Tails

#3 Updated by intrigeri 2015-05-29 17:50:27

Here’s my proposal for branching and versioning. I’m putting it on the parent ticket, because otherwise the discussion will be spread among at least Feature #8554, Feature #8555, Feature #8551.

It’s a bit complicated, for many reasons, including but not limited to:

• in practice, upstream work generally targets current Debian stable (or even, as is the case currently, oldstable); while Debian work needs to target Debian sid and testing (and in turn, stable-backports);
• we’re keeping both upstream and Debian Git history, branches and tags in the same Git repository; if it’s too confusing for you and you keep mixing up both sides, please consider using two different repositories, at least locally (and in your local Debian packaging repo, you’ll need to configure a remote that points to your local upstream repo, with a file:// URL; no need to configure anything the other way, quite the contrary, it would only add confusion).

Upstream side of things

The master branch must always be the one that targets current Tails (in order to avoid confusing Tails contributors who don’t need to learn a new Git workflow). 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. So, we’ll be maintaining several upstream release branches in parallel, each with their own major version number:

• for releases that target Wheezy:
  • version = 3.x
  • tag = tails-installer_3.x
• 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.x
  • tag = tails-installer_4.x
• once we can’t anymore support both Jessie and testing/sid with the same codebase, we’ll fork a new upstream release branch that target Stretch, it’ll be called feature/stretch, use version 5.x, etc.

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.x upstream release, before it lands into feature/jessie and in turn into a new 4.x upstream release. So we’ll have to merge 3.x release tags into feature/jessie from time to time, and then to put out a new 4.x upstream release, so that it can eventually 1. be integrated into Tails/Jessie ISO builds; and 2. go into Debian proper.

Note that the branches targeting a version of Debian that’s newer than the one current Tails is based on (e.g. feature/jessie is the only such branch right now) must only contain, on top of current master:

1. code changes needed to port to that newer Debian (e.g. currently feature/jessie has been ported to UDisks2);
2. merge commits created when merging new 3.x release tags into feature/jessie;
3. whatever boilerplate (e.g. changelog) that embed hard-coded version numbers and needs updating when releasing 4.x.

Debian side of things

Here, we look at things from a slightly different perspective. Here, the focus is on easing maintenance of the package(s) in Debian, not on making things simpler for Tails contributors: the only Tails contributors who need to touch these bit are the release managers, and they can live with a branch rename just fine, as long as it’s properly documented (well, we also have documentation for those willing to quickly package their topic branch the dirty way, that will need to be adjusted as well, but AFAIK only Alan has ever used that procedure, so we should be fine).

Branches, version numbers and tags:

• We’re using DEP-14 conventions (so most of what follows is just rephrasing it in our own terms, with specific examples), except:
  • the master branch is used for upstream development targetted at current Tails, as said above
• The pristine-tar branch contains the binary delta between DFSG-freed tarballs and the corresponding tag. It’s automatically maintained by gbp import-orig, once gbp has been instructed to use pristine-tar.
• The debian/sid branch is the one we 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 will be something like debian/4.0+dfsg-1.
• The debian/$codename-backports branch is the one 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 will be something like debian/4.0+dfsg-1~bpo8+1.
• The tails/$codename branch is the one used to prepare packages that we upload to the Tails APT repo, but not to Debian — e.g. 3.x as currently used on Tails/Wheezy will never be uploaded to Debian. It’s actually our current debian branch, simply renamed to tails/wheezy. And our current debian_feature-jessie branch will be renamed to tails/jessie.
• Additionally, we’ll use tails/$feature branches for other Tails-specific packages. E.g. our current debian_feature-gtk3 branch will be renamed tails/feature/gtk3. Note that version numbers there must always be smaller to the one that are used in Debian, see examples below.
• The upstream/3.x+dfsg, upstream/4.x+dfsg, etc. branches are what we tell gbp to use as its “upstream” branch. E.g. on the debian/sid and debian/jessie-backports branches, debian/gbp.conf will have upstream-branch = upstream/4.x+dfsg; and on the tails/wheezy branch, as long as Tails is based on Wheezy, debian/gbp.conf will instead say upstream-branch = upstream/3.x+dfsg. The tags living on those upstream/* branches are automatically created by gbp import-orig, but it needs to be configured to call them upstream/$repacked_upstream_version (which ends with +dfsg) in all packaging (debian/* and tails/*) branches.

Example workflow

1. Tails contributors get bugfixes and features merged into master
2. Tails freeze time, so the RM:
   1. puts upstream 3.25 out, and tags it (on the master branch)
   2. runs git archive, that creates a 3.25 tarball
   3. runs mk-origtargz, that creates a 3.25+dfsg tarball
   4. runs gbp import-orig on the tails/wheezy branch, that imports stuff into the upstream/3.x+dfsg branch and creates a upstream/3.25+dfsg tag there
   5. builds and uploads to Tails APT repo
3. a Tails developer updates the Jessie package accordingly:
   1. checks out the feature/jessie branch
   2. merges the tails-installer_3.25 tag
   3. releases 4.03 and tags it
   4. runs git archive, that creates a 4.03 tarball
   5. runs mk-origtargz, that creates a 4.03+dfsg tarball
   6. checks out the tails/jessie branch
   7. runs gbp import-orig, that imports stuff into the upstream/4.x+dfsg branch (because gbp.conf says upstream-branch = upstream/4.x+dfsg) and creates a upstream/4.03+dfsg tag there
   8. builds and uploads to Tails feature-jessie APT suite
   9. has gbp create a tails/4.03+dfsg-0tails1 tag (note the -0 that makes it smaller that what will come later:)
4. a maintainer of tails-installer in Debian updates the package in sid accordingly:
   1. checks out the debian branch
   2. merges the tails/jessie branch
   3. bumps version to 4.03+dfsg-1
   4. builds and uploads to sid
   5. has gbp create a debian/4.03+dfsg-1 tag
5. wait for the migration to Debian testing
6. a maintainer of tails-installer in Debian updates the package in jessie-backports accordingly:
   1. checks out the debian/jessie-backports branch
   2. merges the debian/4.03+dfsg-1 tag
   3. dch --bpo to change version to 4.03+dfsg-1~bpo8+1
   4. builds and uploads to jessie-backports
   5. has gbp create a debian/4.03+dfsg-1_bpo8+1 tag
7. optionally, Tails code or APT repo is changed so that ISO images get the package from official backports

Note that “a Tails developer updates the Jessie package accordingly” can possibly be skipped. In that case:

• “a maintainer of tails-installer in Debian updates the package in sid accordingly” implies a little bit more work
• Tails/Jessie will ship slightly obsolete code until the package is uploaded to sid, reaches testing, and then is uploaded to backports; unless Tails/Jessie can simply install the package from Debian testing or sid as-is, which would be best :)