ReleasingTor.md 8.75 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
# CHECKLIST

Here's a summary checklist, with the things that Nick messes up most often.

Did you:

 * [ ] Copy the ChangeLog to the ReleaseNotes?
 * [ ] Check that the new versions got approved?
 * [ ] Check the release date in the ChangeLog?
 * [ ] Update the GeoIP file?

12
# Putting out a new release
13

Nick Mathewson's avatar
Nick Mathewson committed
14
15
Here are the steps that the maintainer should take when putting out a
new Tor release:
16

17
## 0. Preliminaries
18

19
1. Get at least two of weasel/arma/Sebastian to put the new
20
21
22
   version number in their approved versions list.  Give them a few
   days to do this if you can.

23
24
25
26
27
28
29
30
31
32
33
34
35
36
2. If this is going to be an important security release, give these packagers
   some advance warning:

       - {weasel,sysrqb,mikeperry} at torproject dot org
       - {blueness} at gentoo dot org
       - {paul} at invizbox dot io
       - {vincent} at invizbox dot com
       - {lfleischer} at archlinux dot org
       - {Nathan} at freitas dot net
       - {mike} at tig dot as
       - {tails-rm} at boum dot org
       - {simon} at sdeziel.info
       - {yuri} at freebsd.org
       - {mh+tor} at scrit.ch
Nick Mathewson's avatar
Nick Mathewson committed
37
       - {security} at brave.com
38

39
40
41
3. Given the release date for Tor, ask the TB team about the likely release
   date of a TB that contains it.  See note below in "commit, upload,
   announce".
42

43
## I. Make sure it works
44

