doc/HACKING/ReleasingTor.md

   1
   2 Putting out a new release
   3 -------------------------
   4
   5 Here are the steps that the maintainer should take when putting out a
   6 new Tor release:
   7
   8 === 0. Preliminaries
   9
  10 1. Get at least two of weasel/arma/Sebastian to put the new
  11    version number in their approved versions list.  Give them a few
  12    days to do this if you can.
  13
  14 2. If this is going to be an important security release, give the packagers
  15    some advance warning: See this list of packagers in IV.3 below.
  16
  17 3. Given the release date for Tor, ask the TB team about the likely release
  18    date of a TB that contains it.  See note below in "commit, upload,
  19    announce".
  20
  21 === I. Make sure it works
  22
  23 1. Make sure that CI passes: have a look at Travis, Appveyor, and
  24    Jenkins.  Make sure you're looking at the right branches.
  25
  26    If there are any unexplained failures, try to fix them or figure them
  27    out.
  28
  29 2. Verify that there are no big outstanding issues.  You might find such
  30    issues --
  31
  32     * On Trac
  33
  34     * On coverity scan
  35
  36     * On OSS-Fuzz
  37
  38 3. Run checks that aren't covered above, including:
  39
  40     * clang scan-build.  (See the script in ./scripts/test/scan_build.sh)
  41
  42     * make test-network and make test-network-all (with
  43       --enable-expensive-hardening)
  44
  45     * Running Tor yourself and making sure that it actually works for you.
  46
  47
  48 === II. Write a changelog
  49
  50
  51 1a. (Alpha release variant)
  52
  53    Gather the `changes/*` files into a changelog entry, rewriting many
  54    of them and reordering to focus on what users and funders would find
  55    interesting and understandable.
  56
  57    To do this, run
  58       `./scripts/maint/sortChanges.py changes/* > changelog.in`
  59    to combine headings and sort the entries.  Copy the changelog.in file
  60    into the ChangeLog.  Run 'format_changelog.py' (see below) to clean
  61    up the line breaks.
  62
  63    After that, it's time to hand-edit and fix the issues that
  64    lintChanges can't find:
  65
  66    1. Within each section, sort by "version it's a bugfix on", else by
  67       numerical ticket order.
  68
  69    2. Clean them up:
  70
  71       Make stuff very terse
  72
  73       Describe the user-visible problem right away
  74
  75       Mention relevant config options by name.  If they're rare or unusual,
  76       remind people what they're for
  77
  78       Avoid starting lines with open-paren
  79
  80       Present and imperative tense: not past.
  81
  82       "Relays", not "servers" or "nodes" or "Tor relays".
  83
  84       "Onion services", not "hidden services".
  85
  86       "Stop FOOing", not "Fix a bug where we would FOO".
  87
  88       Try not to let any given section be longer than about a page. Break up
  89       long sections into subsections by some sort of common subtopic. This
  90       guideline is especially important when organizing Release Notes for
  91       new stable releases.
  92
  93       If a given changes stanza showed up in a different release (e.g.
  94       maint-0.2.1), be sure to make the stanzas identical (so people can
  95       distinguish if these are the same change).
  96
  97    3. Clean everything one last time.
  98
  99    4. Run `./scripts/maint/format_changelog.py --inplace` to make it prettier
 100
 101 1b. (old-stable release variant)
 102
 103    For stable releases that backport things from later, we try to compose
 104    their releases, we try to make sure that we keep the changelog entries
 105    identical to their original versions, with a "backport from 0.x.y.z"
 106    note added to each section.  So in this case, once you have the items
 107    from the changes files copied together, don't use them to build a new
 108    changelog: instead, look up the corrected versions that were merged
 109    into ChangeLog in the master branch, and use those.
 110
 111    Add "backport from X.Y.Z" in the section header for these entries.
 112
 113 2. Compose a short release blurb to highlight the user-facing
 114    changes. Insert said release blurb into the ChangeLog stanza. If it's
 115    a stable release, add it to the ReleaseNotes file too. If we're adding
 116    to a release-* branch, manually commit the changelogs to the later
 117    git branches too.
 118
 119 3. If there are changes that require or suggest operator intervention
 120    before or during the update, mail operators (either dirauth or relays
 121    list) with a headline that indicates that an action is required or
 122    appreciated.
 123
 124 4. If you're doing the first stable release in a series, you need to
 125    create a ReleaseNotes for the series as a whole.  To get started
 126    there, copy all of the Changelog entries from the series into a new
 127    file, and run `./scripts/maint/sortChanges.py` on it.  That will
 128    group them by category.  Then kill every bugfix entry for fixing
 129    bugs that were introduced within that release series; those aren't
 130    relevant changes since the last series.  At that point, it's time
 131    to start sorting and condensing entries.  (Generally, we don't edit the
 132    text of existing entries, though.)
 133
 134
 135 === III. Making the source release.
 136
 137 1. In `maint-0.?.x`, bump the version number in `configure.ac` and run
 138    `make update-versions` to update version numbers in other
 139    places, and commit.  Then merge `maint-0.?.x` into `release-0.?.x`.
 140
 141    When you merge the maint branch forward to the next maint branch, or into
 142    master, merge it with "-s ours" to avoid a needless version bump.
 143
 144 2. Make distcheck, put the tarball up in somewhere (how about your
 145    homedir on your homedir on people.torproject.org?) , and tell `#tor-dev`
 146    about it.
 147
 148    If you want, wait until at least one person has built it
 149    successfully.  (We used to say "wait for others to test it", but our
 150    CI has successfully caught these kinds of errors for the last several
 151    years.)
 152
 153
 154 3. Make sure that the new version is recommended in the latest consensus.
 155    (Otherwise, users will get confused when it complains to them
 156    about its status.)
 157
 158    If it is not, you'll need to poke Roger, Weasel, and Sebastian again: see
 159    item 0.1 at the start of this document.
 160
 161 === IV. Commit, upload, announce
 162
 163 1. Sign the tarball, then sign and push the git tag:
 164
 165         gpg -ba <the_tarball>
 166         git tag -s tor-0.4.x.y-<status>
 167         git push origin tag tor-0.4.x.y-<status>
 168
 169    (You must do this before you update the website: the website scripts
 170    rely on finding the version by tag.)
 171
 172    (If your default PGP key is not the one you want to sign with, then say
 173    "-u <keyid>" instead of "-s".)
 174
 175 2. scp the tarball and its sig to the dist website, i.e.
 176    `/srv/dist-master.torproject.org/htdocs/` on dist-master. Run
 177    "static-update-component dist.torproject.org" on dist-master.
 178
 179    In the webwml.git repository, `include/versions.wmi` and `Makefile`
 180    to note the new version.  Push these changes to master.
 181
 182    (NOTE: Due to #17805, there can only be one stable version listed at
 183    once.  Nonetheless, do not call your version "alpha" if it is stable,
 184    or people will get confused.)
 185
 186    (NOTE: It will take a while for the website update scripts to update
 187    the website.)
 188
 189 3. Email the packagers (cc'ing tor-team) that a new tarball is up.
 190    The current list of packagers is:
 191
 192        - {weasel,gk,mikeperry} at torproject dot org
 193        - {blueness} at gentoo dot org
 194        - {paul} at invizbox dot io
 195        - {vincent} at invizbox dot com
 196        - {lfleischer} at archlinux dot org
 197        - {Nathan} at freitas dot net
 198        - {mike} at tig dot as
 199        - {tails-rm} at boum dot org
 200        - {simon} at sdeziel.info
 201        - {yuri} at freebsd.org
 202        - {mh+tor} at scrit.ch
 203
 204    Also, email tor-packagers@lists.torproject.org.
 205
 206    Mention where to download the tarball (https://dist.torproject.org).
 207
 208    Include a link to the changelog.
 209
 210
 211 4. Add the version number to Trac.  To do this, go to Trac, log in,
 212     select "Admin" near the top of the screen, then select "Versions" from
 213     the menu on the left.  At the right, there will be an "Add version"
 214     box.  By convention, we enter the version in the form "Tor:
 215     0.4.0.1-alpha" (or whatever the version is), and we select the date as
 216     the date in the ChangeLog.
 217
 218 5. Wait for the download page to be updated. (If you don't do this before you
 219    announce, people will be confused.)
 220
 221 6. Mail the release blurb and ChangeLog to tor-talk (development release) or
 222    tor-announce (stable).
 223
 224    Post the changelog on the blog as well. You can generate a
 225    blog-formatted version of the changelog with
 226       `./scripts/maint/format_changelog.py --B`
 227
 228    When you post, include an estimate of when the next TorBrowser
 229    releases will come out that include this Tor release.  This will
 230    usually track https://wiki.mozilla.org/RapidRelease/Calendar , but it
 231    can vary.
 232
 233    For templates to use when announcing, see:
 234        https://trac.torproject.org/projects/tor/wiki/org/teams/NetworkTeam/AnnouncementTemplates
 235
 236 === V. Aftermath and cleanup
 237
 238 1. If it's a stable release, bump the version number in the
 239     `maint-x.y.z` branch to "newversion-dev", and do a `merge -s ours`
 240     merge to avoid taking that change into master.
 241
 242 2. Forward-port the ChangeLog (and ReleaseNotes if appropriate) to the
 243    master branch.
 244
 245 3. Keep an eye on the blog post, to moderate comments and answer questions.