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       When updating the version, it will be on `maint` branches and so to
  57       merge-forward, use `git merge -s ours`. For instance, if merging the
  58       version change of `maint-0.4.5` into `maint-0.4.6`, do on `maint-0.4.6`
  59       this command: `git merge -s ours maint-0.4.5`. And then you can proceed
  60       with a git-merge-forward.
  61
  62    2. For the ChangeLog and ReleaseNotes, you need to write a blurb at the top
  63       explaining a bit the release.
  64
  65    3. Review, modify if needed, and merge them upstream.
  66
  67    4. Manually trigger the `maintained` job in the `Build` stage so the CI can
  68       build the tarballs without errors.
  69
  70 Once this is done, each selected developers need to build the tarballs in a
  71 reproducible way using:
  72
  73    https://gitlab.torproject.org/tpo/core/tor-ci-reproducible
  74
  75 Steps are:
  76
  77    1. Run `./build.sh` which will download everything you need, including the
  78       latest tarballs from the release CI, and auto-commit the signatures if
  79       the checksum match. You will need to confirm the commits.
  80
  81    2. If all is good, `git push origin main` your signatures.
  82
  83 Once all signatures from all selected developers have been committed:
  84
  85    1. Manually trigger the `signature` job in the `Post-process` stage of the
  86       CI release pipeline.
  87
  88    2. If it passes, the tarball(s) and signature(s) will be available as
  89       artifacts and should be used for the release.
  90
  91    3. Put them on `dist.torproject.org`:
  92
  93       Upload the tarball and its sig to the dist website:
  94
  95          `rsync -avP tor-*.gz{,.asc} dist-master.torproject.org:/srv/dist-master.torproject.org/htdocs/`
  96
  97       Then, on dist-master.torproject.org, run:
  98
  99          `static-update-component dist.torproject.org`
 100
 101       For an alpha or latest stable, open an MR in
 102       https://gitlab.torproject.org/tpo/web/tpo that updates the
 103       `databags/versions.ini` to note the new version.
 104
 105       (NOTE: Due to #17805, there can only be one stable version listed at once.
 106       Nonetheless, do not call your version "alpha" if it is stable, or people
 107       will get confused.)
 108
 109       (NOTE: It will take a while for the website update scripts to update the
 110       website.)
 111
 112
 113 ## 3. Post Process
 114
 115 Once the tarballs have been uploaded and are ready to be announced, we need to
 116 do the following:
 117
 118    1. Tag versions (`main` branch or `release` branch as appropriate) using
 119       `git tag -s tor-0.x.y.z-<status>` and then push the tag(s):
 120       `git push origin tor-0.x.y.z-<status>`
 121
 122       (This should be the `main` or `release` branch because that is the one
 123       from which the tarballs are built.  We want our tags to match our
 124       tarballs.)
 125
 126    2. Merge upstream the artifacts from the `patches` job in the
 127       `Post-process` stage of the CI release pipeline.
 128
 129       Like step (2.1) above, the `-dev` version bump need to be done manually
 130       with a `git merge -s ours`.
 131
 132    3. Write and post the release announcement for the `forum.torproject.net`
 133       in the `News -> Tor Release Announcement` category.
 134
 135       If possible, mention in which Tor Browser version (with dates) the
 136       release will be in. This usually only applies to the latest stable.
 137
 138    4. Inform `tor-announce@lists.torproject.org` with the releasing pointing to
 139       the Forum. Append the ChangeLog there. We do this until we can automate
 140       such post from the forum directly.
 141
 142    5. Update torproject.org website by submitting a MR to
 143       https://gitlab.torproject.org/tpo/web/tpo
 144
 145       The `databags/versions.ini` file is the one to change with the newly
 146       released version(s).
 147
 148 ### New Stable
 149
 150    1. Create the `maint-x.y.z` and `release-x.y.z` branches at the version
 151       tag. Then update the `./scripts/git/git-list-tor-branches.sh` with the
 152       new version.
 153
 154    2. Update `./scripts/git/git-list-tor-branches.sh` and
 155       `./scripts/ci/ci-driver.sh` with the new version in `maint-x.y.z` and
 156       then merge forward into main. (If you haven't pushed remotely the new
 157       branches, merge the local branch).
 158
 159    3. In `main`, bump version to the next series: `tor-x.y.0-alpha-dev` and
 160       then tag it: `git tag -s tor-x.y.0-alpha-dev`
 161
 162 ## Appendix: An alternative means to notify packagers
 163
 164 If for some reason you need to contact a bunch of packagers without
 165 using the publicly archived tor-packagers list, you can try these
 166 people:
 167
 168        - {weasel,sysrqb,mikeperry} at torproject dot org
 169        - {blueness} at gentoo dot org
 170        - {paul} at invizbox dot io
 171        - {vincent} at invizbox dot com
 172        - {lfleischer} at archlinux dot org
 173        - {Nathan} at freitas dot net
 174        - {mike} at tig dot as
 175        - {tails-rm} at boum dot org
 176        - {simon} at sdeziel.info
 177        - {yuri} at freebsd.org
 178        - {mh+tor} at scrit.ch
 179        - {security} at brave.com