Prepare stable release 12.0.3
Explanation of variables
-
$(BUILD_SERVER)
: the server the main builder is using to build a tor-browser release -
$(STAGING_SERVER)
: the server the signer is using to to run the signing process -
$(ESR_VERSION)
: the Mozilla defined ESR version, used in various places for building tor-browser tags, labels, etc- example :
91.6.0
- example :
-
$(RR_VERSION)
: the Mozilla defined Rapid-Release version; Tor Browser for Android is based off of the$(ESR_VERSION)
, but Mozilla's Firefox for Android is based off of the$(RR_VERSION)
so we need to keep track of security vulnerabilities to backport from the monthly Rapid-Release train and our frozen ESR train.- example:
103
- example:
-
$(ESR_TAG)
: the Mozilla defined hg (Mercurial) tag associated with$(ESR_VERSION)
- exmaple :
FIREFOX_91_7_0esr_BUILD2
- exmaple :
-
$(ESR_TAG_PREV)
: the Mozilla defined hg (Mercurial) tag associated with the previous ESR version when rebasing (ie, the ESR version we are rebasing from) -
$(TOR_BROWSER_MAJOR)
: the Tor Browser major version- example :
11
- example :
-
$(TOR_BROWSER_MINOR)
: the Tor Browser minor version- example : either
0
or5
; Alpha's is always(Stable + 5) % 10
- example : either
-
$(BUILD_N)
: a project's build revision within a its branch; this is separate from the$(TOR_BROWSER_BUILD_N)
value; many of the Firefox-related projects have a$(BUILD_N)
suffix and may differ between projects even when they contribute to the same build.- example :
build1
- example :
-
$(TOR_BROWSER_BUILD_N)
: the tor-browser build revision for a given Tor Browser release; used in tagging git commits- example :
build2
-
NOTE : A project's
$(BUILD_N)
and$(TOR_BROWSER_BUILD_N)
may be the same, but it is possible for them to diverge. For example :- if we have multiple Tor Browser releases on a given ESR branch the two will become out of sync as the
$(BUILD_N)
value will increase, while the$(TOR_BROWSER_BUILD_N)
value may stay atbuild1
(but the$(TOR_BROWSER_VERSION)
will increase) - if we have build failures unrelated to
tor-browser
, the$(TOR_BROWSER_BUILD_N)
value will increase while the$(BUILD_N)
will stay the same.
- if we have multiple Tor Browser releases on a given ESR branch the two will become out of sync as the
- example :
-
$(TOR_BROWSER_VERSION)
: the published Tor Browser version- example :
11.5a6
,11.0.7
- example :
-
$(TOR_BROWSER_BRANCH)
: the full name of tor-browser branch- typically of the form:
tor-browser-$(ESR_VERSION)esr-$(TOR_BROWSER_MAJOR).$(TOR-BROWSER_MINOR)-1
- typically of the form:
-
$(TOR_BROWSER_BRANCH_PREV)
: the full name of the previous tor-browser branch (when rebasing)
Android
https://www.mozilla.org/en-US/security/advisories/
Security Vulnerabilities Backport :-
Create tor-browser issue Backport Android-specific Firefox $(RR_VERSION) to ESR $(ESR_VERSION)-based Tor Browser
-
Link new backport issue to this release prep issue
-
-
Go through any Security Vulnerabilities fixed in Firefox $(RR_VERSION)
(or similar) and create list of CVEs which affect Android that need to be a backported- Potentially Affected Components:
-
firefox
/geckoview
application-services
android-components
fenix
-
- Potentially Affected Components:
application-services (Optional) : TODO: we need to setup a gitlab copy of this repo that we can apply security backports to
-
Backport any Android-specific security fixes from Firefox rapid-release -
Sign/Tag commit: - Tag :
application-services-$(ESR_VERSION)-$(TOR_BROWSER_MAJOR).$(TOR_BROWSER_MINOR)-1-$(BUILD_N)
- Message:
Tagging $(BUILD_N) for $(ESR_VERSION)-based stable
- Tag :
-
Push tag to origin
https://gitlab.torproject.org/tpo/applications/android-components.git
android-components (Optional) :-
Backport any Android-specific security fixes from Firefox rapid-release -
Sign/Tag commit: - Tag :
android-components-$(ESR_VERSION)-$(TOR_BROWSER_MAJOR).$(TOR_BROWSER_MINOR)-1-$(BUILD_N)
- Message:
Tagging $(BUILD_N) for $(ESR_VERSION)-based stable)
- Tag :
-
Push tag to origin
https://gitlab.torproject.org/tpo/applications/fenix.git
fenix (Optional) :-
Backport any Android-specific security fixes from Firefox rapid-release -
Sign/Tag commit: - Tag :
tor-browser-$(ESR_VERSION)-$(TOR_BROWSER_MAJOR).$(TOR_BROWSER_MINOR)-1-$(BUILD_N)
- Message:
Tagging $(BUILD_N) for $(ESR_VERSION)-based stable)
- Tag :
-
Push tag to origin
Shared
https://gitlab.torproject.org/tpo/applications/tor-browser.git
tor-browser:-
(Optional) Backport any Android-specific security fixes from Firefox rapid-release -
(Optional, Chemspill) Backport security-fixes to both tor-browser
andbase-browser
branches -
(Optional) Rebase to $(ESR_VERSION)
-
Find the Firefox hg tag here : https://hg.mozilla.org/releases/mozilla-esr102/tags -
$(ESR_TAG)
:FIREFOX_102_8_0esr_BUILD1
-
-
Identify the hg patch associated with above hg tag, and find the equivalent gecko-dev
git commit (search by commit message)-
gecko-dev
commit : tor-browser@3a3a96c9 -
Sign/Tag gecko-dev
commit :- Tag :
$(ESR_TAG)
- Message :
Hg tag $(ESR_TAG)
- Tag :
-
-
Create new tor-browser
branch with the discoveredgecko-dev
commit asHEAD
named:tor-browser-$(ESR_VERSION)esr-$(TOR_BROWSER_MAJOR).$(TOR-BROWSER_MINOR)-1
-
Push new branches and esr tag to origin -
Rebase previous tor-browser
patches onto the newgecko-dev
branch -
Compare patch-sets (ensure nothing weird happened during rebase): -
rangediff: git range-diff $(ESR_TAG_PREV)..$(TOR_BROWSER_BRANCH_PREV) $(ESR_TAG)..$(TOR_BROWSER_BRANCH)
-
diff of diffs: - Do the diff between
current_patchset.diff
andrebased_patchset.diff
with your preferred$(DIFF_TOOL)
and look at differences on lines that starts with + or - -
git diff $(ESR_TAG_PREV)..$(TOR_BROWSER_BRANCH_PREV) > current_patchset.diff
-
git diff $(ESR_TAG)..$(TOR_BROWSER_BRANCH) > rebased_patchset.diff
-
$(DIFF_TOOL) current_patchset.diff rebased_patchset.diff
- Do the diff between
-
-
Open MR for the rebase -
Merge
-
-
Sign/Tag tor-browser
commit :- Tag :
tor-browser-$(ESR_VERSION)esr-$(TOR_BROWSER_MAJOR).$(TOR_BROWSER_MINOR)-1-$(FIREFOX_BUILD_N)
- Message :
Tagging $(FIREFOX_BUILD_N) for $(ESR_VERSION)esr-based stable
- Tag :
-
Create base-browser
branch from rebasedtor-browser
branch named:base-browser-$(ESR_VERSION)esr-$(TOR_BROWSER_MAJOR).$(TOR-BROWSER_MINOR)-1
-
NOTE : Currently we are using the
Bug 40926: Implemented the New Identity feature
commit as the final commit ofbase-browser
beforetor-browser
-
Sign/Tag base-browser
commit:- Tag :
base-browser-$(ESR_VERSION)esr-$(TOR_BROWSER_MAJOR).$(TOR_BROWSER_MINOR)-1-build1
- Message:
Tagging build1 for $(ESR_VERSION)esr-based stable
- Tag :
-
Push tags to origin
Build
https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
tor-browser-build:Tor Browser Stable lives in the various maint-$(TOR_BROWSER_MAJOR).$(TOR_BROWSER_MINOR)
(and possibly more specific) branches
-
Update rbm.conf
-
var/torbrowser_version
: update to next version -
var/torbrowser_build
: update to$(TOR_BROWSER_BUILD_N)
-
(Optional, Desktop) var/torbrowser_incremental_from
: update to previous Desktop version-
IMPORTANT: Really actually make sure this is the previous Desktop version or else the make incrementals-*
step will fail
-
-
-
(Optional) Update Desktop-specific build configs -
Update projects/firefox/config
-
git_hash
: update the$(BUILD_N)
section to matchtor-browser
tag -
(Optional) var/firefox_platform_version
: update to latest$(ESR_VERSION)
if rebased
-
-
Update projects/translation/config
:-
run make list_translation_updates-release
to get updated hashes -
steps/base-browser/git_hash
: update withHEAD
commit of project'sbase-browser
branch -
steps/base-browser-fluent/git_hash
: update withHEAD
commit of project'sbasebrowser-newidentityftl
branch -
steps/tor-browser/git_hash
: update withHEAD
commit of project'stor-browser
branch -
steps/fenix/git_hash
: update withHEAD
commit of project'sfenix-torbrowserstringsxml
branch
-
-
-
(Optional) Update Android-specific build configs -
(Optional) Update projects/geckoview/config
-
git_hash
: update the$(BUILD_N)
section to matchtor-browser
tag -
(Optional) var/geckoview_version
: update to latest$(ESR_VERSION)
if rebased
-
-
(Optional) Update projects/tor-android-service/config
-
git_hash
: update withHEAD
commit of project'smain
branch
-
-
(Optional) Update projects/application-services/config
: NOTE we don't currently have any of our own patches for this project-
git_hash
: update to appropriate git commit associated with$(ESR_VERSION)
-
-
(Optional) Update projects/android-components/config
:-
git_hash
: update the$(BUILD_N)
section to matchandroid-components
tag
-
-
(Optional) Update projects/fenix/config
-
git_hash
: update the$(BUILD_N)
section to matchfenix
tag -
(Optional) var/fenix_version
: update to latest$(ESR_VERSION)
if rebased
-
-
Update allowed_addons.json by running (from tor-browser-build
root):./tools/fetch_allowed_addons.py > projects/browser/allowed_addons.json
-
-
Update common build configs -
Check for NoScript updates here : https://addons.mozilla.org/en-US/firefox/addon/noscript -
(Optional) If new version available, update noscript
section ofinput_files
inprojects/browser/config
-
URL
-
sha256sum
-
-
-
Check for OpenSSL updates here : https://www.openssl.org/source/ -
(Optional) If new 1.X.Y version available, update projects/openssl/config
-
version
: update to next 1.X.Y version -
input_files/sha256sum
: update to sha256 sum of source tarball
-
-
-
Check for zlib updates here: https://github.com/madler/zlib/releases -
(Optional) If new tag available, update projects/zlib/config
-
version
: update to next release tag
-
-
-
Check for tor updates here : https://gitlab.torproject.org/tpo/core/tor/-/tags -
(Optional) Update projects/tor/config
-
version
: update to latest non-alpha
tag (ping dgoulet or ahf if unsure)
-
-
-
Check for go updates here : https://golang.org/dl - NOTE : Tor Browser Stable uses the latest of the previous Stable major series go version (apart from the transition phase from Tor Browser Alpha to Stable, in which case Tor Browser Stable may use the latest major series go version)
-
(Optional) Update projects/go/config
-
version
: update go version -
input_files/sha256sum
forgo
: update sha256sum of archive (sha256 sums are displayed on the go download page)
-
-
(Optional) Update the manual : https://gitlab.torproject.org/tpo/web/manual/-/jobs/ -
Download the artifacts.zip
file from latest build stage row (download icon button on the right) -
Rename it to manual_$PIPELINEID.zip
-
Upload it to people.tpo -
Update projects/manual/config
-
Change the version to $PIPELINEID
-
Update the hash in the input_files section -
Update the URL if you have uploaded to a different people.tpo home
-
-
-
-
Update ChangeLog.txt
-
Ensure ChangeLog.txt is sync'd between alpha and stable branches -
Check the linked issues: ask people to check if any are missing, remove the not fixed ones -
Run tools/fetch-changelogs.py $(TOR_BROWSER_VERSION)
ortools/fetch-changelogs.py '#$(ISSUE_NUMBER)'
- Make sure you have
requests
installed (e.g.,apt install python3-requests
) - The first time you run this script you will need to generate an access token; the script will guide you
- Make sure you have
-
Copy the output of the script to the beginning of ChangeLog.txt
and adjust its output- At the moment, the script does not create a Build System section
- If you used the issue number, you will need to write the Tor Browser version manually
-
-
Open MR with above changes -
Begin build on $(BUILD_SERVER)
(and fix any issues which come up and update MR) -
Merge -
Sign/Tag commit: make signtag-release
-
Push tag to origin
Communications
notify stakeholders
-
Email tor-qa mailing list: tor-qa@lists.torproject.org -
Provide links to unsigned builds on $(BUILD_SERVER)
-
Note any new functionality which needs testing -
Link to any known issues
-
-
Email downstream consumers: - Recipients:
-
Tails dev mailing list: tails-dev@boum.org -
Guardian Project: nathan@guardianproject.info -
torbrowser-launcher: micah@micahflee.com -
FreeBSD port: freebsd@sysctl.cz -
OpenBSD port: caspar@schutijser.com
-
-
Provide links to unsigned builds on $(BUILD_SERVER)
-
Note any changes which may affect packaging/downstream integration
- Recipients:
-
Email upstream stakeholders: -
(Optional, after ESR migration) Cloudflare: ask-research@cloudflare.com - NOTE : We need to provide them with updated user agent string so they can update their internal machinery to prevent Tor Browser users from getting so many CAPTCHAs
-
Signing/Publishing
signing + publishing
-
Ensure builders have matching builds -
On $(STAGING_SERVER)
, ensure updated:-
tor-browser-build/tools/signing/set-config
-
NSS_DB_DIR
: location of thenssdb7
directory
-
-
tor-browser-build/tools/signing/set-config.hosts
-
ssh_host_builder
: ssh hostname of machine with unsigned builds-
NOTE :
tor-browser-build
is expected to be in the$HOME
directory)
-
NOTE :
-
ssh_host_linux_signer
: ssh hostname of linux signing machine -
ssh_host_macos_signer
: ssh hostname of macOS signing machine
-
-
tor-browser-build/tools/signing/set-config.macos-notarization
-
macos_notarization_user
: the email login for a tor notariser Apple Developer account
-
-
set-config.update-responses
-
update_responses_repository_dir
: directory where you clonedgit@gitlab.torproject.org:tpo/applications/tor-browser-update-responses.git
-
-
tor-browser-build/tools/signing/set-config.tbb-version
-
tbb_version
: tor browser version string, same asvar/torbrowser_version
inrbm.conf
(examples:11.5a12
,11.0.13
) -
tbb_version_build
: the tor-browser-build build number (ifvar/torbrowser_build
inrbm.conf
isbuildN
then this value isN
) -
tbb_version_type
: eitheralpha
for alpha releases orrelease
for stable releases
-
-
-
On $(STAGING_SERVER)
in a separatescreen
session, run the macOS proxy script:cd tor-browser-build/tools/signing/
./macos-signer-proxy
-
On $(STAGING_SERVER)
in a separatescreen
session, ensure tor daemon is running with SOCKS5 proxy on the default port 9050 -
apk signing : copy signed *multi.apk
files to the unsigned build outputs directory -
run do-all-signing script: cd tor-browser-build/tools/signing/
./do-all-signing.sh
-
NOTE: at this point the signed binaries should have been copied to
staticiforme
-
Update staticiforme.torproject.org
:- From
screen
session onstaticiforme.torproject.org
: -
Remove old release data from following places: - NOTE : Skip this step if the current release is Android or Desktop only
-
/srv/cdn-master.torproject.org/htdocs/aus1/torbrowser
-
/srv/dist-master.torproject.org/htdocs/torbrowser
-
Static update components : static-update-component cdn.torproject.org && static-update-component dist.torproject.org
-
Enable update responses : sudo -u tb-release ./deploy_update_responses-release.sh
- From
-
Publish APKs to Google Play: - Log into https://play.google.com/apps/publish
- Select
Tor Browser
app - Navigate to
Release > Production
and clickCreate new release
button -
Upload the *.multi.apk
APKs -
Update Release Name to Tor Browser version number -
Update Release Notes - Next to 'Release notes', click
Copy from a previous release
-
Edit blog post url to point to most recent blog post
- Next to 'Release notes', click
- Save, review, and configure rollout percentage
-
25% rollout when publishing a scheduled update -
100% rollout when publishing a security-driven release
-
-
Update rollout percentage to 100% after confirmed no major issues
https://gitlab.torproject.org/tpo/web/tpo.git
website:-
databags/versions.ini
: Update the downloads versions-
torbrowser-stable/version
: sort of a catch-all for latest stable version -
torbrowser-alpha/version
: sort of a catch-all for latest stable version -
torbrowser-*-stable/version
: platform-specific stable versions -
torbrowser-*-alpha/version
: platform-specific alpha versions -
tor-stable
,tor-alpha
: set by tor devs, do not touch
-
-
Push to origin as new branch, open 'Draft :' MR -
Remove Draft:
from MR once signed-packages are uploaded -
Merge -
Publish after CI passes and builds are published
https://gitlab.torproject.org/tpo/web/blog.git
blog:-
Duplicate previous Stable or Alpha release blog post as appropriate to new directory under content/blog/new-release-tor-browser-$(TOR_BROWSER_VERSION)
and update with info on release :-
Update Tor Browser version numbers -
Note any ESR rebase -
Link to any Firefox security updates from ESR upgrade -
Link to any Android-specific security backports -
Note any updates to : - tor
- OpenSSL
- NoScript
-
Convert ChangeLog.txt to markdown format used here by : tor-browser-build/tools/changelog-format-blog-post
-
-
Push to origin as new branch, open Draft:
MR -
Remove Draft:
from MR once signed-packages are uploaded -
Merge -
Publish after CI passes and website has been updated
tor-announce mailing list
-
Send an email to tor-announce@lists.torproject.org, using the same content as the blog post and subject "Tor Browser $version is released".
Edited by morgan