diff options
Diffstat (limited to 'doc/HACKING/ReleasingTor.md')
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 277 |
1 files changed, 95 insertions, 182 deletions
diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index 739ea38795..86feef754e 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -1,234 +1,147 @@ -# Putting out a new release +# How to Release Tor Here are the steps that the maintainer should take when putting out a -new Tor release: +new Tor release. It is split in 3 stages and coupled with our Tor CI Release +pipeline. -## 0. Preliminaries +Before we begin, first rule is to make sure: -1. Get at least two of weasel/arma/Sebastian to put the new - version number in their approved versions list. Give them a few - days to do this if you can. + - Our CIs (*nix and Windows) pass for each version to release + - Coverity has no new alerts -2. If this is going to be an important security release, give these packagers - some advance warning: +## 0. Security Release - - {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 - - {security} at brave.com - -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". - -## I. Make sure it works - -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. - - If there are any unexplained failures, try to fix them or figure them - out. - -2. Verify that there are no big outstanding issues. You might find such - issues -- - - * On Trac - - * On coverity scan - - * On OSS-Fuzz - -## II. Write a changelog +To start with, if you are doing a security release, this must be done few days +prior to the release: -1a. (Alpha release variant) + 1. If this is going to be an important security release, give the packagers + advance warning, via `tor-packagers@lists.torproject.org`. - Gather the `changes/*` files into a changelog entry, rewriting many - of them and reordering to focus on what users and funders would find - interesting and understandable. - 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. +## 1. Preliminaries - Remove the `changes/*` files that you just merged into the ChangeLog. +The following must be done **2 days** at the very least prior to the release: - After that, it's time to hand-edit and fix the issues that - lintChanges can't find: + 1. Add the version(s) in the dirauth-conf git repository as the + RecommendedVersion and RequiredVersion so they can be approved by the + authorities and be in the consensus before the release. - 1. Within each section, sort by "version it's a bugfix on", else by - numerical ticket order. + 2. Send a pre-release announcement to `tor-project@lists.torproject.org` in + order to inform every teams in Tor of the upcoming release. This is so + we can avoid creating release surprises and sync with other teams. - 2. Clean them up: + 3. Ask the network-team to review the `changes/` files in all versions we + are about to release. This step is encouraged but not mandatory. - Make stuff very terse - Describe the user-visible problem right away +## 2. Tarballs - Mention relevant config options by name. If they're rare or unusual, - remind people what they're for +To build the tarballs to release, we need to launch the CI release pipeline: - Avoid starting lines with open-paren + https://gitlab.torproject.org/tpo/core/tor-ci-release - Present and imperative tense: not past. +The `versions.yml` needs to be modified with the Tor versions you want to +release. Once done, git commit and push to trigger the release pipeline. - "Relays", not "servers" or "nodes" or "Tor relays". +The first two stages (Preliminary and Patches) will be run automatically. The +Build stage needs to be triggered manually once all generated patches have +been merged upstream. - "Onion services", not "hidden services". + 1. Download the generated patches from the `Patches` stage. - "Stop FOOing", not "Fix a bug where we would FOO". + 2. For the ChangeLog and ReleaseNotes, you need to write a blurb at the top + explaining a bit the release. - 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. + 3. Review, modify if needed, and merged them upstream. - 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). + 4. Manually trigger the `maintained` job in the `Build` stage so the CI can + build the tarballs without errors. - 3. Clean everything one last time. +Once this is done, each selected developers need to build the tarballs in a +reproducible way using: - 4. Run `./scripts/maint/format_changelog.py --inplace` to make it prettier + https://gitlab.torproject.org/tpo/core/tor-ci-reproducible -1b. (old-stable release variant) +Steps are: - 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 - identical to their original versions, with a "backport from 0.x.y.z" - 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 - into ChangeLog in the master branch, and use those. + 1. Run `./build.sh` which will download everything you need, including the + latest tarballs from the release CI, and auto-commit the signatures if + the checksum match. You will need to confim the commits. - Add "backport from X.Y.Z" in the section header for these entries. + 2. If all is good, `git push origin main` your signatures. -2. Compose a short release blurb to highlight the user-facing - 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 - to a release-* branch, manually commit the changelogs to the later - git branches too. +Once all signatures from all selected developers have been committed: -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. + 1. Manually trigger the `signature` job in the `Post-process` stage of the + CI release pipeline. -4. If you're doing the first stable release in a series, you need to - 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.) + 2. If it passes, the tarball(s) and signature(s) will be available as + artifacts and should be used for the release. -## III. Making the source release. + 3. Put them on `dist.torproject.org`: -1. In `maint-0.?.x`, bump the version number in `configure.ac` and run - `make update-versions` to update version numbers in other - places, and commit. Then merge `maint-0.?.x` into `release-0.?.x`. + Upload the tarball and its sig to the dist website, i.e. + `/srv/dist-master.torproject.org/htdocs/` on dist-master. Run + "static-update-component dist.torproject.org" on dist-master. - When you merge the maint branch forward to the next maint branch, or into - master, merge it with "-s ours" to avoid conflict with the version - bump. + In the `project/web/tpo.git` repository, update `databags/versions.ini` + to note the new version. Push these changes to `master`. -2. Make distcheck, put the tarball up in somewhere (how about your - homedir on people.torproject.org?) , and tell `#tor-dev` - about it. + (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.) - 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.) + (NOTE: It will take a while for the website update scripts to update the + website.) -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. +## 3. Post Process -## IV. Commit, upload, announce +Once the tarballs have been uploaded and are ready to be announced, we need to +do the following: -1. Sign the tarball, then sign and push the git tag: + 1. Tag versions (main and maint) using `git tag -s tor-0.x.y.z-<status>` + and then push the tags: `git push origin --tags` -```console -$ gpg -ba <the_tarball> -$ git tag -s tor-0.4.x.y-<status> -$ git push origin tag tor-0.4.x.y-<status> -``` + 2. Merge upstream the artifacts from the `patches` job in the + `Post-process` stage of the CI release pipeline. - (You must do this before you update the website: the website scripts - rely on finding the version by tag.) + 3. Write and post the release announcement for the `forum.torproject.net` + in the `News -> Tor Release Announcement` category. - (If your default PGP key is not the one you want to sign with, then say - "-u <keyid>" instead of "-s".) + If possible, mention in which Tor Browser version (with dates) the + release will be in. This usually only applies to the latest stable. -2. scp the tarball and its sig to the dist website, i.e. - `/srv/dist-master.torproject.org/htdocs/` on dist-master. Run - "static-update-component dist.torproject.org" on dist-master. + 4. Inform `tor-talk@lists.torproject.org` with the releasing pointing to + the Forum. Append the ChangeLog there. We do this until we can automate + such post from the forum directly. - In the project/web/tpo.git repository, update `databags/versions.ini` - to note the new version. Push these changes to master. +### New Stable - (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.) + 1. Create the `maint-x.y.z` and `release-x.y.z` branches and update the + `./scripts/git/git-list-tor-branches.sh` with the new version. - (NOTE: It will take a while for the website update scripts to update - the website.) + 2. Add the new version in `./scripts/ci/ci-driver.sh`. -3. Email the tor-packagers@lists.torproject.org mailing list to tell them - about the new release. + 3. Forward port the ChangeLog and ReleaseNotes into main branch. Remove any + change logs of stable releases in ReleaseNotes. - Also, email tor-packagers@lists.torproject.org. - Mention where to download the tarball (https://dist.torproject.org). +## Appendix: An alternative means to notify packagers - Include a link to the changelog. +If for some reason you need to contact a bunch of packagers without +using the publicly archived tor-packagers list, you can try these +people: -4. Wait for the download page to be updated. (If you don't do this before you - announce, people will be confused.) - -5. Mail the release blurb and ChangeLog to tor-talk (development release) or - tor-announce (stable). - - Post the changelog on the blog as well. You can generate a - blog-formatted version of the changelog with - `./scripts/maint/format_changelog.py -B` - - 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. - - For templates to use when announcing, see: - https://gitlab.torproject.org/tpo/core/team/-/wikis/NetworkTeam/AnnouncementTemplates - -## V. Aftermath and cleanup - -1. If it's a stable release, bump the version number in the - `maint-x.y.z` branch to "newversion-dev", and do a `merge -s ours` - merge to avoid taking that change into master. - -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.) - -3. Forward-port the ChangeLog (and ReleaseNotes if appropriate) to the - master branch. - -4. Keep an eye on the blog post, to moderate comments and answer questions. + - {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 + - {security} at brave.com |