45
46
47
48
49
1. Make sure that CI passes: have a look at Travis
   (https://travis-ci.org/torproject/tor/branches), Appveyor
   (https://ci.appveyor.com/project/torproject/tor/history), and
   Jenkins (https://jenkins.torproject.org/view/tor/).
   Make sure you're looking at the right branches.
50

51
52
   If there are any unexplained failures, try to fix them or figure them
   out.
53

54
55
2. Verify that there are no big outstanding issues.  You might find such
   issues --
56

57
    * On Trac
58

59
    * On coverity scan
60

61
    * On OSS-Fuzz
62

63
## II. Write a changelog
64

65
66
67
1a. (Alpha release variant)

   Gather the `changes/*` files into a changelog entry, rewriting many
tom lurge's avatar
tom lurge committed
68
69
   of them and reordering to focus on what users and funders would find
   interesting and understandable.
70

71
72
73
74
75
76
   To do this, run `./scripts/maint/sortChanges.py changes/* > changelog.in`
   to combine headings and sort the entries.  Copy the changelog.in file into
   the ChangeLog.  Run `format_changelog.py --inplace` (see below) to clean up
   the line breaks.

   Remove the `changes/*` files that you just merged into the ChangeLog.
77
78
79

   After that, it's time to hand-edit and fix the issues that
   lintChanges can't find:
80

81
82
   1. Within each section, sort by "version it's a bugfix on", else by
      numerical ticket order.
83

84
   2. Clean them up:
85

tom lurge's avatar
tom lurge committed
86
      Make stuff very terse
87

tom lurge's avatar
tom lurge committed
88
      Describe the user-visible problem right away
89

tom lurge's avatar
tom lurge committed
90
91
      Mention relevant config options by name.  If they're rare or unusual,
      remind people what they're for
92

tom lurge's avatar
tom lurge committed
93
      Avoid starting lines with open-paren
94

tom lurge's avatar
tom lurge committed
95
      Present and imperative tense: not past.
96

97
      "Relays", not "servers" or "nodes" or "Tor relays".
98

99
100
      "Onion services", not "hidden services".

tom lurge's avatar
tom lurge committed
101
      "Stop FOOing", not "Fix a bug where we would FOO".
102

tom lurge's avatar
tom lurge committed
103
104
105
106
      Try not to let any given section be longer than about a page. Break up
      long sections into subsections by some sort of common subtopic. This
      guideline is especially important when organizing Release Notes for
      new stable releases.
107

tom lurge's avatar
tom lurge committed
108
109
110
      If a given changes stanza showed up in a different release (e.g.
      maint-0.2.1), be sure to make the stanzas identical (so people can
      distinguish if these are the same change).
111

112
   3. Clean everything one last time.
113

114
   4. Run `./scripts/maint/format_changelog.py --inplace` to make it prettier
115

116
117
118
119
1b. (old-stable release variant)

   For stable releases that backport things from later, we try to compose
   their releases, we try to make sure that we keep the changelog entries
120
   identical to their original versions, with a "backport from 0.x.y.z"
121
122
123
   note added to each section.  So in this case, once you have the items
   from the changes files copied together, don't use them to build a new
   changelog: instead, look up the corrected versions that were merged
124
   into ChangeLog in the main branch, and use those.
125

126
127
   Add "backport from X.Y.Z" in the section header for these entries.

128
2. Compose a short release blurb to highlight the user-facing
tom lurge's avatar
tom lurge committed
129
130
   changes. Insert said release blurb into the ChangeLog stanza. If it's
   a stable release, add it to the ReleaseNotes file too. If we're adding
131
   to a release-* branch, manually commit the changelogs to the later
tom lurge's avatar
tom lurge committed
132
   git branches too.
133

134
135
136
137
138
139
3. If there are changes that require or suggest operator intervention
   before or during the update, mail operators (either dirauth or relays
   list) with a headline that indicates that an action is required or
   appreciated.

4. If you're doing the first stable release in a series, you need to
Nick Mathewson's avatar
Nick Mathewson committed
140
141
142
143
144
145
146
147
148
   create a ReleaseNotes for the series as a whole.  To get started
   there, copy all of the Changelog entries from the series into a new
   file, and run `./scripts/maint/sortChanges.py` on it.  That will
   group them by category.  Then kill every bugfix entry for fixing
   bugs that were introduced within that release series; those aren't
   relevant changes since the last series.  At that point, it's time
   to start sorting and condensing entries.  (Generally, we don't edit the
   text of existing entries, though.)

149
## III. Making the source release.
150

151
1. In `maint-0.?.x`, bump the version number in `configure.ac` and run
152
   `make update-versions` to update version numbers in other
153
   places, and commit.  Then merge `maint-0.?.x` into `release-0.?.x`.
154

155
   When you merge the maint branch forward to the next maint branch, or into
156
   main, merge it with "-s ours" to avoid conflict with the version
157
   bump.
158

159
2. Make distcheck, put the tarball up in somewhere (how about your
160
   homedir on people.torproject.org?) , and tell `#tor-dev`
161
162
163
164
165
166
167
168
169
170
171
172
173
   about it.

   If you want, wait until at least one person has built it
   successfully.  (We used to say "wait for others to test it", but our
   CI has successfully caught these kinds of errors for the last several
   years.)

3. Make sure that the new version is recommended in the latest consensus.
   (Otherwise, users will get confused when it complains to them
   about its status.)

   If it is not, you'll need to poke Roger, Weasel, and Sebastian again: see
   item 0.1 at the start of this document.
174

175
## IV. Commit, upload, announce
176

177
1. Sign the tarball, then sign and push the git tag:
178

Guinness's avatar
Guinness committed
179
180
181
182
183
```console
$ gpg -ba <the_tarball>
$ git tag -s tor-0.4.x.y-<status>
$ git push origin tag tor-0.4.x.y-<status>
```
184
185
186

   (You must do this before you update the website: the website scripts
   rely on finding the version by tag.)
187

188
189
   (If your default PGP key is not the one you want to sign with, then say
   "-u <keyid>" instead of "-s".)
190

191
2. scp the tarball and its sig to the dist website, i.e.
192
193
   `/srv/dist-master.torproject.org/htdocs/` on dist-master. Run
   "static-update-component dist.torproject.org" on dist-master.
194

195
   In the project/web/tpo.git repository, update `databags/versions.ini`
196
   to note the new version.  Push these changes to master.
197

198
199
200
201
   (NOTE: Due to #17805, there can only be one stable version listed at
   once.  Nonetheless, do not call your version "alpha" if it is stable,
   or people will get confused.)

202
203
204
   (NOTE: It will take a while for the website update scripts to update
   the website.)

205
206
3. Email the tor-packagers@lists.torproject.org mailing list to tell them
   about the new release.
tom lurge's avatar
tom lurge committed
207

208
209
   Also, email tor-packagers@lists.torproject.org.

210
211
212
213
   Mention where to download the tarball (https://dist.torproject.org).

   Include a link to the changelog.

214
4. Wait for the download page to be updated. (If you don't do this before you
215
   announce, people will be confused.)
216

217
5. Mail the release blurb and ChangeLog to tor-talk (development release) or
218
   tor-announce (stable).
tom lurge's avatar
tom lurge committed
219

220
   Post the changelog on the blog as well. You can generate a
221
   blog-formatted version of the changelog with
222
      `./scripts/maint/format_changelog.py -B`
223

224
225
226
227
   When you post, include an estimate of when the next TorBrowser
   releases will come out that include this Tor release.  This will
   usually track https://wiki.mozilla.org/RapidRelease/Calendar , but it
   can vary.
tom lurge's avatar
tom lurge committed
228

229
   For templates to use when announcing, see:
230
       https://gitlab.torproject.org/tpo/core/team/-/wikis/NetworkTeam/AnnouncementTemplates
231

232
## V. Aftermath and cleanup
233

234
1. If it's a stable release, bump the version number in the
235
   `maint-x.y.z` branch to "newversion-dev", and do a `merge -s ours`
236
   merge to avoid taking that change into main.
237

238
239
240
2. If there is a new `maint-x.y.z` branch, create a Travis CI cron job that
   builds the release every week. (It's ok to skip the weekly build if the
   branch was updated in the last 24 hours.)
241

242
3. Forward-port the ChangeLog (and ReleaseNotes if appropriate) to the
243
   main branch.
244

245
4. Keep an eye on the blog post, to moderate comments and answer questions.