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 Generate the OpenPGP signatures and Torrents
264 ============================================
266 First, create a directory with a suitable name and go there:
268 mkdir "$ISOS/tails-i386-$VERSION" && cd "$ISOS/tails-i386-$VERSION"
270 Second, copy the built image to this brand new directory.
273 mv *.iso "tails-i386-$VERSION.iso"
275 Third, generate detached OpenPGP signatures for the image to be
276 published, in the same directory as the image and with a `.sig`
279 gpg --armor --default-key "$TAILS_SIGNATURE_KEY" --detach-sign *.iso
280 rename 's,\.asc$,.sig,' *.asc
282 Fourth, go up to the parent directory, create a `.torrent` file and
283 check the generated `.torrent` files metainfo:
286 mktorrent -a 'http://torrent.gresille.org/announce' "tails-i386-${VERSION}" && \
287 btshowmetainfo tails-i386-$VERSION.torrent
289 Fifth, generate detached OpenPGP signatures for every published
292 gpg --armor --default-key "$TAILS_SIGNATURE_KEY" --detach-sign \
293 tails-i386-$VERSION.torrent && \
294 mv tails-i386-$VERSION.torrent.{asc,sig}
296 Prepare incremental upgrades
297 ============================
299 Build the Incremental Upgrade Kits
300 ----------------------------------
302 Skip this step when preparing a major release.
304 Use `tails-create-iuk` to build an IUK for the previous stable release
305 and (if applicable) the last RC for the version being released. Example:
307 sudo su -c "cd $IUK_CHECKOUT && \
308 PERL5LIB=\"$PERL5LIB_CHECKOUT/lib\" \
309 ./bin/tails-create-iuk \
310 --squashfs-diff-name \"$VERSION.squashfs\" \
311 --old-iso \"$ISOS/tails-i386-$PREVIOUS_VERSION/tails-i386-$PREVIOUS_VERSION.iso\" \
312 --new-iso \"$ISOS/tails-i386-$VERSION/tails-i386-$VERSION.iso\" \
313 --outfile \"$ISOS/Tails_i386_${PREVIOUS_VERSION}_to_${VERSION}.iuk\""
315 Note that developer tools for creating IUK and upgrade-description
316 files were only tested on Debian sid. It should hopefully work well on
317 Wheezy too, but I would not even try to use it on Squeeze.
319 <a id="prepare-upgrade-description-files"></a>
321 Prepare upgrade-description files
322 ---------------------------------
324 Do **not** skip this step when preparing a major release.
326 1. Prepare upgrade-description files (see the [[upgrade-description
328 specification|contribute/design/incremental_upgrades#upgrade-description-files]]
329 for details). The idea is to:
331 * update (create if needed) an upgrade-description file for every
332 *previous* supported release (e.g. N~rc1, N-1, N-1~rc2) that replaces
333 all existing upgrade paths with the path to the version being
335 * create a new upgrade-description for the version being released,
336 that expresses that *no* upgrade is available for that one yet.
338 This is what `tails-iuk-generate-ugrade-description-files` tool
341 cd $IUK_CHECKOUT && \
342 ./bin/tails-iuk-generate-upgrade-description-files \
343 --version "$VERSION" \
344 --iso "$ISOS/tails-i386-$VERSION/tails-i386-$VERSION.iso" \
345 --previous-version "$PREVIOUS_VERSION" \
346 --previous-version "${VERSION}-rc1" \
348 --release-checkout "$RELEASE_CHECKOUT" \
349 --major-release "$MAJOR_RELEASE"
352 * The `--iuks` argument must point to the directory where the IUKs
353 generated at the previous step are stored.
354 * At least the last stable release and the previous release
355 candidates for the version being released must be passed to
356 `--previous-version`.
357 * A few (say, 2 or 3) older versions must be passed with
358 `--previous-version`, so that users who skipped a release or two
359 are directly informed of the new one.
361 1. Create an armoured detached signature for each created or modified
362 upgrade-description file.
364 find "$RELEASE_CHECKOUT/wiki/src/upgrade/" \
365 -type f -name upgrades.yml -exec \
366 gpg -u "$TAILS_SIGNATURE_KEY" --armor --detach-sign {} \;
368 1. Rename each detached signature to `.pgp`:
370 find "$RELEASE_CHECKOUT/wiki/src/upgrade/" -type f \
371 -name upgrades.yml.asc -exec rename -f 's,\.asc$,.pgp,' {} \;
373 1. Add and commit the upgrade-description files and their detached
374 signatures to the Git branch used to prepare the release (`stable`
377 cd "$RELEASE_CHECKOUT" && git add wiki/src/upgrade && \
378 git commit -m "Update upgrade-description files."
380 1. Check the syntactic correctness of all upgrade-description files:
382 cd $IUK_CHECKOUT && \
383 ./bin/tails-iuk-check-upgrade-description-file \
384 ${RELEASE_CHECKOUT}/wiki/src/upgrade/v1/*/*/*/*/upgrades.yml
392 Verify that the current source for Firefox is still the same we've
393 used when preparing our custom Iceweasel package: e.g. FF17.0.8 got
394 re-tagged and re-uploaded at the last minute, due to a test failure.
396 Better catch this before people spend time doing manual tests.
398 ## Announce, seed and test the Torrents
400 Announce and seed the Torrents.
402 Test them with a BitTorrent client running in a different place.
404 ## Download and seed image from lizard
406 scp "$RELEASE_CHECKOUT/wiki/src/torrents/files/tails-i386-$VERSION.torrent" \
407 bittorrent.lizard: && \
408 ssh bittorrent.lizard transmission-remote --add tails-i386-$VERSION.torrent
410 Publish the ISO over HTTP
411 -------------------------
413 Upload the images to the primary rsync mirror. Best practice is to first
414 let bittorrent.lizard download the image, and then copy it from there to
417 ssh lizard.tails.boum.org \
419 bittorrent.lizard:/var/lib/transmission-daemon/downloads/tails-i386-$VERSION \
421 # set DIST to either 'testing' (for RC:s) or 'stable' (for actual releases)
422 ssh rsync.lizard << EOF
423 chown -R root:rsync_tails tails-i386-$VERSION
424 chmod -R u=rwX,go=rX tails-i386-$VERSION
425 sudo mv tails-i386-$VERSION /srv/rsync/tails/tails/$DIST/
428 Update the time in `project/trace` file on the primary rsync mirror
429 and on the live wiki (even for a release candidate):
431 TRACE_TIME=$(date +%s) &&
432 echo $TRACE_TIME | ssh rsync.lizard "cat > /srv/rsync/tails/tails/project/trace" && \
433 [ -n "$MASTER_CHECKOUT" ] && \
434 echo $TRACE_TIME > "$MASTER_CHECKOUT/wiki/src/inc/trace" &&
436 cd "$MASTER_CHECKOUT" && \
437 git commit wiki/src/inc/trace -m "Updating trace file after uploading $VERSION."
440 <a id="publish-iuk"></a>
445 Same as for the ISO, but the IUKs should land into
446 `/srv/rsync/tails/tails/$DIST/iuk/`.
448 Wait for the HTTP mirrors to catch up
449 -------------------------------------
451 Wait for the next rsync pull.
453 Make sure every webserver listed in the `dl.amnesia.boum.org` round
454 robin pool has the new version. Drop those that are lagging behind and
455 notify their administrators.
457 Test downloading the ISO and IUK over HTTP.
462 1. Set up a Gobby document and copy the [[test
463 suite|contribute/release_process/test]] in it.
464 1. Email <tails@boum.org> to announce that tests may start:
465 - make it clear what's the deadline
466 - make it clear where and how you expect to get feedback
468 - attach the `.packages` file
469 1. Make sure someone is committed to run the automated test suite.
470 1. Make sure that enough people are here to run the tests, that they
471 report their results in due time, and that they make it clear when
472 they're leaving for good.
474 While this happens, the release manager should prepare for the next
475 steps. Please read on!
477 Update the website and Git repository
478 =====================================
480 In order to get any new documentation into the website, merge either
481 `stable` or `testing` (depending on which release you just did) into
484 Rename the `.packages` file to remove the `.iso` part of its name.
486 If preparing a final release, copy the `.iso.sig`, `.packages`,
487 `.torrent` and `.torrent.sig` files into the Git repository's
488 `wiki/src/torrents/files/` directory and remove the one for the
489 previous release (including any RCs). If preparing an RC, only copy
492 If preparing a final release, generate the SHA-256 hash of every image
493 to be released in `inc/*`:
495 sha256sum $ISOS/tails-i386-$VERSION/tails-i386-$VERSION.iso | \
496 cut -f 1 -d ' ' | tr -d '\n' \
497 > "$RELEASE_CHECKOUT/wiki/src/inc/stable_i386_hash.html"
499 Update the [[support/known_issues]] page.
501 Write the announcement for the release in
502 `news/version_$VERSION.mdwn`, including:
504 - Update the `meta title` directive.
505 - Make sure there's an `announce` tag to have an email sent to the
507 - Document important config changes that persistence users have to do
508 themselves (e.g. the Pidgin proxy settings change in
509 [[!tails_gitweb_commit 9925321]] breaks all existing persistent
512 Write an announcement listing the security bugs affecting the previous
513 version in `security/` in order to let the users of the old versions
514 know that they have to upgrade. Date it a few days before the ISO
515 image to be released was *built*. Including:
517 - the list of CVE fixed in Linux since the one shipped in the previous
519 <http://ftp-master.metadata.debian.org/changelogs/main/l/linux/unstable_changelog>
520 - the list of DSA fixed in packages we ship since those that were in
521 the previous release of Tails: <http://security.debian.org/>
522 - the list of MFSA fixed by the iceweasel update:
523 <https://www.mozilla.org/security/announce/>
525 Generate PO files for the release and security announcements with
527 Then, send them to <tails-l10n@boum.org> so that they get translated
528 shortly, perhaps even soon enough to integrate them before pushing the
529 release out officially.
531 Then, record the last commit before putting the release out for real:
533 git commit -m "releasing version ${VERSION}"
541 Verify once more that the current source for Firefox is still the same
542 we've used when preparing our custom Iceweasel packages.
549 Push the last commits to our Git repository:
553 ... and ask <root@boum.org> to refresh the ikiwiki wrappers for
556 Publish update-description files
557 --------------------------------
559 Upload the update description files and their detached OpenPGP
560 signature to the primary rsync mirror.
561 See [[blueprint/incremental_upgrades]] for details.
566 Mark all issues fixed in this release as `Status: Resolved` in our bug
567 tracker. For a list of candidates, see the [issues in *Fix committed*
568 status](https://labs.riseup.net/code/projects/tails/issues?query_id=111).
573 Update the topic in our [[chatroom|chat]].
578 Announce the release by tweeting a link to the "news" page.
583 We announce *major* releases on the Tor blog:
585 - [login to their Drupal](https://blog.torproject.org/user)
586 - *Add a New Blog Post*
587 - add the same tags as the previous release announce had
588 - choose *Filtered HTML* as the *Input format*
589 - paste the HTML generated by ikiwiki from the announce in `news/`
590 into the textarea in the blog post editor
591 - cleanup a bit to make it shorter
592 - add a link to our [[download page|download]]
593 - change the internal links into external links
594 - turn `<h1>` into `<strong>`
595 - direct users to [[our communication channels|support/talk]] for
596 comments and feedback
602 Write a short announcement for the Tor weekly news, or find someone
603 who's happy to do it.
605 Prepare for the next release
606 ============================
608 1. Move the previous stable release to `obsolete` on the mirrors.
609 1. Remove any remaining RC for the just-published release from
611 1. Pull `master` back and merge it into `devel`.
613 [[post-release|contribute/APT_repository#workflow-post-release]] APT
614 repository documentation.
615 1. Push the resulting `devel` branch.
616 1. If this was a major release, then reset experimental:
617 - take note of branches merged into `experimental`, but not into
620 git log --pretty=oneline --color=never --merges devel..experimental \
621 | /bin/grep 'into experimental$' \
622 | sed -e 's,^[a-f0-9]\+\s\+,,' | sort -u
624 - `git checkout experimental && git reset --hard devel`
625 - [[hard reset|contribute/APT_repository#workflow-reset]] the `experimental`
626 APT suite to the state of the `devel` one.
627 - merge additional branches into experimental (both at the Git and
630 for branch in $UNMERGED_BRANCHES ; do
631 suite=$(echo $branch | sed -e 's,[/_],-,g')
632 ssh reprepro@incoming.deb.tails.boum.org tails-merge-suite $suite experimental
635 Note that the merge will fail for suites that contain no package.
637 - `git push --force origin experimental`
638 1. Push the release tag to lizard for Jenkins' consumption: `git push --tags lizard`
639 1. Manually trigger Jenkins builds of experimental, devel and stable:
640 <https://jenkins.tails.boum.org/>.
641 1. Bonus points if you care about Tails 1.1: update the Iceweasel
642 packages for feature/wheezy, and trigger a Jenkins build thereof.
647 [[!map pages="contribute/release_process/*"]]