doc/HACKING/ReleasingTor.md

   1 # How to Release Tor
   2
   3 Here are the steps that the maintainer should take when putting out a
   4 new Tor release. It is split in 3 stages and coupled with our Tor CI Release
   5 pipeline.
   6
   7 Before we begin, first rule is to make sure:
   8
   9    - Our CIs (*nix and Windows) pass for each version to release
  10    - Coverity has no new alerts
  11
  12 ## 0. Security Release
  13
  14 To start with, if you are doing a security release, this must be done few days
  15 prior to the release:
  16
  17    1. If this is going to be an important security release, give the packagers
  18       advance warning, via `tor-packagers@lists.torproject.org`.
  19
  20
  21 ## 1. Preliminaries
  22
  23 The following must be done **2 days** at the very least prior to the release:
  24
  25    1. Add the version(s) in the dirauth-conf git repository as the
  26       RecommendedVersion and RequiredVersion so they can be approved by the
  27       authorities and be in the consensus before the release.
  28
  29    2. Send a pre-release announcement to `tor-project@lists.torproject.org` in
  30       order to inform every teams in Tor of the upcoming release. This is so
  31       we can avoid creating release surprises and sync with other teams.
  32
  33    3. Ask the network-team to review the `changes/` files in all versions we
  34       are about to release. This step is encouraged but not mandatory.
  35
  36
  37 ## 2. Tarballs
  38
  39 To build the tarballs to release, we need to launch the CI release pipeline:
  40
  41    https://gitlab.torproject.org/tpo/core/tor-ci-release
  42
  43 The `versions.yml` needs to be modified with the Tor versions you want to
  44 release. Once done, git commit and push to trigger the release pipeline.
  45
  46 The first two stages (Preliminary and Patches) will be run automatically. The
  47 Build stage needs to be triggered manually once all generated patches have
  48 been merged upstream.
  49
  50    1. Download the generated patches from the `Patches` stage.
  51
  52       Apply these patches to the `main` or `release` branch as appropriate.
  53       (Version bumps apply to `maint`; anything touching the changelog should
  54       apply only to `main` or `release`.)
  55
  56    2. For the ChangeLog and ReleaseNotes, you need to write a blurb at the top
  57       explaining a bit the release.
  58
  59    3. Review, modify if needed, and merge them upstream.
  60
  61    4. Manually trigger the `maintained` job in the `Build` stage so the CI can
  62       build the tarballs without errors.
  63
  64 Once this is done, each selected developers need to build the tarballs in a
  65 reproducible way using:
  66
  67    https://gitlab.torproject.org/tpo/core/tor-ci-reproducible
  68
  69 Steps are:
  70
  71    1. Run `./build.sh` which will download everything you need, including the
  72       latest tarballs from the release CI, and auto-commit the signatures if
  73       the checksum match. You will need to confim the commits.
  74
  75    2. If all is good, `git push origin main` your signatures.
  76
  77 Once all signatures from all selected developers have been committed:
  78
  79    1. Manually trigger the `signature` job in the `Post-process` stage of the
  80       CI release pipeline.
  81
  82    2. If it passes, the tarball(s) and signature(s) will be available as
  83       artifacts and should be used for the release.
  84
  85    3. Put them on `dist.torproject.org`:
  86
  87       Upload the tarball and its sig to the dist website:
  88
  89          `rsync -avP tor-*.gz{,.asc} dist-master.torproject.org:/srv/dist-master.torproject.org/htdocs/`
  90
  91       Then, on dist-master.torproject.org, run:
  92
  93          `static-update-component dist.torproject.org`
  94
  95       For an alpha or latest stable, open an MR in
  96       https://gitlab.torproject.org/tpo/web/tpo that updates the
  97       `databags/versions.ini` to note the new version.
  98
  99       (NOTE: Due to #17805, there can only be one stable version listed at once.
 100       Nonetheless, do not call your version "alpha" if it is stable, or people
 101       will get confused.)
 102
 103       (NOTE: It will take a while for the website update scripts to update the
 104       website.)
 105
 106
 107 ## 3. Post Process
 108
 109 Once the tarballs have been uploaded and are ready to be announced, we need to
 110 do the following:
 111
 112    1. Tag versions (`main` branch or `release` branch as appropriate) using
 113       `git tag -s tor-0.x.y.z-<status>` and then push the tag(s):
 114       `git push origin tor-0.x.y.z-<status>`
 115
 116       (This should be the `main` or `release` branch because that is the one
 117       from which the tarballs are built.  We want our tags to match our
 118       tarballs.)
 119
 120    2. Merge upstream the artifacts from the `patches` job in the
 121       `Post-process` stage of the CI release pipeline.
 122
 123    3. Write and post the release announcement for the `forum.torproject.net`
 124       in the `News -> Tor Release Announcement` category.
 125
 126       If possible, mention in which Tor Browser version (with dates) the
 127       release will be in. This usually only applies to the latest stable.
 128
 129    4. Inform `tor-talk@lists.torproject.org` with the releasing pointing to
 130       the Forum. Append the ChangeLog there. We do this until we can automate
 131       such post from the forum directly.
 132
 133 ### New Stable
 134
 135    1. Create the `maint-x.y.z` and `release-x.y.z` branches and update the
 136       `./scripts/git/git-list-tor-branches.sh` with the new version.
 137
 138    2. Add the new version in `./scripts/ci/ci-driver.sh`.
 139
 140    3. Forward port the ChangeLog and ReleaseNotes into main branch. Remove any
 141       change logs of stable releases in ReleaseNotes.
 142
 143
 144 ## Appendix: An alternative means to notify packagers
 145
 146 If for some reason you need to contact a bunch of packagers without
 147 using the publicly archived tor-packagers list, you can try these
 148 people:
 149
 150        - {weasel,sysrqb,mikeperry} at torproject dot org
 151        - {blueness} at gentoo dot org
 152        - {paul} at invizbox dot io
 153        - {vincent} at invizbox dot com
 154        - {lfleischer} at archlinux dot org
 155        - {Nathan} at freitas dot net
 156        - {mike} at tig dot as
 157        - {tails-rm} at boum dot org
 158        - {simon} at sdeziel.info
 159        - {yuri} at freebsd.org
 160        - {mh+tor} at scrit.ch
 161        - {security} at brave.com