wiki/src/contribute/release_process/tails-installer.mdwn

   1 [[!meta title="Releasing tails-installer"]]
   2
   3 [[!toc levels=3]]
   4
   5 The big picture
   6 ===============
   7
   8 Upstream
   9 --------
  10
  11 For this package, "upstream" means, from a Debian packaging
  12 point-of-view, the state of our upstream branches. Let's not pretend we
  13 have not forked liveusb-creator, and admit we are now upstream for our
  14 own version. Thus, from version 4.x on, our fork has been renamed to
  15 tails-installer.
  16
  17 The `master` branch must always be the one that targets current Tails
  18 and possibly *also* earlier Debian releases. At the moment it supports
  19 Debian Jessie, Stretch, Buster and Sid.
  20
  21 But that's not enough, since we also need to put releases out with code
  22 that works on current Debian testing/unstable. Thus, we maintain several upstream
  23 release branches in parallel, each with their own major version number:
  24
  25  * for work and releases that target Jessie and Stretch (and, as long
  26    as compatible, that target Debian testing/unstable as well):
  27    * branch = `master`
  28    * version = `5.*`
  29    * tag = `tails-installer_5.*`
  30
  31 Once we can't support both Jessie, Stretch and Debian testing/unstable
  32 with the same codebase anymore, we'll fork a new upstream release
  33 branch that targets Debian testing, it'll be called
  34 `feature/$codename`, use version `6.*`, etc.
  35
  36 Packaging
  37 ---------
  38
  39 We're using [DEP-14 conventions](http://dep.debian.net/deps/dep14/),
  40 except for our `master` branch which is used for upstream development
  41 targeted at current Tails, as said above. More specifically:
  42
  43 * The `pristine-tar` branch contains the binary delta between DFSG-freed
  44   tarballs and the corresponding tag. It's automatically maintained by
  45   `gbp import-orig`.
  46 * The `debian/sid` branch is used to build the package that we upload to
  47   Debian unstable. The tags on this branch are called `debian/$package_version`,
  48   which is the default when creating them with
  49   `gbp buildpackage --git-sign-tags --git-tag-only`;
  50   in practice this is something like `debian/5.3+dfsg-1`.
  51 * The `debian/$codename-backports` branch is used to prepare packages
  52   that we upload to the official backports repository for Debian `$codename`.
  53   E.g. here we want to have `debian/jessie-backports` soon after the initially
  54   uploaded package reaches Debian testing. The tags on this branch are
  55   also called `debian/$package_version`. In practice this is something
  56   like `debian/5.3+dfsg-1~bpo8+1`.
  57 * The `tails/master` branch is used to prepare packages that we upload
  58   to the Tails APT repo for stable releases, but not to Debian.
  59 * The `tails/$codename` branch is used to prepare packages that we upload
  60   to the Tails APT repo but for Tails based on Debian `$codename`. Again,
  61   these packages will not be uploaded to Debian.
  62 * Additionally, we use `tails/$feature` branches for other
  63   Tails-specific packaging branches.
  64 * The `upstream/4.x+dfsg`, `upstream/5.x+dfsg`, etc. branches are what
  65   we tell `gbp` to use as its "upstream" branch. Make sure to check
  66   them out when setting up the repository for the first time.
  67 * For Ubuntu, we want to support the current Ubuntu version (currently
  68   `yakkety`), the upcoming version (currently `zesty`), and the
  69   current LTS (currently `xenial`).
  70   We do not maintain any Git branches related to Ubuntu releases, as
  71   simply the changelog entries are modified.
  72
  73 Topic branches
  74 --------------
  75
  76 In practice, it's expected that Tails contributors submit bugfix and
  77 feature branches forked off `master`, because they want them part of next
  78 Tails release. Hence, it will happen that code lands into `master` first,
  79 and in turn into a new `5.*` upstream release, before it lands into e.g.
  80 `feature/buster` and in turn into a new `6.*` upstream release.
  81
  82 For how to package topic branches (`bugfix/*` and `feature/*`), see
  83 [[the dedicated page|topic_branch]].
  84
  85 Workflow
  86 ========
  87
  88 Release a new upstream version
  89 ------------------------------
  90
  91 <a id="upstream-prepare"></a>
  92
  93 ### Prepare the environment
  94
  95 The new upstream version should be something like `5.3`, based on the
  96 upstream branch you are building the Debian package for. Adjust and
  97 export:
  98
  99     export NEW_UPSTREAM_VERSION=5.replace_me
 100     export UPSTREAM_DEV_BRANCH=master
 101     export PKG_NAME=tails-installer
 102
 103 <a id="upstream-tag"></a>
 104
 105 ### Tag the new version
 106
 107     git checkout "$UPSTREAM_DEV_BRANCH" && \
 108     ./setup.py build && \
 109        (cd po && \
 110            for po in *.po ; do msgmerge --update "$po" \
 111            "$PKG_NAME.pot" ; done \
 112        ) && \
 113        git commit po -m 'Update POT and PO files.' && \
 114     git tag \
 115        -s "${PKG_NAME}_${NEW_UPSTREAM_VERSION}" \
 116        -m "Releasing Tails Installer $NEW_UPSTREAM_VERSION" && \
 117     git push --tags origin "$UPSTREAM_DEV_BRANCH"
 118
 119 <a id="upstream-tarball"></a>
 120
 121 ### Generate a new upstream tarball
 122
 123     mkdir -p ../tarballs && \
 124     git archive \
 125        --prefix="${PKG_NAME}-${NEW_UPSTREAM_VERSION}/" \
 126        --output="../tarballs/${PKG_NAME}_${NEW_UPSTREAM_VERSION}.tar.gz" \
 127        "$UPSTREAM_DEV_BRANCH"
 128
 129 <a id="tails-package"></a>
 130
 131 Update the Debian package for Tails
 132 -----------------------------------
 133
 134 Checkout the packaging branch, e.g.:
 135
 136         export PKG_NAME=tails-installer
 137         export PACKAGING_BRANCH=tails/master
 138         git checkout "$PACKAGING_BRANCH"
 139
 140 Here we assumed that `tails/master` still supports Debian Sid,
 141 otherwise `PACKAGING_BRANCH` should be `tails/${codename}`.
 142
 143 Merge Debian packaging changes:
 144
 145     git fetch debian && \
 146     codename="${PACKAGING_BRANCH/*\//}" && \
 147     if [ "${codename}" = "master" ]; then
 148         codename=sid
 149     fi && \
 150     git merge "debian/${codename}"
 151
 152 Verify that `debian/gbp.conf` references the correct upstream and Debian (packaging) branches,
 153 and that `pristine-tar` usage is enabled, e.g.:
 154
 155         [DEFAULT]
 156         upstream-branch = upstream/5.x+dfsg
 157         debian-branch = tails/${codename}
 158         debian-tag = tails/%(version)s
 159         pristine-tar = True
 160
 161 Extract the upstream and packaging branch from gbp.conf:
 162
 163         export UPSTREAM_BRANCH=$(gbp config buildpackage.upstream-branch \
 164                              | sed -r -e 's,.*=,,')
 165
 166 Create a DFSG-compatible tarball from the previously created Git
 167 archive and reimport it into the source tree. This merges, into the
 168 `debian-branch` specified in `gbp.conf`, not only the commit that
 169 imported the current DFSG-free upstream tarball into the
 170 `upstream-branch`, but also the corresponding upstream Git history:
 171
 172         mk-origtargz \
 173            -C ../tarballs \
 174            --version "$NEW_UPSTREAM_VERSION+dfsg" \
 175            --copy \
 176            ../tarballs/${PKG_NAME}_${NEW_UPSTREAM_VERSION}.tar.gz && \
 177         gbp import-orig \
 178            --upstream-vcs-tag="${PKG_NAME}_$NEW_UPSTREAM_VERSION" \
 179            ../tarballs/${PKG_NAME}_${NEW_UPSTREAM_VERSION}+dfsg.orig.tar.gz
 180
 181 Update `debian/changelog`:
 182
 183     gbp dch && dch -e
 184
 185 In there, set the appropriate:
 186
 187 * version number, such as `5.3+dfsg-0tails1`; in particular, note that
 188   the Debian revision starts with `-0` for any package meant for the
 189   Tails APT repository, while the first package that will be uploaded
 190   to Debian will have `-1`;
 191 * target release name.
 192
 193 Commit the changelog:
 194
 195     git commit debian/changelog \
 196         -m "$(dpkg-parsechangelog -SSource) ($(dpkg-parsechangelog -SVersion))
 197
 198     Git-Dch: Ignore
 199     "
 200
 201 Make sure that the working environment is clean:
 202
 203     git clean -fdx
 204
 205 Build a new Tails package (use a amd64 chroot that matches the target distribution):
 206
 207     gbp buildpackage
 208
 209 Add a signed tag to the Git repository and push the changes:
 210
 211     gbp buildpackage --git-tag-only --git-sign-tags && \
 212     git push --tags origin "$UPSTREAM_BRANCH" \
 213                     "$PACKAGING_BRANCH" \
 214                     pristine-tar
 215
 216 If you are a member of the Debian pkg-privacy team
 217 --------------------------------------------------
 218
 219 Add the remote:
 220
 221     git remote add debian ssh://git.debian.org/git/pkg-privacy/packages/tails-installer.git
 222
 223 Then push:
 224
 225     git push --tags debian "$UPSTREAM_BRANCH" \
 226                     "$PACKAGING_BRANCH" \
 227                     pristine-tar
 228
 229 Never force push! If `git push` fails you may have to merge back in
 230 e.g. `debian/pristine-tar` into your local `pristine-tar` and push
 231 again. Also push it to `origin`, in that case.
 232
 233 Add the Debian package to Tails
 234 -------------------------------
 235
 236 Sign the package:
 237
 238     debsign $CHANGES_FILE
 239
 240 Upload:
 241
 242     dupload --to tails $CHANGES_FILE
 243
 244 Update the Debian package
 245 -------------------------
 246
 247 This assumes that the latest upstream release has been imported into
 248 a `tails/master` already.
 249
 250 And then, a maintainer of `tails-installer` in Debian updates the
 251 package in sid accordingly, for example:
 252
 253 * check out the `debian/sid` branch
 254 * merge the `tails/master` branch
 255 * bump version to `5.3+dfsg-1`
 256 * build, test and upload to sid
 257 * have gbp create a `debian/5.3+dfsg-1` tag
 258 * push the Debian packaging branch (`debian/sid`) and the new tag
 259
 260 Example for a backport to Jessie:
 261
 262 * check out the `debian/jessie-backports` branch
 263 * merge the `debian/sid` branch
 264 * `dch --bpo` to bump version to `5.3+dfsg-1~bpo8+1`
 265 * build, test and upload to jessie-backports
 266 * have gbp create a `debian/5.3+dfsg-1_bpo8+1` tag
 267 * push the Debian packaging branch (`debian/jessie-backports`) and the new tag
 268
 269 Upload a package to our Ubuntu PPA
 270 ----------------------------------
 271
 272 Team members are allowed to upload a package to our Ubuntu PPA:
 273 <https://launchpad.net/~tails-team/+archive/ubuntu/tails-installer>
 274
 275 You'll need to configure the dput tool to upload to the PPA and put into
 276 `$HOME/.dput.cf` (adjust to use your Launchpad ID):
 277
 278     [ppa-tails-installer]
 279     fqdn = ppa.launchpad.net
 280     method = ftp
 281     incoming = ~tails-team/ubuntu/tails-installer/
 282     login = your_launchpad_id
 283     allow_unsigned_uploads = 0
 284
 285 * checkout the `debian/sid` branch
 286   to build a package for the next Ubuntu release or checkout the
 287   `debian/jessie-backports` branch to build a package for the
 288   current Ubuntu version or current LTS.
 289 * bump version to `5.3+dfsg-0ubuntu1~$codename` using `dch -i`
 290   where `$codename` is the name of the target Ubuntu distribution.
 291 * if it does not exist, rebuild the .orig.tar.gz of the latest version
 292   from pristine-tar (use the latest git log entry to find the version):
 293   `pristine-tar checkout ../tails-installer_5.3+dfsg.orig.tar.gz`
 294 * build a source only package using `debuild -i -uc -us -sa -S`
 295   Once the package has been built, a `.changes` file will be created in
 296   pbuilder's configured destination directory.
 297 * test the package (piuparts, Lintian, etc.)
 298 * sign the corresponding source.changes file
 299   `debsign ../tails-installer_$NEW_UPSTREAM_RELEASE-xxx_source.changes`
 300   Replace "xxx" with the correct version information.
 301   The signature should be made with a key which is registered
 302   at Launchpad as being part of the Tails team.
 303 * Upload to the PPA:
 304   `dput ppa-tails-installer ../tails-installer_$NEW_UPSTREAM_RELEASE+xxx_source.changes`
 305
 306 You will receive an email informing you if the upload was really successful
 307 or if it contained any errors. On success, you should now revert your changes on the
 308 Debian branch using `git reset HEAD --hard`.
 309
 310 Quality assurance for Debian and Ubuntu packages
 311 ------------------------------------------------
 312
 313     Scenario: Installing Tails to a pristine USB drive
 314       Given I have started Debian
 315       And I have a Tails ISO image
 316       When I install the tails-installer package
 317       And I plug USB drive "install"
 318       And I ask Tails Installer to install my Tails ISO image to USB drive "install"
 319       Then my Tails ISO image is installed on USB drive "install"
 320
 321     Scenario: Upgrading an old Tails USB installation from an ISO image
 322       Given I have started Debian
 323       And I have a Tails ISO image
 324       When I install the tails-installer package
 325       And I plug USB drive "upgrade" that has an old Tails installed
 326       And I ask Tails installer to upgrade USB drive "upgrade" with my Tails ISO image
 327       Then my Tails ISO image is installed on USB drive "upgrade"