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