[[!meta title="Releasing liveusb-creator"]]
[[!toc levels=3]]
The big picture
===============
Upstream
--------
For this package, "upstream" means, from a Debian packaging
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.
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.
Packaging
---------
We're using [DEP-14 conventions](http://dep.debian.net/deps/dep14/),
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 topic branches (`bugfix/*` and `feature/*`), see
[[the dedicated page|topic_branch]].
Workflow
========
Release a new upstream version
------------------------------
### Prepare the environment
The new upstream version should be something like `3.14`, based on the
upstream branch you are building the Debian package for. Adjust and
export:
export NEW_UPSTREAM_VERSION=3.replace_me
export UPSTREAM_DEV_BRANCH=master
### Tag the new version
git checkout "$UPSTREAM_DEV_BRANCH" && \
./setup.py 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
### 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" \
"$UPSTREAM_DEV_BRANCH"
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.:
[DEFAULT]
upstream-branch = upstream/4.x+dfsg
debian-branch = tails/jessie
pristine-tar = True
Extract the upstream and packaging branch from gbp.conf:
export UPSTREAM_BRANCH=`gbp config buildpackage.upstream-branch | sed -r -e 's,.*=,,'`
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:
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
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 Tails package (use a i386 chroot that matches the target distribution):
gbp buildpackage
Add a signed tag to the Git repository and push the changes:
gbp buildpackage --git-tag-only --git-sign-tags && \
git push origin "$UPSTREAM_BRANCH" \
"$PACKAGING_BRANCH" \
pristine-tar && \
git push origin --tags
Add the Debian package to Tails
-------------------------------
Sign the package:
debsign $CHANGES_FILE
Upload:
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