path: root/wiki/src/contribute/release_process/liveusb-creator.mdwn
diff options
Diffstat (limited to 'wiki/src/contribute/release_process/liveusb-creator.mdwn')
1 files changed, 170 insertions, 57 deletions
diff --git a/wiki/src/contribute/release_process/liveusb-creator.mdwn b/wiki/src/contribute/release_process/liveusb-creator.mdwn
index 1afa3d0..1f5c1f4 100644
--- a/wiki/src/contribute/release_process/liveusb-creator.mdwn
+++ b/wiki/src/contribute/release_process/liveusb-creator.mdwn
@@ -1,103 +1,191 @@
[[!meta title="Releasing liveusb-creator"]]
-[[!toc levels=1]]
+[[!toc levels=3]]
-Upstream and packaging
+The big picture
For this package, "upstream" means, from a Debian packaging
-point-of-view, the state of our master branch. Let's not pretend we
+point-of-view, the state of our upstream branches. Let's not pretend we
have not forked liveusb-creator, and admit we are now upstream for our
own version.
-Still, most of the time, we will be releasing -N "Debian"-specific
-packages, that really are packaged Git snapshots, rather than new
-"upstream" releases. Only when we really need it, we will update the
-"orig" tarball from our master branch.
+The `master` branch must always be the one that targets current Tails.
+That's what we have always done, and right
+now `master` is indeed targeting Wheezy.
+But that's not enough, since we also need to put releases out with code
+that works on current Debian testing/sid. Thus, we maintain several upstream
+release branches in parallel, each with their own major version number:
+ * for releases that target Wheezy:
+ * version = `3.*`
+ * tag = `tails-installer_3.*`
+ * for work and releases that target Jessie (and, as long as compatible,
+ that target testing/sid as well):
+ * branch = feature/jessie (that's what we've been doing so far)
+ * version = `4.*`
+ * tag = `tails-installer_4.*`
+Once we can't support both Jessie and testing/sid with the same
+codebase anymore, we'll fork a new upstream release branch that targets Stretch,
+it'll be called feature/stretch, use version `5.*`, etc.
+We're using [DEP-14 conventions](,
+except for our `master` branch which is used for upstream development
+targetted at current Tails, as said above. More specifically:
+* The `pristine-tar` branch contains the binary delta between DFSG-freed
+ tarballs and the corresponding tag. It's automatically maintained by
+ `gbp import-orig`.
+* The `debian/sid` branch is used to build the package that we upload to
+ Debian unstable. The tags on this branch are called `debian/$package_version`,
+ which is the default when creating them with
+ `gbp buildpackage --git-sign-tags --git-tag-only`;
+ in practice this is something like `debian/4.0+dfsg-1`.
+* The `debian/$codename-backports` branch is used to prepare packages
+ that we upload to the official backports repository for Debian `$codename`.
+ E.g. here we want to have `debian/jessie-backports` soon after the initially
+ uploaded package reaches Debian testing. The tags on this branch are also called
+ `debian/$package_version`. In practice this is something like
+ `debian/4.0+dfsg-1~bpo8+1`.
+* The `tails/$codename` branch is used to prepare packages that we upload
+ to the Tails APT repo, but not to Debian -- e.g. `3.*` as currently used on
+ Tails/Wheezy will never be uploaded to Debian.
+* Additionally, we use `tails/$feature` branches for other Tails-specific packaging branches.
+* The `upstream/3.x+dfsg`, `upstream/4.x+dfsg`, etc. branches are what we tell `gbp`
+ to use as its "upstream" branch.
Topic branches
+In practice, it's expected that Tails contributors submit bugfix and
+feature branches forked off master, because they want them part of next
+Tails release. Hence, it will happen that code lands into master first,
+and in turn into a new `3.*` upstream release, before it lands into
+`feature/jessie` and in turn into a new `4.*` upstream release.
-For how to package `bugfix` and `feature`, see
+For how to package topic branches (`bugfix/*` and `feature/*`), see
[[the dedicated page|topic_branch]].
-Tidy up upstream source
-Merge new Fedora's changes if needed:
+Release a new upstream version
- git checkout master
- git remote add fedora git://
- git fetch fedora
- git remote add lmacken
- git fetch lmacken
+<a id="upstream-prepare"></a>
-Then see if they have tagged a release that we haven't merged yet,
-and merge the release tag if needed (in advance before the freeze,
-and following our usual review'n'merge process).
+### Prepare the environment
-Do extra changes if needed.
+The new upstream version should be something like `3.14`, based on the
+upstream branch you are building the Debian package for. Adjust and
-Generate a new upstream tarball
+ export NEW_UPSTREAM_VERSION=3.replace_me
+ export UPSTREAM_DEV_BRANCH=master
-**If needed** (that is, basically if dpkg-source complains, when
-running git-buildpackage below, that it cannot represent changes in
-binary files), generate a new upstream tarball from the tip of our
-master branch.
+<a id="upstream-tag"></a>
-The new upstream version should be something like `3.11.6+tails1`:
-only increment the number after `+tails` if the new release is still
-based on Fedora's 3.11.6. Else, set the part before `+tails` to the
-new Fedora release's version number, and reset the right side to
+### Tag the new version
- git archive --prefix=git/ \
- --output=../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION.orig.tar.xz \
- master
+ git checkout "$UPSTREAM_DEV_BRANCH" && \
+ ./ build && \
+ (cd po && \
+ for po in *.po ; do msgmerge --update "$po" \
+ liveusb-creator.pot ; done \
+ ) && \
+ git commit po -m 'Update POT and PO files.' && \
+ git tag \
+ -s "tails-installer_$NEW_UPSTREAM_VERSION" \
+ -m "Releasing Tails Installer $NEW_UPSTREAM_VERSION" && \
+ git push origin "$UPSTREAM_DEV_BRANCH" && \
+ git push origin --tags
-Update the Debian package
+<a id="upstream-tarball"></a>
+### Generate a new upstream tarball
+ mkdir -p ../tarballs && \
+ git archive \
+ --prefix="liveusb-creator-$NEW_UPSTREAM_VERSION/" \
+ --output="../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION.tar.gz" \
+<a id="tails-package"></a>
+Update the Debian package for Tails
+Checkout the packaging branch, that would be `tails/wheezy` or `tails/jessie`,
+for example:
+ export PACKAGING_BRANCH=tails/jessie
+ git checkout "$PACKAGING_BRANCH"
+Verify that `debian/gbp.conf` references the correct upstream and Debian (packaging) branches,
+and that `pristine-tar` usage is enabled, e.g.:
+ upstream-branch = upstream/4.x+dfsg
+ debian-branch = tails/jessie
+ pristine-tar = True
-Checkout the branch with Debian package specifics:
+Extract the upstream and packaging branch from gbp.conf:
- git checkout debian
+ export UPSTREAM_BRANCH=`gbp config buildpackage.upstream-branch | sed -r -e 's,.*=,,'`
-Merge upstream changes:
+Create a DFSG-compatible tarball from the previously created Git
+archive and reimport it into the source tree. This merges, into the
+`debian-branch` specified in `gbp.conf`, not only the commit that
+imported the current DFSG free upstream tarball into the
+`upstream-branch`, but also the corresponding upstream Git history:
- git merge master
+ mk-origtargz \
+ -C ../tarballs \
+ --version "$NEW_UPSTREAM_VERSION+dfsg" \
+ --copy \
+ ../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION.tar.gz && \
+ gbp import-orig \
+ --upstream-vcs-tag="tails-installer_$NEW_UPSTREAM_VERSION" \
+ ../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION+dfsg.orig.tar.gz
Update `debian/changelog`:
gbp dch && dch -e
-(Do not forget to set the appropriate release.)
+In there, set the appropriate:
+* version number, such as `4.3+dfsg-0tails1`; in particular, note that
+ the Debian revision starts with `-0` for any package meant for the
+ Tails APT repository, while the first package that will be uploaded
+ to Debian will have `-1`;
+* target release name.
+Commit the changelog:
git commit debian/changelog -m "$(head -n 1 debian/changelog | sed -e 's,).*,),')"
-Build a new Debian package (use a Wheezy/i386 chroot):
+Build a new Tails package (use a i386 chroot that matches the target distribution):
gbp buildpackage
-If `gbp buildpackage` complains about a missing `upstream/$VERSION`,
-then manually download the corresponding tarball (which can be found
-in our Debian repo unless upstream just had a new release) and place
-it in `..`, and then re-run the command with `--git-no-pristine-tar`.
Add a signed tag to the Git repository and push the changes:
gbp buildpackage --git-tag-only --git-sign-tags && \
- git push origin master:master \
- debian:debian && \
- git push --tags
-(Make sure both `master` and `debian` are pushed.)
+ git push origin "$UPSTREAM_BRANCH" \
+ pristine-tar && \
+ git push origin --tags
Add the Debian package to Tails
Sign the package:
@@ -106,3 +194,28 @@ Sign the package:
dupload --to tails $CHANGES_FILE
+Update the Debian package
+This assumes that the latest upstream release has been imported into
+a Tails packaging branch (e.g. `tails/jessie`) already.
+And then, a maintainer of `tails-installer` in Debian updates the
+package in sid accordingly, for example:
+* check out the `debian/sid` branch
+* merge the `tails/jessie` branch
+* bump version to `4.3+dfsg-1`
+* build, test and upload to sid
+* have gbp create a `debian/4.3+dfsg-1` tag
+* push the Debian packaging branch (`debian/sid`) and the new tag
+Example for a backport to Jessie:
+* check out the `debian/jessie-backports` branch
+* merge the `debian/sid` branch
+* `dch --bpo` to bump version to `4.3+dfsg-1~bpo8+1`
+* build, test and upload to jessie-backports
+* have gbp create a `debian/4.3+dfsg-1_bpo8+1` tag
+* push the Debian packaging branch (`debian/jessie-backports`) and the new tag