1 [[!meta title="Release process"]]
5 See the [[release_schedule]].
10 Export the following environment variables to be able to copy'n'paste
11 the scripts snippets found on this page:
13 * `VERSION`: the version number of the release being prepared.
14 * `export TAG=$(echo "$VERSION" | sed -e 's,~,-,')`
15 * `PREVIOUS_VERSION`: the version number of the previous release.
16 * `MAJOR_RELEASE`: set to 1 if preparing a major release, to 0 else
17 * `ISOS`: the directory where one stores `tails-i386-*`
18 sub-directories like the ones downloaded with BitTorrent.
19 * `MASTER_CHECKOUT`: a checkout of the `master` branch of the main
21 * `RELEASE_CHECKOUT`: a checkout of the branch of the main Tails Git
22 repository used to prepare the release (`stable` or `testing`).
23 * `TAILS_SIGNATURE_KEY=0D24B36AA9A2A651787876451202821CBE2CD9C1`
24 * `IUK_CHECKOUT`: a checkout of the relevant tag of the `iuk`
26 * `PERL5LIB_CHECKOUT`: a checkout of the relevant tag of the
27 `perl5lib` Git repository.
32 The [[contribute/working_together/roles/release_manager]] role
33 documentation has more tasks that should be done early enough.
35 Update Iceweasel preferences
36 ----------------------------
38 * update `extensions.adblockplus.currentVersion` in
39 `config/chroot_local-includes/etc/iceweasel/profile/user.js`
41 Coordinate with Debian security updates
42 ---------------------------------------
44 See [[release_process/Debian_security_updates]].
46 Select the right branch
47 =======================
49 For a major release, the `devel` branch should be merged into the `testing`
50 branch and changes should be made from there.
52 From minor releases, work should happen in `stable`.
60 Patterns are stored in
61 `config/chroot_local-includes/etc/iceweasel/profile/adblockplus/`.
64 2. Open *Tools* → *Addons*
65 3. Select *Adblock Plus* in extensions
66 4. Open *Preferences* → *Filter preferences…*
67 5. For each filters, click *Actions* → *Update filters*
69 7. Copy the `.mozilla/firefox/default/adblockplus/patterns.ini` from
70 this Iceweasel instance to the
71 `config/chroot_local-includes/etc/iceweasel/profile/adblockplus`
72 directory in the Tails Git checkout.
75 git commit -m 'Update AdBlock Plus patterns.' \
76 config/chroot_local-includes/etc/iceweasel/profile/adblockplus/patterns.ini`
78 Upgrade bundled binary Debian packages
79 --------------------------------------
81 That is: make sure the bundled binary Debian packages contain
82 up-to-date localization files.
84 For each bundled Debian package, run the included `import-translations`
85 script if one exists, or copy updated PO files from the
86 Transifex branches of `git://git.torproject.org/translation.git` (e.g.
87 `whisperback_completed`). Skip PO files for [[translation teams that use
88 Git|contribute/how/translate#translate]]. Verify and commit.
90 Then check the PO files [[using i18nspector|contribute/l10n_tricks]].
91 Correct all the errors that are not in the ignored list of
92 [[`check_po.sh`|contribute/l10n_tricks]]. Commit the changes if any.
94 Then see the relevant release processes:
100 * [[persistence-setup]]
103 * see release process on
104 <https://git-tails.immerda.ch/whisperback/plain/HACKING>
105 * build a debian package
106 * upload it to [[APT repository]]
111 Pull updated translations for languages translated in Transifex:
113 ./import-translations
115 Refresh the code PO files:
117 ./refresh-translations
119 Commit the result, including new PO files:
121 git add po && git commit -m 'Update PO files.'
126 If we are at freeze time for a major release:
128 * Merge the `master` Git branch into `devel`.
129 * Merge the `devel` Git branch into `testing`.
130 * Reset the `testing` APT suite to the state of the `devel` one, as
131 documented on [[contribute/APT_repository#workflow-freeze]].
133 Else, if we are at freeze time for a point-release:
135 * Merge the `master` Git branch into `stable`.
140 Remove the placeholder entry for next release in `debian/changelog`,
143 ./release $VERSION $PREVIOUS_VERSION
145 This populates the Changelog with the Git log entries.
147 Then, launch an editor for the needed cleanup of the result:
151 Then, gather other useful information from every custom bundled
152 package's own Changelog (Greeter, Persistent Volume Assistant, etc.).
156 git commit debian/changelog -m "Update changelog for $VERSION."
163 Merge `master` into the branch used for the release:
165 git fetch origin && git merge origin/master
169 If preparing a RC, skip this part.
171 In the branch used to build the release, update the `wiki/src/inc/*` files to
172 match the *version number* and *date* of the new release. Set the date
173 at least 24 hours in the future! Between tests and mirror synchronization,
174 the build will not be released on the same day. Try to make sure it
175 matches the date of the future signature.
177 RELEASE_DATE='June 26, 2013'
179 echo "$VERSION" > wiki/src/inc/stable_i386_version.html
180 echo "$RELEASE_DATE" > wiki/src/inc/stable_i386_date.html
181 $EDITOR wiki/src/inc/*.html
183 git commit wiki/src/inc/ -m "Update version and date for $VERSION."
185 ### features and design documentation
187 Read the Changelog carefully, and update [[doc/about/features]]
192 git grep PENDING wiki/src/contribute/design*
194 ... and remove the `PENDING-FOR-N.M` warnings.
199 Refresh the website PO files and commit the ones corresponding to
200 pages that were added or changed accordingly to changes coming with
201 the new release. This e.g. ensures that the RC call for translation
202 points translators to up-to-date PO files:
204 ./build-wiki && git add wiki/src && git commit -m 'Update website PO files.'
206 If at freeze time, ask on tails-l10n that someone checks the PO files
207 of `po/` and of the website [[using
208 `check_po.sh`|contribute/l10n_tricks]], and corrects all the errors.
210 Tag the release in Git
211 ======================
213 git tag -u "$TAILS_SIGNATURE_KEY" -m "tagging version ${VERSION}" "${TAG}"
216 (Pushing the tag is needed so that the APT repository is updated, and
217 the Tails APT configuration works at build and boot time. It might be
218 premature, as testing might reveal critical issues, but this is
219 a signed tag, so it can be overridden later. Yes, there is room for
222 Prepare the versioned APT suite
223 ===============================
225 Follow the [[post-tag|contribute/APT_repository#workflow-post-tag]] APT
226 repository documentation.
231 Build the almost-final image
232 ----------------------------
234 [[Build images|contribute/build]] and carefully read the build logs to
235 make sure nothing bad happened.
240 1. Build an ISO image.
242 1. Boot this DVD **on bare metal**.
243 1. Add `profile` to the kernel command-line.
244 1. Three minutes after `iceweasel` has been loaded, retrieve the new sort
245 file from `/var/log/boot-profile`.
246 1. Copy the new sort file to `config/binary_rootfs/squashfs.sort`.
248 1. Inspect the Git diff (including diff stat), apply common sense.
249 1. `git commit -m 'Updating SquashFS sort file' config/binary_rootfs/squashfs.sort`
251 Build the final image
252 ---------------------
254 Then all included files should be up-to-date and the versioned APT
255 suite should be ready, so it is time to:
257 * tag the release *again*, with all included files in
259 * build the final image!
261 <a id="prepare-iuk"></a>
263 Build the Incremental Upgrade Kits
264 ----------------------------------
266 Skip this step when preparing a major release.
268 Use `tails-create-iuk` to build an IUK for the previous stable release
269 and (if applicable) the last RC for the version being released. Example:
271 sudo su -c "cd $IUK_CHECKOUT && \
272 PERL5LIB=\"$PERL5LIB_CHECKOUT/lib\" \
273 ./bin/tails-create-iuk \
274 --squashfs-diff-name \"$VERSION.squashfs\" \
275 --old-iso \"$ISOS/tails-i386-$PREVIOUS_VERSION/tails-i386-$PREVIOUS_VERSION.iso\" \
276 --new-iso \"$ISOS/tails-i386-$VERSION/tails-i386-$VERSION.iso\" \
277 --outfile \"$ISOS/Tails_i386_${PREVIOUS_VERSION}_to_${VERSION}.iuk\""
279 Note that developer tools for creating IUK and upgrade-description
280 files were only tested on Debian sid. It should hopefully work well on
281 Wheezy too, but I would not even try to use it on Squeeze.
283 <a id="prepare-upgrade-description-files"></a>
285 Prepare upgrade-description files
286 ---------------------------------
288 Do **not** skip this step when preparing a major release.
290 1. Prepare upgrade-description files (see the [[upgrade-description
292 specification|contribute/design/incremental_upgrades#upgrade-description-files]]
293 for details). The idea is to:
295 * update (create if needed) an upgrade-description file for every
296 *previous* supported release (e.g. N~rc1, N-1, N-1~rc2) that replaces
297 all existing upgrade paths with the path to the version being
299 * create a new upgrade-description for the version being released,
300 that expresses that *no* upgrade is available for that one yet.
302 This is what `tails-iuk-generate-ugrade-description-files` tool
305 cd $IUK_CHECKOUT && \
306 ./bin/tails-iuk-generate-upgrade-description-files \
307 --version "$VERSION" \
308 --iso "$ISOS/tails-i386-$VERSION/tails-i386-$VERSION.iso" \
309 --previous-version "$PREVIOUS_VERSION" \
310 --previous-version "${VERSION}-rc1" \
312 --release-checkout "$RELEASE_CHECKOUT" \
313 --major-release "$MAJOR_RELEASE"
316 * The `--iuks` argument must point to the directory where the IUKs
317 generated at the previous step are stored.
318 * At least the last stable release and the previous release
319 candidates for the version being released must be passed to
320 `--previous-version`.
321 * A few (say, 2 or 3) older versions must be passed with
322 `--previous-version`, so that users who skipped a release or two
323 are directly informed of the new one.
325 1. Create an armoured detached signature for each created or modified
326 upgrade-description file.
328 1. Rename each detached signature to `.pgp`:
330 find "$RELEASE_CHECKOUT/wiki/src/upgrade/" -type f \
331 -name upgrades.yml.asc -exec rename 's,\.asc$,.pgp,' {} \;
333 1. Add and commit the upgrade-description files and their detached
334 signatures to the Git branch used to prepare the release (`stable`
337 1. Check the syntactic correctness of all upgrade-description files:
339 ./bin/tails-iuk-check-upgrade-description-file \
340 ${RELEASE_CHECKOUT}/wiki/src/upgrade/v1/*/*/*/*/upgrades.yml
342 Generate the OpenPGP signatures and Torrents
343 ============================================
345 First, create a directory with a suitable name and go there:
347 mkdir "$ISOS/tails-i386-$VERSION" && cd "$ISOS/tails-i386-$VERSION"
349 Second, copy the built image to this brand new directory.
352 mv *.iso "tails-i386-$VERSION.iso"
354 Third, generate detached OpenPGP signatures for the image to be
355 published, in the same directory as the image and with a `.sig`
358 gpg --armor --default-key "$TAILS_SIGNATURE_KEY" --detach-sign *.iso
359 rename 's,\.asc$,.sig,' *.asc
361 Fourth, go up to the parent directory, create a `.torrent` file and
362 check the generated `.torrent` files metainfo:
365 mktorrent -a 'http://torrent.gresille.org/announce' "tails-i386-${VERSION}" && \
366 btshowmetainfo tails-i386-$VERSION.torrent
368 Fifth, generate detached OpenPGP signatures for every published
371 gpg --armor --default-key "$TAILS_SIGNATURE_KEY" --detach-sign \
372 tails-i386-$VERSION.torrent && \
373 mv tails-i386-$VERSION.torrent.{asc,sig}
381 Verify that the current source for Firefox is still the same we've
382 used when preparing our custom Iceweasel package: e.g. FF17.0.8 got
383 re-tagged and re-uploaded at the last minute, due to a test failure.
385 Better catch this before people spend time doing manual tests.
387 ## Announce, seed and test the Torrents
389 Announce and seed the Torrents.
391 Test them with a BitTorrent client running in a different place.
393 ## Download and seed image from lizard
395 scp tails-i386-$VERSION.torrent bittorrent.lizard:
396 ssh bittorrent.lizard transmission-remote --add tails-i386-$VERSION.torrent
398 Publish the ISO over HTTP
399 -------------------------
401 Upload the images to the primary rsync mirror. Best practice is to first
402 let bittorrent.lizard download the image, and then copy it from there to
405 ssh lizard.tails.boum.org \
407 bittorrent.lizard:/var/lib/transmission-daemon/downloads/tails-i386-$VERSION \
409 # set DIST to either 'testing' (for RC:s) or 'stable' (for actual releases)
410 ssh rsync.lizard << EOF
411 chown -R root:rsync_tails tails-i386-$VERSION
412 chmod -R u=rwX,go=rX tails-i386-$VERSION
413 sudo mv tails-i386-$VERSION /srv/rsync/tails/tails/$DIST/
416 Update the time in `project/trace` file on the primary rsync mirror
417 and on the live wiki (even for a release candidate):
419 TRACE_TIME=$(date +%s) &&
420 echo $TRACE_TIME | ssh rsync.lizard "cat > /srv/rsync/tails/tails/project/trace" && \
421 [ -n "$MASTER_CHECKOUT" ] && \
422 echo $TRACE_TIME > "$MASTER_CHECKOUT/wiki/src/inc/trace" &&
424 cd "$MASTER_CHECKOUT" && \
425 git commit wiki/src/inc/trace -m "Updating trace file after uploading $VERSION."
428 <a id="publish-iuk"></a>
433 Same as for the ISO, but the IUK should land into
434 `/srv/rsync/tails/tails/$DIST/iuk/`.
436 Wait for the HTTP mirrors to catch up
437 -------------------------------------
439 Wait for the next rsync pull.
441 Make sure every webserver listed in the `dl.amnesia.boum.org` round
442 robin pool has the new version. Drop those that are lagging behind and
443 notify their administrators.
445 Test downloading the ISO and IUK over HTTP.
450 1. Set up a Gobby document and copy the [[test
451 suite|contribute/release_process/test]] in it.
452 1. Email <tails@boum.org> to announce that tests may start:
453 - make it clear what's the deadline
454 - make it clear where and how you expect to get feedback
456 - attach the `.packages` file
457 1. Make sure someone is committed to run the automated test suite.
458 1. Make sure that enough people are here to run the tests, that they
459 report their results in due time, and that they make it clear when
460 they're leaving for good.
462 While this happens, the release manager should prepare for the next
463 steps. Please read on!
465 Update the website and Git repository
466 =====================================
468 In order to get any new documentation into the website, merge either
469 `stable` or `testing` (depending on which release you just did) into
472 Rename the `.packages` file to remove the `.iso` part of its name.
474 If preparing a final release, copy the `.iso.sig`, `.packages`,
475 `.torrent` and `.torrent.sig` files into the Git repository's
476 `wiki/src/torrents/files/` directory and remove the one for the
477 previous release (including any RCs). If preparing an RC, only copy
480 If preparing a final release, generate the SHA-256 hash of every image
481 to be released in `inc/*`:
483 sha256sum $ISOS/tails-i386-$VERSION/tails-i386-$VERSION.iso | \
484 cut -f 1 -d ' ' | tr -d '\n' \
485 > wiki/src/inc/stable_i386_hash.html
487 Update the [[support/known_issues]] page.
489 Write the announcement for the release in
490 `news/version_$VERSION.mdwn`, including:
492 - Update the `meta title` directive.
493 - Make sure there's an `announce` tag to have an email sent to the
495 - Document important config changes that persistence users have to do
496 themselves (e.g. the Pidgin proxy settings change in
497 [[!tails_gitweb_commit 9925321]] breaks all existing persistent
500 Write an announcement listing the security bugs affecting the previous
501 version in `security/` in order to let the users of the old versions
502 know that they have to upgrade. Date it a few days before the ISO
503 image to be released was *built*. Including:
505 - the list of CVE fixed in Linux since the one shipped in the previous
507 <http://ftp-master.metadata.debian.org/changelogs/main/l/linux/unstable_changelog>
508 - the list of DSA fixed in packages we ship since those that were in
509 the previous release of Tails: <http://security.debian.org/>
510 - the list of MFSA fixed by the iceweasel update:
511 <https://www.mozilla.org/security/announce/>
513 Generate PO files for the release and security announcements with
515 Then, send them to <tails-l10n@boum.org> so that they get translated
516 shortly, perhaps even soon enough to integrate them before pushing the
517 release out officially.
519 Then, record the last commit before putting the release out for real:
521 git commit -m "releasing version ${VERSION}"
529 Verify once more that the current source for Firefox is still the same
530 we've used when preparing our custom Iceweasel packages.
537 Push the last commits to our Git repository:
541 ... and ask <root@boum.org> to refresh the ikiwiki wrappers for
544 Publish update-description files
545 --------------------------------
547 Upload the update description files and their detached OpenPGP
548 signature to the primary rsync mirror.
549 See [[blueprint/incremental_upgrades]] for details.
554 Mark all issues fixed in this release as `Status: Resolved` in our bug
555 tracker. For a list of candidates, see the [issues in *Fix committed*
556 status](https://labs.riseup.net/code/projects/tails/issues?query_id=111).
561 Update the topic in our [[chatroom|chat]].
566 Announce the release by tweeting a link to the "news" page.
571 We announce *major* releases on the Tor blog:
573 - [login to their Drupal](https://blog.torproject.org/user)
574 - *Add a New Blog Post*
575 - add the same tags as the previous release announce had
576 - choose *Filtered HTML* as the *Input format*
577 - paste the HTML generated by ikiwiki from the announce in `news/`
578 into the textarea in the blog post editor
579 - cleanup a bit to make it shorter
580 - add a link to our [[download page|download]]
581 - change the internal links into external links
582 - turn `<h1>` into `<strong>`
583 - direct users to [[our communication channels|support/talk]] for
584 comments and feedback
590 Write a short announcement for the Tor weekly news, or find someone
591 who's happy to do it.
593 Prepare for the next release
594 ============================
596 1. Move the previous stable release to `obsolete` on the mirrors.
597 1. Remove any remaining RC for the just-published release from
599 1. Pull `master` back and merge it into `devel`.
601 [[post-release|contribute/APT_repository#workflow-post-release]] APT
602 repository documentation.
603 1. Push the resulting `devel` branch.
604 1. If this was a major release, then reset experimental:
605 - take note of branches merged into `experimental`, but not into
608 git log --pretty=oneline --color=never --merges devel..experimental \
609 | /bin/grep 'into experimental$' \
610 | sed -e 's,^[a-f0-9]\+\s\+,,' | sort -u
612 - `git checkout experimental && git reset --hard devel`
613 - [[hard reset|contribute/APT_repository#workflow-reset]] the `experimental`
614 APT suite to the state of the `devel` one.
615 - merge additional branches into experimental (both at the Git and
618 for branch in $UNMERGED_BRANCHES ; do
619 suite=$(echo $branch | sed -e 's,[/_],-,g')
620 ssh reprepro@incoming.deb.tails.boum.org tails-merge-suite $suite experimental
623 Note that the merge will fail for suites that contain no package.
625 - `git push --force origin experimental`
626 1. Push the release tag to lizard for Jenkins' consumption: `git push --tags lizard`
627 1. Manually trigger Jenkins builds of experimental, devel and stable:
628 <https://jenkins.tails.boum.org/>.
629 1. Bonus points if you care about Tails 1.1: update the Iceweasel
630 packages for feature/wheezy, and trigger a Jenkins build thereof.
635 [[!map pages="contribute/release_process/*"]]