The big picture

Upstream

For this package, "upstream" means, from a Debian packaging point-of-view, the state of our upstream branches. Tails developers are the upstream for this forked version of liveusb-creator, which, from version 4.x on, has been renamed to tails-installer.

The master branch must always be the one that targets current Tails. At the moment it supports Tails based on Debian Stretch, Buster and Sid.

But that's not enough, since we also need to put releases out with code that works on current Debian testing/unstable. Thus, we maintain several upstream release branches in parallel, each with their own major version number:

  • for work and releases that target Stretch (and, as long as compatible, that target Debian testing/unstable as well):
    • branch = master
    • version = 5.*
    • tag = tails-installer_5.*

Once we can't support both Stretch and Debian testing/unstable with the same codebase anymore, we'll fork a new upstream release branch that targets Debian testing, it'll be called feature/$codename (i.e. feature/bullseye), use version 6.*, etc.

Packaging

We're using DEP-14 conventions, except for our master branch which is used for upstream development targeted 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 tails/master branch is used to prepare packages that we upload to the Tails APT repo for Tails stable releases, but not to Debian.
  • The tails/$codename branch is used to prepare packages that we upload to the Tails APT repo but for (non-stable) Tails based on Debian $codename. Again, these packages will not be uploaded to Debian.
  • Additionally, we use tails/$feature branches for other Tails-specific packaging branches.
  • The upstream/4.x+dfsg, upstream/5.x+dfsg, etc. branches are what we tell gbp to use as its "upstream" branch. Make sure to check them out when setting up the repository for the first time.

Branches that are not used anymore because the package was dropped from Debian, but stay in the packaging repository for reference:

  • The debian/sid branch was used to build the package that we uploaded to Debian unstable. The tags on this branch were called debian/$package_version.
  • The debian/$codename-backports branch was used to prepare packages that were upload to the official backports repository for Debian $codename.
  • We did not maintain any Git branches related to Ubuntu releases, as simply the changelog entries are modified and the releases tagged.

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 5.* upstream release, before it lands into e.g. feature/buster and in turn into a new 6.* upstream release.

For how to package topic branches (bugfix/* and feature/*), see the dedicated page.

Workflow

Release a new upstream version

Prepare the environment

The new upstream version should be something like 5.3, based on the upstream branch you are building the Debian package for. Adjust and export:

export NEW_UPSTREAM_VERSION=5.replace_me
export UPSTREAM_DEV_BRANCH=master
export PKG_NAME=tails-installer

Tag the new version

git checkout "$UPSTREAM_DEV_BRANCH" && \
./setup.py build && \
   (cd po && \
       for po in *.po ; do msgmerge --update "$po" \
       "$PKG_NAME.pot" ; done \
   ) && \
   git commit po -m 'Update POT and PO files.' && \
git tag \
   -s "${PKG_NAME}_${NEW_UPSTREAM_VERSION}" \
   -m "Releasing Tails Installer $NEW_UPSTREAM_VERSION" && \
git push --tags origin "$UPSTREAM_DEV_BRANCH"

Generate a new upstream tarball

mkdir -p ../tarballs && \
git archive \
   --prefix="${PKG_NAME}-${NEW_UPSTREAM_VERSION}/" \
   --output="../tarballs/${PKG_NAME}_${NEW_UPSTREAM_VERSION}.tar.gz" \
   "$UPSTREAM_DEV_BRANCH"

Update the Debian package for Tails

Checkout the packaging branch, e.g.:

export PKG_NAME=tails-installer
export PACKAGING_BRANCH=tails/master
git checkout "$PACKAGING_BRANCH"

Here we assumed that tails/master still supports Debian Sid, otherwise PACKAGING_BRANCH should be tails/${codename}.

Merge Debian packaging changes:

git fetch debian && \
codename="${PACKAGING_BRANCH/*\//}" && \
if [ "${codename}" = "master" ]; then
    codename=sid
fi && \
git merge "debian/debian/${codename}"

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/5.x+dfsg
debian-branch = tails/${codename}
debian-tag = tails/%(version)s
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/${PKG_NAME}_${NEW_UPSTREAM_VERSION}.tar.* && \
gbp import-orig \
   --upstream-vcs-tag="${PKG_NAME}_$NEW_UPSTREAM_VERSION" \
   ../tarballs/${PKG_NAME}_${NEW_UPSTREAM_VERSION}+dfsg.orig.tar.*

Update debian/changelog:

gbp dch && dch -e

The raw data compiled by gbp dch must be edited to convey information that's relevant and self-contained for a Debian audience (clearly our upstream commit messages are not written with this audience in mind). For example, the 5.0.4+dfsg-0tails1 changelog entry is pretty good, but things like "Apply awful hack to fix Tails#14755" are meaningless for a Debian audience.

Also:

  • Set the appropriate version number, such as 5.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;
  • Set the appropriate target release name.
  • Make sure every Tails ticket ID is of the form Tails#NNNNN, not #NNNNN and definitely not Closes: #NNNNN.

Commit the changelog:

git commit debian/changelog \
    -m "$(echo "$(dpkg-parsechangelog -SSource) ($(dpkg-parsechangelog -SVersion))\n\nGit-Dch: Ignore\n")"

Make sure that the working environment is clean:

git clean -fdx

Build a new Tails package (use a amd64 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 --tags origin "$UPSTREAM_BRANCH" \
                "$PACKAGING_BRANCH" \
                pristine-tar

Add the Debian package to Tails

Sign the package:

debsign $CHANGES_FILE

Upload:

dupload --to tails $CHANGES_FILE