.gitignore

-git_clones
-hg_clones
-out
-release
-alpha
-alpha_nightly
-nightly
-hardened
-rbm.local.conf
+/git_clones
+/hg_clones
+/gclient
+/out
+/torbrowser
+/basebrowser
+/mullvadbrowser
+/testbuild
+/rbm.local.conf
+/logs
+/tmp
+
+# Old build directories, let's keep them anyway
+/release
+/alpha
+/nightly
+
+# This file is used to test the updater, and whoever is interested in doing so,
+# should provide their file.
+/projects/firefox/marsigner.der

.gitlab/issue_templates/Backport.md

+<!--
+Title:
+    Backport tor-browser-build-browser#12345: Title of Issue
+
+This is an issue for tracking back-porting a patch-set (e.g. from main to maint-14.0)
+-->
+
+## Backport Patchset
+
+### Book-keeping
+
+#### Gitlab Issue(s)
+- tor-browser#12345
+- mullvad-browser#123
+- tor-browser-build#12345
+
+#### Merge Request(s)
+- tor-browser-build!1234
+
+#### Target Channels
+
+- [ ] maint-14.0
+- [ ] maint-13.5
+
+### Notes
+
+<!-- whatever additional info, context, etc that would be helpful for backporting -->
+
+/label ~"Apps::Type::Backport"

.gitlab/issue_templates/Release Prep - Mullvad Browser Alpha.md

+# Release Prep Mullvad Browser Alpha
+
+- **NOTE** It is assumed the `mullvad-browser` alpha rebase and security backport tasks have been completed
+- **NOTE** This can/is often done in conjunction with the equivalent Tor Browser release prep issue
+
+<details>
+  <summary>Explanation of variables</summary>
+
+- `${BUILD_SERVER}`: the server the main builder is using to build a browser release
+- `${BUILDER}`: whomever is building the release on the ${BUILD_SERVER}
+  - **example**: `pierov`
+- `${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 browser tags, labels, etc
+  - **example**: `91.6.0`
+- `${MULLVAD_BROWSER_MAJOR}`: the Mullvad Browser major version
+  - **example**: `11`
+- `${MULLVAD_BROWSER_MINOR}`: the Mullvad Browser minor version
+  - **example**: either `0` or `5`; Alpha's is always `(Stable + 5) % 10`
+- `${MULLVAD_BROWSER_VERSION}`: the Mullvad Browser version in the format
+  - **example**: `12.5a3`, `12.0.3`
+- `${BUILD_N}`: a project's build revision within a its branch; this is separate from the `${MULLVAD_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`
+- `${MULLVAD_BROWSER_BUILD_N}`: the mullvad-browser build revision for a given Mullvad Browser release; used in tagging git commits
+  - **example**: `build2`
+    - **⚠️ WARNING**: A project's `${BUILD_N}` and `${MULLVAD_BROWSER_BUILD_N}` may be the same, but it is possible for them to diverge. For **example** :
+      - if we have multiple Mullvad Browser releases on a given ESR branch the two will become out of sync as the `${BUILD_N}` value will increase, while the `${MULLVAD_BROWSER_BUILD_N}` value may stay at `build1` (but the `${MULLVAD_BROWSER_VERSION}` will increase)
+      - if we have build failures unrelated to `mullvad-browser`, the `${MULLVAD_BROWSER_BUILD_N}` value will increase while the `${BUILD_N}` will stay the same.
+- `${MULLVAD_BROWSER_VERSION}`: the published Mullvad Browser version
+    - **example**: `11.5a6`, `11.0.7`
+- `${MB_BUILD_TAG}`: the `tor-browser-build` build tag used to build a given Mullvad Browser version
+  - **example**: `mb-12.0.7-build1`
+- `${RELEASE_DATE}`: the intended release date of this browser release; for ESR schedule-driven releases, this should match the upstream Firefox release date
+  - **example**: `2024-10-29`
+
+</details>
+
+<details>
+  <summary>Build Configuration</summary>
+
+### mullvad-browser: https://gitlab.torproject.org/tpo/applications/mullvad-browser.git
+
+- [ ] Tag `mullvad-browser` commit:
+  - **example**: `mullvad-browser-128.4.0esr-14.5-1-build1`
+  - Run:
+    ```bash
+    ./tools/browser/sign-tag.mullvadbrowser alpha ${BUILD_N}
+    ```
+
+### tor-browser-build: https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
+Mullvad Browser Alpha (and Nightly) are on the `main` branch
+
+- [ ] Changelog bookkeeping:
+  - Ensure all commits to `mullvad-browser` and `tor-browser-build` for this release have an associated issue linked to this release preparation issue
+  - Ensure each issue has a platform (~Windows, ~MacOS, ~Linux, ~Desktop, ~"All Platforms") and potentially ~"Build System" labels
+- [ ] Create a release preparation branch from the `main` branch
+- [ ] Run release preparation script:
+  - **NOTE**: You can omit the `--mullvad-browser` argument if this is for a joint Tor and Mullvad Browser release
+  - **⚠️ WARNING**: You may need to manually update the `firefox/config` file's `browser_build` field if `mullvad-browser.git` has not yet been tagged (e.g. if security backports have not yet been merged and tagged)
+  ```bash
+  ./tools/relprep.py --mullvad-browser  --date ${RELEASE_DATE} ${MULLVAD_BROWSER_VERSION}
+  ```
+- [ ] Review build configuration changes:
+  - [ ] `rbm.conf`
+    - [ ] `var/torbrowser_version`: updated to next browser version
+    - [ ] `var/torbrowser_build`: updated to `${MULLVAD_BROWSER_BUILD_N}`
+    - [ ] `var/browser_release_date`: updated to build date. For the build to be reproducible, the date should be in the past when building.
+      - **⚠️ WARNING**: If we have updated `var/torbrowser_build` without updating the `firefox` tag, then we can leave this unchanged to avoid forcing a firefox re-build (e.g. when bumping `var/torbrowser_build` to build2, build3, etc due to non-firefox related build issues)
+    - [ ] `var/browser_platforms`: updated to enable the platforms included in this release
+    - [ ] `var/torbrowser_incremental_from`: updated to previous Desktop version
+      - **NOTE**: We try to build incrementals for the previous 3 desktop versions
+      - **⚠️ WARNING**: Really *actually* make sure this is the previous Desktop version or else the `make mullvadbrowser-incrementals-*` step will fail
+  - [ ] `projects/firefox/config`
+    - [ ] `browser_build`: updated to match `mullvad-browser` tag
+    - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] ***(Optional)*** `projects/translation/config`:
+    - [ ] `steps/base-browser/git_hash`: updated with `HEAD` commit of project's `base-browser` branch
+    - [ ] `steps/mullvad-browser/git_hash`: updated with `HEAD` commit of project's `mullvad-browser` branch
+  - [ ] ***(Optional)*** `projects/browser/config`:
+    - [ ] ***(Optional)***  NoScript: https://addons.mozilla.org/en-US/firefox/addon/noscript
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+    - [ ] ***(Optional)*** uBlock-origin: https://addons.mozilla.org/en-US/firefox/addon/ublock-origin
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+    - [ ] ***(Optional)*** Mullvad Browser extension: https://github.com/mullvad/browser-extension/releases
+      - [ ] `URL` updated
+      - [ ] `sha256sum` updated
+  - [ ] `ChangeLog-MB.txt`: ensure correctness
+    - Browser name correct
+    - Release date correct
+    - No Android updates
+    - All issues added under correct platform
+    - ESR updates correct
+    - Component updates correct
+- [ ] Open MR with above changes, using the template for release preparations
+  - **NOTE**: target the `main` branch
+- [ ] Merge
+- [ ] Sign+Tag
+  - **NOTE** this must be done by one of:
+    - boklm
+    - dan
+    - ma1
+    - morgan
+    - pierov
+  - Run:
+    ```bash
+    make mullvadbrowser-signtag-alpha
+    ```
+- [ ] Push tag to `upstream`
+- [ ] Build the tag:
+  - Run:
+    ```bash
+    make mullvadbrowser
+    ```
+    - [ ] Tor Project build machine
+    - [ ] Local developer machine
+  - [ ] Submit build request to Mullvad infrastructure:
+    - **NOTE** this requires a github authentication token
+    - Run:
+      ```bash
+      make mullvadbrowser-kick-devmole-build
+      ```
+
+</details>
+
+<details>
+  <summary>Signing</summary>
+
+### release signing
+- [ ] Assign this issue to the signer, one of:
+  - boklm
+  - ma1
+  - morgan
+  - pierov
+- [ ] Ensure all builders have matching builds
+- [ ] On `${STAGING_SERVER}`, ensure updated:
+  - **NOTE** Having a local git branch with `main` as the upstream branch with these values saved means you only need to periodically `git pull --rebase`
+  - [ ] `tor-browser-build` is on the right commit: `git tag -v mb-${MULLVAD_BROWSER_VERSION}-${MULLVAD_BROWSER_BUILD_N} && git checkout mb-${MULLVAD_BROWSER_VERSION}-${MULLVAD_BROWSER_BUILD_N}`
+  - [ ] `tor-browser-build/tools/signing/set-config.hosts`
+    - `ssh_host_builder`: ssh hostname of machine with unsigned builds
+    - `ssh_host_linux_signer`: ssh hostname of linux signing machine
+    - `builder_tor_browser_build_dir`: path on `ssh_host_builder` to root of builder's `tor-browser-build` clone containing unsigned builds
+  - [ ] `tor-browser-build/tools/signing/set-config.rcodesign-appstoreconnect`
+    - `appstoreconnect_api_key_path`: path to json file containing appstoreconnect api key infos
+  - [ ] `set-config.update-responses`
+    - `update_responses_repository_dir`: directory where you cloned `git@gitlab.torproject.org:tpo/applications/mullvad-browser-update-responses.git`
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, ensure tor daemon is running with SOCKS5 proxy on the default port 9050
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, run do-all-signing script:
+  - Run:
+    ```bash
+    cd tor-browser-build/tools/signing/ && ./do-all-signing.mullvadbrowser
+    ```
+  - **NOTE**: on successful execution, the signed binaries and mars should have been copied to `staticiforme` and update responses pushed
+
+</details>
+
+<details>
+  <summary>Publishing</summary>
+
+### website
+- [ ] On `staticiforme.torproject.org`, remove old release and publish new:
+  - [ ] `/srv/dist-master.torproject.org/htdocs/mullvadbrowser`
+  - Run:
+    ```bash
+    static-update-component dist.torproject.org
+    ```
+
+### mullvad-browser (GitHub): https://github.com/mullvad/mullvad-browser/
+- [ ] Assign this issue to someone with mullvad commit access, one of:
+    - boklm
+    - ma1
+    - morgan
+    - pierov
+- [ ] Sign+Tag additionally the `mullvad-browser.git` `firefox` commit used in build:
+  - **Tag**: `${MULLVAD_BROWSER_VERSION}`
+    - **example**: `12.5a7`
+  - **Message**: `${ESR_VERSION}esr-based ${MULLVAD_BROWSER_VERSION}`
+    - **example**: `102.12.0esr-based 12.5a7`
+- [ ] Push this release's associated `mullvad-browser.git` branch to github
+- [ ] Push this release's associated tags to github:
+  - [ ] Firefox ESR tag
+    - **example**: `FIREFOX_102_12_0esr_BUILD1`
+  - [ ] `base-browser` tag
+    - **example**: `base-browser-102.12.0esr-12.0-1-build1`
+  - [ ] `mullvad-browser` build tag
+    - **example**: `mullvad-browser-102.12.0esr-12.0-1-build1`
+  - [ ] `mullvad-browser` release tag
+    - **example**: `12.0.11`
+
+</details>
+
+<details>
+  <summary>Communications</summary>
+
+### Mullvad
+- [ ] Email Mullvad with release information:
+  - **Recipients**
+    - Mullvad support alias: support@mullvadvpn.net
+    - Rui Hildt: rui@mullvad.net
+    ```
+    support@mullvadvpn.net, rui@mullvad.net,
+    ```
+  - **Subject**
+    ```
+    New build: Mullvad Browser ${MULLVAD_BROWSER_VERSION} (signed)
+    ```
+  - **Body**
+    ```
+    Hello,
+
+    Branch+Tags have been pushed to Mullvad's GitHub repo.
+
+    - signed builds: https://dist.torproject.org/mullvadbrowser/${MULLVAD_BROWSER_VERSION}
+    - update_response hashes: ${MULLVAD_UPDATE_RESPONSES_HASH}
+
+    * https://gitlab.torproject.org/tpo/applications/mullvad-browser-update-responses
+
+    changelog:
+    # paste changelog as quote here
+    ...
+    ```
+
+### packagers
+- [ ] **(Optional, Once Packages are pushed to GitHub)**
+  - **NOTE**: This is an optional step and only necessary close a major release/transition from alpha to stable, or if there are major packing changes these developers need to be aware of
+  - **Recipients**
+    - flathub package maintainer: proletarius101@protonmail.com
+    - arch package maintainer: bootctl@gmail.com
+    - nixOS package maintainer: dev@felschr.com
+    ```
+    proletarius101@protonmail.com, bootctl@gmail.com, dev@felschr.com,
+    ```
+  - **Subject**
+    ```
+    Mullvad Browser ${MULLVAD_BROWSER_VERSION} released
+    ```
+  - **Body**
+    ```
+    Hello!
+
+    This is a major alpha release which may require changes in your respective downstream packages once it stabilises.
+
+    The latest alpha builds can be found here:
+
+    - https://github.com/mullvad/mullvad-browser/releases?q=prerelease%3Atrue
+    ```
+
+</details>
+
+/label ~"Apps::Type::ReleasePreparation"
+/label ~"Sponsor 131"

.gitlab/issue_templates/Release Prep - Mullvad Browser Stable.md

+# Release Prep Mullvad Browser Stable
+
+- **NOTE** It is assumed the `mullvad-browser` release rebase and security backport tasks have been completed
+- **NOTE** This can/is often done in conjunction with the equivalent Tor Browser release prep issue
+
+<details>
+  <summary>Explanation of variables</summary>
+
+- `${BUILD_SERVER}`: the server the main builder is using to build a browser release
+- `${BUILDER}`: whomever is building the release on the ${BUILD_SERVER}
+  - **example**: `pierov`
+- `${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 browser tags, labels, etc
+  - **example**: `91.6.0`
+- `${MULLVAD_BROWSER_MAJOR}`: the Mullvad Browser major version
+  - **example**: `11`
+- `${MULLVAD_BROWSER_MINOR}`: the Mullvad Browser minor version
+  - **example**: either `0` or `5`; Alpha's is always `(Stable + 5) % 10`
+- `${MULLVAD_BROWSER_VERSION}`: the Mullvad Browser version in the format
+  - **example**: `12.5a3`, `12.0.3`
+- `${BUILD_N}`: a project's build revision within a its branch; this is separate from the `${MULLVAD_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`
+- `${MULLVAD_BROWSER_BUILD_N}`: the mullvad-browser build revision for a given Mullvad Browser release; used in tagging git commits
+  - **example**: `build2`
+    - **⚠️ WARNING**: A project's `${BUILD_N}` and `${MULLVAD_BROWSER_BUILD_N}` may be the same, but it is possible for them to diverge. For **example** :
+      - if we have multiple Mullvad Browser releases on a given ESR branch the two will become out of sync as the `${BUILD_N}` value will increase, while the `${MULLVAD_BROWSER_BUILD_N}` value may stay at `build1` (but the `${MULLVAD_BROWSER_VERSION}` will increase)
+      - if we have build failures unrelated to `mullvad-browser`, the `${MULLVAD_BROWSER_BUILD_N}` value will increase while the `${BUILD_N}` will stay the same.
+- `${MULLVAD_BROWSER_VERSION}`: the published Mullvad Browser version
+    - **example**: `11.5a6`, `11.0.7`
+- `${MB_BUILD_TAG}`: the `tor-browser-build` build tag used to build a given Mullvad Browser version
+   - **example**: `mb-12.0.7-build1`
+- `${RELEASE_DATE}`: the intended release date of this browser release; for ESR schedule-driven releases, this should match the upstream Firefox release date
+  - **example**: `2024-10-29`
+
+</details>
+
+<details>
+  <summary>Build Configuration</summary>
+
+### mullvad-browser: https://gitlab.torproject.org/tpo/applications/mullvad-browser.git
+
+- [ ] Tag `mullvad-browser` commit:
+  - **example**: `mullvad-browser-128.3.0esr-14.0-1-build1`
+  - Run:
+    ```bash
+    ./tools/browser/sign-tag.mullvadbrowser stable ${BUILD_N}
+    ```
+
+### tor-browser-build: https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
+Mullvad Browser Stable is on the `maint-${MULLVAD_BROWSER_MAJOR}.${MULLVAD_BROWSER_MINOR}` branch
+
+- [ ] Changelog bookkeeping:
+  - Ensure all commits to `mullvad-browser` and `tor-browser-build` for this release have an associated issue linked to this release preparation issue
+  - Ensure each issue has a platform (~Windows, ~MacOS, ~Linux, ~Desktop, ~"All Platforms") and potentially ~"Build System" labels
+- [ ] Create a release preparation branch from the current `maint-XX.Y` branch
+- [ ] Run release preparation script:
+  - **NOTE**: You can omit the `--mullvad-browser` argument if this is for a joint Tor and Mullvad Browser release
+  - **⚠️ WARNING**: You may need to manually update the `firefox/config` file's `browser_build` field if `mullvad-browser.git` has not yet been tagged (e.g. if security backports have not yet been merged and tagged)
+  ```bash
+  ./tools/relprep.py --mullvad-browser --date ${RELEASE_DATE} ${MULLVAD_BROWSER_VERSION}
+  ```
+- [ ] Review build configuration changes:
+  - [ ] `rbm.conf`
+    - [ ] `var/torbrowser_version`: updated to next browser version
+    - [ ] `var/torbrowser_build`: updated to `${MULLVAD_BROWSER_BUILD_N}`
+    - [ ] `var/browser_release_date`: updated to build date. For the build to be reproducible, the date should be in the past when building.
+      - **⚠️ WARNING**: If we have updated `var/torbrowser_build` without updating the `firefox` tag, then we can leave this unchanged to avoid forcing a firefox re-build (e.g. when bumping `var/torbrowser_build` to build2, build3, etc due to non-firefox related build issues)
+    - [ ] `var/torbrowser_incremental_from`: updated to previous Desktop version
+      - **NOTE**: We try to build incrementals for the previous 3 desktop versions
+      - **⚠️ WARNING**: Really *actually* make sure this is the previous Desktop version or else the `make mullvadbrowser-incrementals-*` step will fail
+  - [ ] `projects/firefox/config`
+    - [ ] `browser_build`: updated to match `mullvad-browser` tag
+    - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] ***(Optional)*** `projects/translation/config`:
+    - [ ] `steps/base-browser/git_hash`: updated with `HEAD` commit of project's `base-browser` branch
+    - [ ] `steps/mullvad-browser/git_hash`: updated with `HEAD` commit of project's `mullvad-browser` branch
+  - [ ] ***(Optional)*** `projects/browser/config`:
+    - [ ] ***(Optional)*** NoScript: https://addons.mozilla.org/en-US/firefox/addon/noscript
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+    - [ ] ***(Optional)*** uBlock-origin: https://addons.mozilla.org/en-US/firefox/addon/ublock-origin
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+    - [ ] ***(Optional)*** Mullvad Browser extension: https://github.com/mullvad/browser-extension/releases
+      - [ ] `URL` updated
+      - [ ] `sha256sum` updated
+  - [ ] `ChangeLog-MB.txt`: ensure correctness
+    - Browser name correct
+    - Release date correct
+    - No Android updates
+    - All issues added under correct platform
+    - ESR updates correct
+    - Component updates correct
+- [ ] Open MR with above changes, using the template for release preparations
+  - **NOTE**: target the `maint-14.0` branch
+- [ ] Merge
+- [ ] Sign+Tag
+  - **NOTE** this must be done by one of:
+    - boklm
+    - dan
+    - ma1
+    - morgan
+    - pierov
+  - Run:
+    ```bash
+    make mullvadbrowser-signtag-release
+    ```
+- [ ] Push tag to `upstream`
+- [ ] Build the tag:
+  - Run:
+    ```bash
+    make mullvadbrowser-release && make mullvadbrowser-incrementals-release
+    ```
+    - [ ] Tor Project build machine
+    - [ ] Local developer machine
+  - [ ] Submit build request to Mullvad infrastructure:
+    - **NOTE** this requires a github authentication token
+    - Run:
+      ```bash
+      make mullvadbrowser-kick-devmole-build
+      ```
+
+</details>
+
+<details>
+  <summary>Signing</summary>
+
+### release signing
+- [ ] Assign this issue to the signer, one of:
+  - boklm
+  - ma1
+  - morgan
+  - pierov
+- [ ] Ensure all builders have matching builds
+- [ ] On `${STAGING_SERVER}`, ensure updated:
+  - **NOTE** Having a local git branch with `maint-14.0` as the upstream branch with these values saved means you only need to periodically `git pull --rebase` and update the `set-config.tbb-version` file
+  - [ ] `tor-browser-build` is on the right commit: `git tag -v mb-${MULLVAD_BROWSER_VERSION}-${MULLVAD_BROWSER_BUILD_N} && git checkout mb-${MULLVAD_BROWSER_VERSION}-${MULLVAD_BROWSER_BUILD_N}`
+  - [ ] `tor-browser-build/tools/signing/set-config.hosts`
+    - `ssh_host_builder`: ssh hostname of machine with unsigned builds
+    - `ssh_host_linux_signer`: ssh hostname of linux signing machine
+    - `builder_tor_browser_build_dir`: path on `ssh_host_builder` to root of builder's `tor-browser-build` clone containing unsigned builds
+  - [ ] `tor-browser-build/tools/signing/set-config.rcodesign-appstoreconnect`
+    - `appstoreconnect_api_key_path`: path to json file containing appstoreconnect api key infos
+  - [ ] `set-config.update-responses`
+    - `update_responses_repository_dir`: directory where you cloned `git@gitlab.torproject.org:tpo/applications/mullvad-browser-update-responses.git`
+  - [ ] `tor-browser-build/tools/signing/set-config.tbb-version`
+    - `tbb_version`: mullvad browser version string, same as `var/torbrowser_version` in `rbm.conf` (examples: `11.5a12`, `11.0.13`)
+    - `tbb_version_build`: the tor-browser-build build number (if `var/torbrowser_build` in `rbm.conf` is `buildN` then this value is `N`)
+    - `tbb_version_type`: either `alpha` for alpha releases or `release` for stable releases
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, ensure tor daemon is running with SOCKS5 proxy on the default port 9050
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, run do-all-signing script:
+  - Run:
+    ```bash
+    cd tor-browser-build/tools/signing/ && ./do-all-signing.mullvadbrowser
+    ```
+  - **NOTE**: on successful execution, the signed binaries and mars should have been copied to `staticiforme` and update responses pushed
+
+</details>
+
+<details>
+  <summary>Publishing</summary>
+
+### website
+- [ ] On `staticiforme.torproject.org`, remove old release and publish new:
+  - [ ] `/srv/dist-master.torproject.org/htdocs/mullvadbrowser`
+  - Run:
+    ```bash
+    static-update-component dist.torproject.org
+    ```
+
+### mullvad-browser (GitHub): https://github.com/mullvad/mullvad-browser/
+- [ ] Assign this issue to someone with mullvad commit access, one of:
+    - boklm
+    - ma1
+    - morgan
+    - pierov
+- [ ] Sign+Tag additionally the `mullvad-browser.git` `firefox` commit used in build:
+  - **Tag**: `${MULLVAD_BROWSER_VERSION}`
+    - **example**: `12.5a7`
+  - **Message**: `${ESR_VERSION}esr-based ${MULLVAD_BROWSER_VERSION}`
+    - **example**: `102.12.0esr-based 12.5a7`
+- [ ] Push this release's associated `mullvad-browser.git` branch to github
+- [ ] Push this release's associated tags to github:
+  - [ ] Firefox ESR tag
+    - **example**: `FIREFOX_102_12_0esr_BUILD1`
+  - [ ] `base-browser` tag
+    - **example**: `base-browser-102.12.0esr-12.0-1-build1`
+  - [ ] `mullvad-browser` build tag
+    - **example**: `mullvad-browser-102.12.0esr-12.0-1-build1`
+  - [ ] `mullvad-browser` release tag
+    - **example**: `12.0.11`
+
+</details>
+
+<details>
+  <summary>Communications</summary>
+
+### Mullvad
+- [ ] Email Mullvad with release information:
+  - **Recipients**
+    - Mullvad support alias: support@mullvadvpn.net
+    - Rui Hildt: rui@mullvad.net
+    ```
+    support@mullvadvpn.net, rui@mullvad.net
+    ```
+  - **Subject**
+    ```
+    New build: Mullvad Browser ${MULLVAD_BROWSER_VERSION} (signed)
+    ```
+  - **Body**
+    ```
+    Hello,
+
+    Branch+Tags have been pushed to Mullvad's GitHub repo.
+
+    - signed builds: https://dist.torproject.org/mullvadbrowser/${MULLVAD_BROWSER_VERSION}
+    - update_response hashes: ${MULLVAD_UPDATE_RESPONSES_HASH}*
+
+    * https://gitlab.torproject.org/tpo/applications/mullvad-browser-update-responses
+
+    changelog:
+    # paste changelog as quote here
+    ...
+    ```
+
+### packagers
+- [ ] **(Once Packages are pushed to GitHub)**
+  - **Recipients**
+    - flathub package maintainer: proletarius101@protonmail.com
+    - arch package maintainer: bootctl@gmail.com
+    - nixOS package maintainer: dev@felschr.com
+    ```
+    proletarius101@protonmail.com, bootctl@gmail.com, dev@felschr.com,
+    ```
+  - **Subject**
+    ```
+    Mullvad Browser ${MULLVAD_BROWSER_VERSION} released
+    ```
+  - **Body**
+    ```
+    Hello!
+
+    Mullvad-Browser packages are available, so you should update your respective downstream packages.
+
+    The latest release builds can be found here:
+
+    - https://github.com/mullvad/mullvad-browser/releases?q=prerelease%3Afalse
+    ```
+
+### merge requests
+- [ ] **(Once Packages are pushed to GitHub)**
+  - [ ] homebrew: https://github.com/Homebrew/homebrew-cask/blob/master/Casks/m/mullvad-browser.rb
+    - **NOTE**: a bot seems to pick this up without needing our intervention these days
+    - **NOTE**: should just need to update `version` and `sha256` to latest
+
+</details>
+
+/label ~"Apps::Type::ReleasePreparation"
+/label ~"Sponsor 131"

.gitlab/issue_templates/Release Prep - Tor Browser Alpha.md

+# Release Prep Tor Browser Alpha
+
+- **NOTE** It is assumed the `tor-browser` alpha rebase and security backport tasks have been completed
+- **NOTE** This can/is often done in conjunction with the equivalent Mullvad Browser release prep issue
+
+<details>
+  <summary>Explanation of variables</summary>
+
+- `${BUILD_SERVER}`: the server the main builder is using to build a browser release
+- `${BUILDER}`: whomever is building the release on the ${BUILD_SERVER}
+  - **example**: `pierov`
+- `${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 browser tags, labels, etc
+  - **example**: `91.6.0`
+- `${TOR_BROWSER_MAJOR}`: the Tor Browser major version
+  - **example**: `11`
+- `${TOR_BROWSER_MINOR}`: the Tor Browser minor version
+  - **example**: either `0` or `5`; Alpha's is always `(Stable + 5) % 10`
+- `${TOR_BROWSER_VERSION}`: the Tor Browser version in the format
+  - **example**: `12.5a3`, `12.0.3`
+- `${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`
+- `${TOR_BROWSER_BUILD_N}`: the tor-browser build revision for a given Tor Browser release; used in tagging git commits
+  - **example**: `build2`
+  - **⚠️ WARNING**: 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 at `build1` (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.
+- `${TOR_BROWSER_VERSION}`: the published Tor Browser version
+    - **example**: `11.5a6`, `11.0.7`
+- `${TBB_BUILD_TAG}`: the `tor-browser-build` build tag used to build a given Tor Browser version
+  - **example**: `tbb-12.5a7-build1`
+- `${RELEASE_DATE}`: the intended release date of this browser release; for ESR schedule-driven releases, this should match the upstream Firefox release date
+  - **example**: `2024-10-29`
+
+</details>
+
+<details>
+  <summary>Build Configuration</summary>
+
+### tor-browser: https://gitlab.torproject.org/tpo/applications/tor-browser.git
+
+- [ ] Tag `tor-browser` in tor-browser.git
+  - **example**: `tor-browser-128.4.0esr-14.5-1-build1`
+  - Run:
+    ```bash
+    ./tools/browser/sign-tag.torbrowser alpha ${BUILD_N}
+    ```
+
+### tor-browser-build: https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
+Tor Browser Alpha (and Nightly) are on the `main` branch
+
+- [ ] Changelog bookkeeping:
+  - Ensure all commits to `tor-browser` and `tor-browser-build` for this release have an associated issue linked to this release preparation issue
+  - Ensure each issue has a platform (~Windows, ~MacOS, ~Linux, ~Android, ~Desktop, ~"All Platforms") and potentially ~"Build System" labels
+- [ ] Create a release preparation branch from the `main` branch
+- [ ] Run release preparation script:
+  - **NOTE**: You can omit the `--tor-browser` argument if this is for a jointt Tor and Mullvad Browser release
+  - **⚠️ WARNING**: You may need to manually update the `firefox/config` and `geckoview/config` files' `browser_build` field if `tor-browser.git` has not yet been tagged (e.g. if security backports have not yet been merged and tagged)
+  ```bash
+  ./tools/relprep.py --tor-browser --date ${RELEASE_DATE} ${TOR_BROWSER_VERSION}
+  ```
+- [ ] Review build configuration changes:
+  - [ ] `rbm.conf`
+    - [ ] `var/torbrowser_version`: updated to next browser version
+    - [ ] `var/torbrowser_build`: updated to `${TOR_BROWSER_BUILD_N}`
+    - [ ] `var/browser_release_date`: updated to build date. For the build to be reproducible, the date should be in the past when building.
+      - **⚠️ WARNING**: If we have updated `var/torbrowser_build` without updating the `firefox` or `geckoview` tags, then we can leave this unchanged to avoid forcing a firefox re-build (e.g. when bumping `var/torbrwoser_build` to build2, build3, etc due to non-firefox related build issues)
+    - [ ] `var/browser_platforms`: updated to enable the platforms included in this release
+    - [ ] ***(Desktop Only)*** `var/torbrowser_incremental_from`: updated to previous Desktop version
+      - **NOTE**: We try to build incrementals for the previous 3 desktop versions
+      - **⚠️ WARNING**: Really *actually* make sure this is the previous Desktop version or else the `make torbrowser-incrementals-*` step will fail
+  - [ ] `projects/firefox/config`
+    - [ ] `browser_build`: updated to match `tor-browser` tag
+    - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] `projects/geckoview/config`
+    - [ ] `browser_build`: updated to match `tor-browser` tag
+    - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] ***(Optional)*** `projects/translation/config`:
+    - [ ] `steps/base-browser/git_hash`: updated with `HEAD` commit of project's `base-browser` branch
+    - [ ] `steps/tor-browser/git_hash`: updated with `HEAD` commit of project's `tor-browser` branch
+    - [ ] `steps/fenix/git_hash`: updated with `HEAD` commit of project's `fenix-torbrowserstringsxml` branch
+  - [ ] ***(Optional)*** `projects/browser/config`:
+    - [ ] ***(Optional)*** NoScript: https://addons.mozilla.org/en-US/firefox/addon/noscript
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+  - [ ] ***(Optional)*** `projects/openssl/config`: https://www.openssl.org/source/
+    - **NOTE**: Only if new LTS version (3.0.X currrently) available
+    - [ ] `version`: updated to next LTS version
+    - [ ] `input_files/sha256sum`: updated to sha256 sum of source tarball
+  - [ ] **(Optional)** `projects/zlib/config`: https://github.com/madler/zlib/releases
+    - **NOTE**: Only if new tag available
+    - [ ] `version`: updated to next release tag
+  - [ ] **(Optional)** `projects/zstd/config`: https://github.com/facebook/zstd/releases
+    - **NOTE**: Only if new tag available; Android-only for now
+    - [ ] `version`: updated to next release tag
+    - [ ] `git_hash`: updated to the commit corresponding to the tag (we don't check signatures for Zstandard)
+  - [ ] **(Optional)** `projects/tor/config` https://gitlab.torproject.org/tpo/core/tor/-/tags
+    - [ ] `version`: updated to latest `-alpha` tag or release tag if newer (ping **dgoulet** or **ahf** if unsure)
+  - [ ] **(Optional)** `projects/go/config` https://go.dev/dl
+    - **NOTE**: In general, Tor Browser Alpha uses the latest Stable major series Go version, but there are sometimes exceptions. Check with the anti-censorship team before doing a major version update in case there is incompatibilities.
+    - [ ] `version`: updated go version
+    - [ ] `input_files/sha256sum` for `go`: update sha256sum of archive (sha256 sums are displayed on the go download page)
+  - [ ] **(Optional)** `projects/manual/config`
+    - [ ] `version`: updated to latest pipeline id
+    - [ ] `input_files/shasum` for `manual`: updated to manual hash
+    - [ ] Upload the downloaded `manual_${PIPELINEID}.zip` file to `tb-build-02.torproject.org`
+    - [ ] Deploy to `tb-builder`'s `public_html` directory:
+      - Run:
+        ```bash
+        sudo -u tb-builder cp manual_${PIPELINEID}.zip ~tb-builder/public_html/.
+        ```
+      - `sudo` documentation for TPO machines: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/doc/accounts#changingresetting-your-passwords
+  - [ ] `ChangeLog-TBB.txt`: ensure correctness
+    - Browser name correct
+    - Release date correct
+    - No Android updates on a desktop-only release and vice-versa
+    - All issues added under correct platform
+    - ESR updates correct
+    - Component updates correct
+- [ ] Open MR with above changes, using the template for release preparations
+  - **NOTE**: target the `main` branch
+- [ ] Merge
+- [ ] Sign+Tag
+  - **NOTE** this must be done by one of:
+    - boklm
+    - dan
+    - ma1
+    - morgan
+    - pierov
+  - Run:
+    ```bash
+    make torbrowser-signtag-alpha
+    ```
+- [ ] Push tag to `upstream`
+- [ ] Build the tag:
+  - Run:
+    ```bash
+    make torbrowser
+    ```
+    - [ ] Tor Project build machine
+    - [ ] Local developer machine
+  - [ ] Submit build request to Mullvad infrastructure:
+    - **NOTE** this requires a github authentication token
+    - Run:
+      ```bash
+      make torbrowser-kick-devmole-build
+      ```
+
+</details>
+
+<details>
+  <summary>Website</summary>
+
+  ### downloads: https://gitlab.torproject.org/tpo/web/tpo.git
+  - [ ] `databags/versions.ini`: Update the downloads versions
+      - `torbrowser-stable/version`: catch-all for latest stable version
+      - `torbrowser-alpha/version`: catch-all for latest alpha version
+      - `torbrowser-*-stable/version`: platform-specific stable versions
+      - `torbrowser-*-alpha/version`: platform-specific alpha versions
+  - [ ] Push to origin as new branch and create MR
+  - [ ] Review
+  - [ ] Merge
+    - **⚠️ WARNING**: Do not deploy yet!
+
+  ### blog: https://gitlab.torproject.org/tpo/web/blog.git
+  - [ ] Generate release blog post
+    - Run:
+    ```bash
+    ./tools/signing/create-blog-post.torbrowser
+    ```
+    - **NOTE** this script creates the new blog post from a template (edit `./tools/signing/set-config.blog` to set you local blog directory)
+    - [ ] **(Optional)** Note any ESR update
+    - [ ] **(Optional)** Thank any users which have contributed patches
+    - [ ] **(Optional)** Draft any additional sections for new features which need testing, known issues, etc
+  - [ ] Push to origin as new branch and open MR
+  - [ ] Review
+  - [ ] Merge
+    - **⚠️ WARNING**: Do not deploy yet!
+
+</details>
+
+<details>
+  <summary>Signing</summary>
+
+### release signing
+- [ ] Assign this issue to the signer, one of:
+  - boklm
+  - ma1
+  - morgan
+  - pierov
+- [ ] Ensure all builders have matching builds
+- [ ] On `${STAGING_SERVER}`, ensure updated:
+  - **NOTE** Having a local git branch with `main` as the upstream branch with these values saved means you only need to periodically `git pull --rebase`
+  - [ ] `tor-browser-build` is on the right commit: `git tag -v tbb-${TOR_BROWSER_VERSION}-${TOR_BROWSER_BUILD_N} && git checkout tbb-${TOR_BROWSER_VERSION}-${TOR_BROWSER_BUILD_N}`
+  - [ ] `tor-browser-build/tools/signing/set-config.hosts`
+    - `ssh_host_builder`: ssh hostname of machine with unsigned builds
+    - `ssh_host_linux_signer`: ssh hostname of linux signing machine
+    - `builder_tor_browser_build_dir`: path on `ssh_host_builder` to root of builder's `tor-browser-build` clone containing unsigned builds
+  - [ ] `tor-browser-build/tools/signing/set-config.rcodesign-appstoreconnect`
+    - `appstoreconnect_api_key_path`: path to json file containing appstoreconnect api key infos
+  - [ ] `set-config.update-responses`
+    - `update_responses_repository_dir`: directory where you cloned `git@gitlab.torproject.org:tpo/applications/tor-browser-update-responses.git`
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, ensure tor daemon is running with SOCKS5 proxy on the default port 9050
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, run do-all-signing script:
+  - Run:
+    ```bash
+    cd tor-browser-build/tools/signing/ && ./do-all-signing.torbrowser
+    ```
+  - **NOTE**: on successful execution, the signed binaries and mars should have been copied to `staticiforme` and update responses pushed
+
+</details>
+
+<details>
+  <summary>Signature verification</summary>
+
+  <details>
+    <summary>Check whether the .exe files got properly signed and timestamped</summary>
+
+```bash
+# Point OSSLSIGNCODE to your osslsigncode binary
+pushd tor-browser-build/torbrowser/${channel}/signed/$TORBROWSER_VERSION
+OSSLSIGNCODE=/path/to/osslsigncode
+../../../../tools/authenticode_check.sh
+popd
+```
+
+  </details>
+  <details>
+    <summary>Check whether the MAR files got properly signed</summary>
+
+```bash
+# Point NSS_DB_DIR to your nssdb dir containing the mar signing certificate
+# (check tools/marsigning_check.sh source code for details)
+# Point SIGNMAR to your signmar binary
+# Point LD_LIBRARY_PATH to your mar-tools directory
+pushd tor-browser-build/torbrowser/${channel}/signed/$TORBROWSER_VERSION
+NSSDB=/path/to/nssdb
+SIGNMAR=/path/to/mar-tools/signmar
+LD_LIBRARY_PATH=/path/to/mar-tools/
+../../../../tools/marsigning_check.sh
+popd
+```
+
+  </details>
+</details>
+
+<details>
+  <summary>Publishing</summary>
+
+### website
+- [ ] On `staticiforme.torproject.org`, static update components:
+  - Run:
+    ```bash
+    static-update-component cdn.torproject.org && static-update-component dist.torproject.org
+    ```
+- [ ] Deploy `tor-website` MR
+- [ ] Deploy `tor-blog` MR
+- [ ] On `staticiforme.torproject.org`, enable update responses:
+  - Run:
+    ```bash
+    sudo -u tb-release ./deploy_update_responses-alpha.sh
+    ```
+- [ ] On `staticiforme.torproject.org`, remove old release:
+  - **NOTE**: Skip this step if we need to hold on to older versions for some reason (for example, this is an Andoid or Desktop-only release, or if we need to hold back installers in favor of build-to-build updates if there are signing issues, etc)
+  - [ ] `/srv/cdn-master.torproject.org/htdocs/aus1/torbrowser`
+  - [ ] `/srv/dist-master.torproject.org/htdocs/torbrowser`
+  - Run:
+    ```bash
+    static-update-component cdn.torproject.org && static-update-component dist.torproject.org
+    ```
+
+### Google Play: https://play.google.com/apps/publish
+- [ ] Publish APKs to Google Play:
+  - Select `Tor Browser (Alpha)` app
+  - Navigate to `Release > Production` and click `Create new release` button:
+    - Upload the `tor-browser-android-*.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
+  - 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
+
+</details>
+
+<details>
+  <summary>Communications</summary>
+
+### tor-announce mailing list
+- [ ] Email tor-announce mailing list
+  - **Recipients**
+    ```
+    tor-announce@lists.torproject.org
+    ```
+  - **Subject**
+    ```
+    New Release: Tor Browser ${TOR_BROWSER_VERSION} (Android, Windows, macOS, Linux)
+    ```
+  - **Body**
+    ```
+    Hi everyone,
+
+    Tor Browser ${TOR_BROWSER_VERSION} has now been published for all platforms. For details please see our blog post:
+    - ${BLOG_POST_URL}
+
+    Changelog:
+    # paste changelog as quote here
+    ```
+
+### packagers
+- [ ] ***(Optional, only around build/packaging changes)*** Email packagers:
+  - **Recipients**
+    - Tails dev mailing list: tails-dev@boum.org
+    - Guardian Project: nathan@guardianproject.info
+    - FreeBSD port: freebsd@sysctl.cz <!-- Gitlab user maxfx -->
+    - OpenBSD port: caspar@schutijser.com <!-- Gitlab user cschutijser -->
+    - torbrowser-launcher: mail@asciiwolf.com <!-- Gitlab user asciiwolf -->
+    - Anti-Censorship: meskio@torproject.org <!-- Gitlab user meskio -->
+    ```
+    tails-dev@boum.org, nathan@guardianproject.info, freebsd@sysctl.cz, caspar@schutijser.com, mail@asciiwolf.com, meskio@torproject.org,
+    ```
+  - **Subject**
+    ```
+    New Release: Tor Browser ${TOR_BROWSER_VERSION} (Android, Windows, macOS, Linux)
+    ```
+  - [ ] Note any changes which may affect packaging/downstream integration
+
+### downstream projects
+- [ ] ***(Optional, only after internal API-breaking changes)*** Email downstream project maintainers:
+  - **Recipients**
+    - selenium-tor: matzfan@tempr.email <!-- Forum user Noino -->
+    ```
+    matzfan@tempr.email
+    ```
+  - **Subject**
+    ```
+    Breaking Changes in Tor Browser ${TOR_BROWSER_VERSION}
+    ```
+  - [ ] Note any internal API changes which may affect browser automation
+
+### upstream services
+- [ ] ***(Optional, after ESR migration)*** Email external partners:
+  - [ ] 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
+  - [ ]  Startpage: admin@startpage.com
+    - **NOTE**: Startpage also needs the updated user-agent string for better experience on their onion service sites.
+
+</details>
+
+/label ~"Apps::Type::ReleasePreparation"

.gitlab/issue_templates/Release Prep - Tor Browser Legacy.md

+# Release Prep Tor Browser Legacy
+
+- **NOTE** It is assumed the `tor-browser` release rebase and security backport tasks have been completed
+
+<details>
+  <summary>Explanation of variables</summary>
+
+- `${BUILD_SERVER}`: the server the main builder is using to build a browser release
+- `${BUILDER}`: whomever is building the release on the ${BUILD_SERVER}
+  - **example**: `pierov`
+- `${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 browser tags, labels, etc
+  - **example**: `91.6.0`
+- `${TOR_BROWSER_MAJOR}`: the Tor Browser major version
+  - **example**: `11`
+- `${TOR_BROWSER_MINOR}`: the Tor Browser minor version
+  - **example**: either `0` or `5`; Alpha's is always `(Stable + 5) % 10`
+- `${TOR_BROWSER_VERSION}`: the Tor Browser version in the format
+  - **example**: `12.5a3`, `12.0.3`
+- `${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`
+- `${TOR_BROWSER_BUILD_N}`: the tor-browser build revision for a given Tor Browser release; used in tagging git commits
+  - **example**: `build2`
+  - **⚠️ WARNING**: 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 at `build1` (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.
+- `${TOR_BROWSER_VERSION}`: the published Tor Browser version
+    - **example**: `11.5a6`, `11.0.7`
+- `${TBB_BUILD_TAG}`: the `tor-browser-build` build tag used to build a given Tor Browser version
+  - **example**: `tbb-12.5a7-build1`
+- `${RELEASE_DATE}`: the intended release date of this browser release; for ESR schedule-driven releases, this should match the upstream Firefox release date
+  - **example**: `2024-10-29`
+
+</details>
+
+<details>
+  <summary>Build Configuration</summary>
+
+### tor-browser: https://gitlab.torproject.org/tpo/applications/tor-browser.git
+
+- [ ] Tag `tor-browser` in tor-browser.git
+  - **example**: `tor-browser-115.17.0esr-13.5-1-build1`
+  - Run:
+    ```bash
+    ./tools/browser/sign-tag.torbrowser legacy ${BUILD_N}
+    ```
+
+### tor-browser-build: https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
+Tor Browser Legacy is on the `maint-13.5` branch
+
+- [ ] Changelog bookkeeping:
+  - Ensure all commits to `tor-browser` and `tor-browser-build` for this release have an associated issue linked to this release preparation issue
+  - Ensure each issue has a platform (~Windows, ~MacOS, ~Desktop, ~"All Platforms") and potentially ~"Build System" labels
+- [ ] Create a release preparation branch from the `maint-13.5` branch
+- [ ] Run release preparation script:
+  - **⚠️ WARNING**: You may need to manually update the `firefox/config` file's `browser_build` field if `tor-browser.git` has not yet been tagged (e.g. if security backports have not yet been merged and tagged)
+  ```bash
+  ./tools/relprep.py --tor-browser --date ${RELEASE_DATE} ${TOR_BROWSER_VERSION}
+  ```
+- [ ] Review build configuration changes:
+  - [ ] `rbm.conf`
+    - [ ] `var/torbrowser_version`: updated to next browser version
+    - [ ] `var/torbrowser_build`: updated to `${TOR_BROWSER_BUILD_N}`
+    - [ ] `var/browser_release_date`: updated to build date. For the build to be reproducible, the date should be in the past when building.
+      - **⚠️ WARNING**: If we have updated `var/torbrowser_build` without updating the `firefox`, then we can leave this unchanged to avoid forcing a firefox re-build (e.g. when bumping `var/torbrwoser_build` to build2, build3, etc due to non-firefox related build issues)
+    - [ ] ***(Desktop Only)*** `var/torbrowser_incremental_from`: updated to previous Desktop version
+      - **NOTE**: We try to build incrementals for the previous 3 desktop versions
+      - **⚠️ WARNING**: Really *actually* make sure this is the previous Desktop version or else the `make torbrowser-incrementals-*` step will fail
+  - [ ] `projects/firefox/config`
+    - [ ] `browser_build`: updated to match `tor-browser` tag
+    - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] ***(Optional)*** `projects/translation/config`:
+    - [ ] `steps/base-browser/git_hash`: updated with `HEAD` commit of project's `base-browser` branch
+    - [ ] `steps/tor-browser/git_hash`: updated with `HEAD` commit of project's `tor-browser` branch
+  - [ ] ***(Optional)*** `projects/browser/config`:
+    - [ ] ***(Optional)*** NoScript: https://addons.mozilla.org/en-US/firefox/addon/noscript
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+  - [ ] ***(Optional)*** `projects/openssl/config`: https://www.openssl.org/source/
+    - **NOTE**: Only if new LTS version (3.0.X currrently) available
+    - [ ] `version`: updated to next LTS version
+    - [ ] `input_files/sha256sum`: updated to sha256 sum of source tarball
+  - [ ] **(Optional)** `projects/zlib/config`: https://github.com/madler/zlib/releases
+    - **NOTE**: Only if new tag available
+    - [ ] `version`: updated to next release tag
+  - [ ] **(Optional)** `projects/zstd/config`: https://github.com/facebook/zstd/releases
+    - **NOTE**: Only if new tag available
+    - [ ] `version`: updated to next release tag
+    - [ ] `git_hash`: updated to the commit corresponding to the tag (we don't check signatures for Zstandard)
+  - [ ] **(Optional)** `projects/tor/config` https://gitlab.torproject.org/tpo/core/tor/-/tags
+    - [ ] `version`: updated to latest non `-alpha` tag or release tag if newer (ping **dgoulet** or **ahf** if unsure)
+  - [ ] **(Optional)** `projects/go/config` https://go.dev/dl
+    - [ ] `go_1_22`: updated to latest 1.22 version
+    - [ ] `input_files/sha256sum` for `go`: update sha256sum of archive (sha256 sums are displayed on the go download page)
+  - [ ] **(Optional)** `projects/manual/config`
+    - [ ] `version`: updated to latest pipeline id
+    - [ ] `input_files/shasum` for `manual`: updated to manual hash
+    - [ ] Upload the downloaded `manual_${PIPELINEID}.zip` file to `tb-build-02.torproject.org`
+    - [ ] Deploy to `tb-builder`'s `public_html` directory:
+      - Run:
+        ```bash
+        sudo -u tb-builder cp manual_${PIPELINEID}.zip ~tb-builder/public_html/.
+        ```
+      - `sudo` documentation for TPO machines: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/doc/accounts#changingresetting-your-passwords
+  - [ ] `ChangeLog-TBB.txt`: ensure correctness
+    - Browser name correct
+    - Release date correct
+    - No Android updates
+    - All issues added under correct platform
+    - ESR updates correct
+    - Component updates correct
+- [ ] Open MR with above changes, using the template for release preparations
+  - **NOTE**: target the `maint-13.5` branch
+- [ ] Merge
+- [ ] Sign+Tag
+  - **NOTE** this must be done by one of:
+    - boklm
+    - dan
+    - ma1
+    - morgan
+    - pierov
+  - Run:
+    ```bash
+    make torbrowser-signtag-release
+    ```
+- [ ] Push tag to `upstream`
+- [ ] Build the tag:
+  - Run:
+    ```bash
+    make torbrowser-release && make torbrowser-incrementals-release
+    ```
+    - [ ] Tor Project build machine
+    - [ ] Local developer machine
+  - [ ] Submit build request to Mullvad infrastructure:
+    - **NOTE** this requires a github authentication token
+    - Run:
+      ```bash
+      make torbrowser-kick-devmole-build
+      ```
+
+</details>
+
+<details>
+  <summary>Website</summary>
+
+  ### blog: https://gitlab.torproject.org/tpo/web/blog.git
+  - [ ] Generate release blog post
+    - Run:
+    ```bash
+    ./tools/signing/create-blog-post.torbrowser
+    ```
+    - **NOTE** this script creates the new blog post from a template (edit `./tools/signing/set-config.blog` to set you local blog directory)
+    - [ ] **(Optional)** Note any ESR update
+    - [ ] **(Optional)** Thank any users which have contributed patches
+    - [ ] **(Optional)** Draft any additional sections for new features which need testing, known issues, etc
+  - [ ] Push to origin as new branch and open MR
+  - [ ] Review
+  - [ ] Merge
+    - **⚠️ WARNING**: Do not deploy yet!
+
+</details>
+
+<details>
+  <summary>Signing</summary>
+
+### release signing
+- [ ] Assign this issue to the signer, one of:
+  - boklm
+  - ma1
+  - morgan
+  - pierov
+- [ ] Ensure all builders have matching builds
+- [ ] On `${STAGING_SERVER}`, ensure updated:
+  - **NOTE** Having a local git branch with `maint-13.5` as the upstream branch with these values saved means you only need to periodically `git pull --rebase` and update the `set-config.tbb-version` file
+  - [ ] `tor-browser-build` is on the right commit: `git tag -v tbb-${TOR_BROWSER_VERSION}-${TOR_BROWSER_BUILD_N} && git checkout tbb-${TOR_BROWSER_VERSION}-${TOR_BROWSER_BUILD_N}`
+  - [ ] `tor-browser-build/tools/signing/set-config.hosts`
+    - `ssh_host_builder`: ssh hostname of machine with unsigned builds
+    - `ssh_host_linux_signer`: ssh hostname of linux signing machine
+    - `builder_tor_browser_build_dir`: path on `ssh_host_builder` to root of builder's `tor-browser-build` clone containing unsigned builds
+  - [ ] `tor-browser-build/tools/signing/set-config.rcodesign-appstoreconnect`
+    - `appstoreconnect_api_key_path`: path to json file containing appstoreconnect api key infos
+  - [ ] `tor-browser-build/tools/signing/set-config.tbb-version`
+    - `tbb_version`: tor browser version string, same as `var/torbrowser_version` in `rbm.conf` (examples: `11.5a12`, `11.0.13`)
+    - `tbb_version_build`: the tor-browser-build build number (if `var/torbrowser_build` in `rbm.conf` is `buildN` then this value is `N`)
+    - `tbb_version_type`: either `alpha` for alpha releases or `release` for stable releases
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, ensure tor daemon is running with SOCKS5 proxy on the default port 9050
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, run do-all-signing script:
+  - Run:
+    ```bash
+    cd tor-browser-build/tools/signing/ && ./do-all-signing.torbrowser
+    ```
+  - **NOTE**: on successful execution, the signed binaries and mars should have been copied to `staticiforme` and update responses pushed
+
+</details>
+
+<details>
+  <summary>Signature verification</summary>
+
+  <details>
+    <summary>Check whether the .exe files got properly signed and timestamped</summary>
+
+```bash
+# Point OSSLSIGNCODE to your osslsigncode binary
+pushd tor-browser-build/torbrowser/${channel}/signed/$TORBROWSER_VERSION
+OSSLSIGNCODE=/path/to/osslsigncode
+../../../../tools/authenticode_check.sh
+popd
+```
+
+  </details>
+  <details>
+    <summary>Check whether the MAR files got properly signed</summary>
+
+```bash
+# Point NSSDB to your nssdb containing the mar signing certificate
+# Point SIGNMAR to your signmar binary
+# Point LD_LIBRARY_PATH to your mar-tools directory
+pushd tor-browser-build/torbrowser/${channel}/signed/$TORBROWSER_VERSION
+NSSDB=/path/to/nssdb
+SIGNMAR=/path/to/mar-tools/signmar
+LD_LIBRARY_PATH=/path/to/mar-tools/
+../../../../tools/marsigning_check.sh
+popd
+```
+
+  </details>
+</details>
+
+<details>
+  <summary>Publishing</summary>
+
+### website
+- [ ] On `staticiforme.torproject.org`, static update components:
+  - Run:
+    ```bash
+    static-update-component cdn.torproject.org && static-update-component dist.torproject.org
+    ```
+- [ ] Deploy `tor-blog` MR
+- [ ] On `staticiforme.torproject.org`, remove old release:
+  - **NOTE**: Skip this step if we need to hold on to older versions for some reason (for example, this is an Andoid or Desktop-only release, or if we need to hold back installers in favor of build-to-build updates if there are signing issues, etc)
+  - [ ] `/srv/cdn-master.torproject.org/htdocs/aus1/torbrowser`
+  - [ ] `/srv/dist-master.torproject.org/htdocs/torbrowser`
+  - Run:
+    ```bash
+    static-update-component cdn.torproject.org && static-update-component dist.torproject.org
+    ```
+- [ ] **(Optional)** Generate and deploy new update responses
+  - **NOTE**: This is only required if there will be no corresponding 14.0 release (i.e. this is an emergency legacy-only 13.5 release). Normally, legacy update responses are generated and deployed as part of the 14.0 release.
+  - **⚠️ WARNING**: This is a little bit off the beaten track, ping boklm or morgan if you have any doubts
+  - From the `maint-14.0` branch:
+    - [ ] Update `rbm.conf`
+      - [ ] `var/torbrowser_legacy_version`: update to `${TOR_BROWSER_VERSION}`
+        - **NOTE** this is the browser version for the legacy branch, not the 14.0 branch
+      - [ ] `var/torbrowser_legacy_platform_version`: update to `${ESR_VERSION}`
+        - **NOTE** this is ESR version for the legacy branch, not the 14.0 branch
+    - [ ] Generate update responses:
+      - Run:
+        ```bash
+        make torbrowser-update_responses-release
+        ```
+    - [ ] Commit new update responses to tor-browser-update-responses.git:
+      - Run:
+        ```bash
+        updaterespdir=/path/to/tor-browser-update-responses.git
+        cp torbrowser/release/update-responses/update-responses-release-${TOR_BROWSER_VERSION}.tar "$updaterespdir"
+        cd "$updaterespdir"
+        git pull
+        rm -Rf update_3/release
+        tar -C update_3 update-responses-release-${TOR_BROWSER_VERSION}.tar
+        rm update-responses-release-${TOR_BROWSER_VERSION}.tar
+        git add update_3/release
+        git commit -m "release: new version, ${TOR_BROWSER_VERSION}"
+        git push
+        # print the commit hash and copy past it for the next step
+        git show -s --format=%H
+        ```
+  - On `staticiforme.torproject.org`, deploy new update responses:
+    - [ ] Enable update responses, passing the commit hash as argument (replace $commit):
+      ```bash
+      sudo -u tb-release ./deploy_update_responses-release.sh $commit
+      ```
+
+</details>
+
+<details>
+  <summary>Communications</summary>
+
+### tor-announce mailing list
+- [ ] Email tor-announce mailing list
+  - **Recipients**
+    ```
+    tor-announce@lists.torproject.org
+    ```
+  - **Subject**
+    ```
+    New Release: Tor Browser ${TOR_BROWSER_VERSION} (Windows, macOS)
+    ```
+  - **Body**
+    ```
+    Hi everyone,
+
+    Tor Browser ${TOR_BROWSER_VERSION} has now been published for legacy Windows and macOS platforms. For details please see our blog post:
+    - ${BLOG_POST_URL}
+
+    Changelog:
+    # paste changelog as quote here
+    ```
+
+</details>
+
+/label ~"Apps::Type::ReleasePreparation"

.gitlab/issue_templates/Release Prep - Tor Browser Stable.md

+# Release Prep Tor Browser Stable
+
+- **NOTE** It is assumed the `tor-browser` release rebase and security backport tasks have been completed
+- **NOTE** This can/is often done in conjunction with the equivalent Mullvad Browser release prep issue
+
+<details>
+  <summary>Explanation of variables</summary>
+
+- `${BUILD_SERVER}`: the server the main builder is using to build a browser release
+- `${BUILDER}`: whomever is building the release on the ${BUILD_SERVER}
+  - **example**: `pierov`
+- `${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 browser tags, labels, etc
+  - **example**: `91.6.0`
+- `${TOR_BROWSER_MAJOR}`: the Tor Browser major version
+  - **example**: `11`
+- `${TOR_BROWSER_MINOR}`: the Tor Browser minor version
+  - **example**: either `0` or `5`; Alpha's is always `(Stable + 5) % 10`
+- `${TOR_BROWSER_VERSION}`: the Tor Browser version in the format
+  - **example**: `12.5a3`, `12.0.3`
+- `${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`
+- `${TOR_BROWSER_BUILD_N}`: the tor-browser build revision for a given Tor Browser release; used in tagging git commits
+  - **example**: `build2`
+  - **⚠️ WARNING**: 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 at `build1` (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.
+- `${TOR_BROWSER_VERSION}`: the published Tor Browser version
+    - **example**: `11.5a6`, `11.0.7`
+- `${TBB_BUILD_TAG}`: the `tor-browser-build` build tag used to build a given Tor Browser version
+  - **example**: `tbb-12.5a7-build1`
+- `${RELEASE_DATE}`: the intended release date of this browser release; for ESR schedule-driven releases, this should match the upstream Firefox release date
+  - **example**: `2024-10-29`
+
+</details>
+
+<details>
+  <summary>Build Configuration</summary>
+
+### tor-browser: https://gitlab.torproject.org/tpo/applications/tor-browser.git
+
+- [ ] Tag `tor-browser` in tor-browser.git
+  - **example**: `tor-browser-128.4.0esr-14.0-1-build1`
+  - Run:
+    ```bash
+    ./tools/browser/sign-tag.torbrowser stable ${BUILD_N}
+    ```
+
+### tor-browser-build: https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
+Tor Browser Stable is on the `maint-${TOR_BROWSER_MAJOR}.${TOR_BROWSER_MINOR}` branch
+
+- [ ] Changelog bookkeeping:
+  - Ensure all commits to `tor-browser` and `tor-browser-build` for this release have an associated issue linked to this release preparation issue
+  - Ensure each issue has a platform (~Windows, ~MacOS, ~Linux, ~Android, ~Desktop, ~"All Platforms") and potentially ~"Build System" labels
+- [ ] Create a release preparation branch from the current `maint-XX.Y` branch
+- [ ] Run release preparation script:
+  - **NOTE**: You can omit the `--tor-browser` argument if this is for a joint Tor and Mullvad Browser release
+  - **⚠️ WARNING**: You may need to manually update the `firefox/config` and `geckoview/config` files' `browser_build` field if `tor-browser.git` has not yet been tagged (e.g. if security backports have not yet been merged and tagged)
+  ```bash
+  ./tools/relprep.py --tor-browser --date ${RELEASE_DATE} ${TOR_BROWSER_VERSION}
+  ```
+- [ ] Review build configuration changes:
+  - [ ] `rbm.conf`
+    - [ ] `var/torbrowser_version`: updated to next browser version
+    - [ ] `var/torbrowser_build`: updated to `${TOR_BROWSER_BUILD_N}`
+    - [ ] `var/browser_release_date`: updated to build date. For the build to be reproducible, the date should be in the past when building.
+      - **⚠️ WARNING**: If we have updated `var/torbrowser_build` without updating the `firefox` or `geckoview` tags, then we can leave this unchanged to avoid forcing a firefox re-build (e.g. when bumping `var/torbrwoser_build` to build2, build3, etc due to non-firefox related build issues)
+    - [ ] ***(Desktop Only)*** `var/torbrowser_incremental_from`: updated to previous Desktop version
+      - **NOTE**: We try to build incrementals for the previous 3 desktop versions
+      - **⚠️ WARNING**: Really *actually* make sure this is the previous Desktop version or else the `make torbrowser-incrementals-*` step will fail
+    - [ ] `var/torbrowser_legacy_version`: updated to latest legacy Tor Browser version
+    - [ ] `var/torbrowser_legacy_platform_version`: updated to latest legacy Tor Browser ESR version
+  - [ ] `projects/firefox/config`
+      - [ ] `browser_build`: updated to match `tor-browser` tag
+      - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] `projects/geckoview/config`
+    - [ ] `browser_build`: updated to match `tor-browser` tag
+    - [ ] ***(Optional)*** `var/firefox_platform_version`: updated to latest `${ESR_VERSION}` if rebased
+  - [ ] ***(Optional)*** `projects/translation/config`:
+    - [ ] `steps/base-browser/git_hash`: updated with `HEAD` commit of project's `base-browser` branch
+    - [ ] `steps/tor-browser/git_hash`: updated with `HEAD` commit of project's `tor-browser` branch
+    - [ ] `steps/fenix/git_hash`: updated with `HEAD` commit of project's `fenix-torbrowserstringsxml` branch
+  - [ ] ***(Optional)*** `projects/browser/config`:
+    - [ ] ***(Optional)*** NoScript: https://addons.mozilla.org/en-US/firefox/addon/noscript
+      - [ ] `URL` updated
+        - **⚠️ WARNING**: If preparing the release manually, updating the version number in the url is not sufficient, as each version has a random unique id in the download url
+      - [ ] `sha256sum` updated
+  - [ ] ***(Optional)*** `projects/openssl/config`: https://www.openssl.org/source/
+    - **NOTE**: Only if new LTS version (3.0.X currrently) available
+    - [ ] `version`: updated to next LTS version
+    - [ ] `input_files/sha256sum`: updated to sha256 sum of source tarball
+  - [ ] **(Optional)** `projects/zlib/config`: https://github.com/madler/zlib/releases
+    - **NOTE**: Only if new tag available
+    - [ ] `version`: updated to next release tag
+  - [ ] **(Optional)** `projects/zstd/config`: https://github.com/facebook/zstd/releases
+    - **NOTE**: Only if new tag available; Android-only for now
+    - [ ] `version`: updated to next release tag
+    - [ ] `git_hash`: updated to the commit corresponding to the tag (we don't check signatures for Zstandard)
+  - [ ] **(Optional)** `projects/tor/config` https://gitlab.torproject.org/tpo/core/tor/-/tags
+    - [ ] `version`: updated to latest non `-alpha` tag or release tag if newer (ping **dgoulet** or **ahf** if unsure)
+  - [ ] **(Optional)** `projects/go/config` https://go.dev/dl
+    - **NOTE**: In general, Tor Browser Alpha uses the latest Stable major series Go version, but there are sometimes exceptions. Check with the anti-censorship team before doing a major version update in case there is incompatibilities.
+    - [ ] `version`: updated go version
+    - [ ] `input_files/sha256sum` for `go`: update sha256sum of archive (sha256 sums are displayed on the go download page)
+  - [ ] **(Optional)** `projects/manual/config`
+    - [ ] `version`: updated to latest pipeline id
+    - [ ] `input_files/shasum` for `manual`: updated to manual hash
+    - [ ] Upload the downloaded `manual_${PIPELINEID}.zip` file to `tb-build-02.torproject.org`
+    - [ ] Deploy to `tb-builder`'s `public_html` directory:
+      - Run:
+        ```bash
+        sudo -u tb-builder cp manual_${PIPELINEID}.zip ~tb-builder/public_html/.
+        ```
+      - `sudo` documentation for TPO machines: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/doc/accounts#changingresetting-your-passwords
+  - [ ] `ChangeLog-TBB.txt`: ensure correctness
+    - Browser name correct
+    - Release date correct
+    - No Android updates on a desktop-only release and vice-versa
+    - All issues added under correct platform
+    - ESR updates correct
+    - Component updates correct
+- [ ] Open MR with above changes, using the template for release preparations
+  - **NOTE**: target the `maint-14.0` branch
+- [ ] Merge
+- [ ] Sign+Tag
+  - **NOTE** this must be done by one of:
+    - boklm
+    - dan
+    - ma1
+    - morgan
+    - pierov
+  - Run:
+    ```bash
+    make torbrowser-signtag-release
+    ```
+- [ ] Push tag to `upstream`
+- [ ] Build the tag:
+  - Run:
+    ```bash
+    make torbrowser-release && make torbrowser-incrementals-release
+    ```
+    - Tor Project build machine
+    - Local developer machine
+  - [ ] Submit build request to Mullvad infrastructure:
+    - **NOTE** this requires a github authentication token
+    - Run:
+      ```bash
+      make torbrowser-kick-devmole-build
+      ```
+
+</details>
+
+<details>
+  <summary>Website</summary>
+
+  ### downloads: https://gitlab.torproject.org/tpo/web/tpo.git
+  - [ ] `databags/versions.ini`: Update the downloads versions
+      - `torbrowser-stable/version`: catch-all for latest stable version
+      - `torbrowser-alpha/version`: catch-all for latest alpha version
+      - `torbrowser-*-stable/version`: platform-specific stable versions
+      - `torbrowser-*-alpha/version`: platform-specific alpha versions
+  - [ ] Push to origin as new branch and create MR
+  - [ ] Review
+  - [ ] Merge
+    - **⚠️ WARNING**: Do not deploy yet!
+
+  ### blog: https://gitlab.torproject.org/tpo/web/blog.git
+  - [ ] Generate release blog post
+    - Run:
+    ```bash
+    ./tools/signing/create-blog-post.torbrowser
+    ```
+    - **NOTE** this script creates the new blog post from a template (edit `./tools/signing/set-config.blog` to set you local blog directory)
+    - [ ] **(Optional)** Note any ESR update
+    - [ ] **(Optional)** Thank any users which have contributed patches
+    - [ ] **(Optional)** Draft any additional sections for new features which need testing, known issues, etc
+  - [ ] Push to origin as new branch and open MR
+  - [ ] Review
+  - [ ] Merge
+    - **⚠️ WARNING**: Do not deploy yet!
+
+</details>
+
+<details>
+  <summary>Signing</summary>
+
+### release signing
+- [ ] Assign this issue to the signer, one of:
+  - boklm
+  - ma1
+  - morgan
+  - pierov
+- [ ] Ensure all builders have matching builds
+- [ ] Notify Tails
+  - **Recipients**
+    ```
+    tails-dev@boum.org
+    ```
+  - **Subject**
+    ```
+    Tor Browser ${TOR_BROWSER_VERSION} Ready
+    ```
+  - **Body**
+    ```
+    Hello,
+
+    Tor Browser Stable is ready for Tails. Build artifacts can be found here:
+    - ${BUILD_ARTIFACTS_URL}
+
+    Changelog:
+    # paste changelog as quote here
+    ```
+- [ ] Verify the associated legacy `maint-13.5` release has been signed and deployed
+  - **⚠️ WARNING**: Do not continue if the legacy channel has not been fully signed and published yet; it is needed for update-response generation!
+  - **NOTE** Stable releases without a corresponding legacy release may ignore this
+- [ ] On `${STAGING_SERVER}`, ensure updated:
+  - **NOTE** Having a local git branch with `maint-14.0` as the upstream branch with these values saved means you only need to periodically `git pull --rebase` and update the `set-config.tbb-version` file
+  - [ ] `tor-browser-build` is on the right commit: `git tag -v tbb-${TOR_BROWSER_VERSION}-${TOR_BROWSER_BUILD_N} && git checkout tbb-${TOR_BROWSER_VERSION}-${TOR_BROWSER_BUILD_N}`
+  - [ ] `tor-browser-build/tools/signing/set-config.hosts`
+    - `ssh_host_builder`: ssh hostname of machine with unsigned builds
+    - `ssh_host_linux_signer`: ssh hostname of linux signing machine
+    - `builder_tor_browser_build_dir`: path on `ssh_host_builder` to root of builder's `tor-browser-build` clone containing unsigned builds
+  - [ ] `tor-browser-build/tools/signing/set-config.rcodesign-appstoreconnect`
+    - `appstoreconnect_api_key_path`: path to json file containing appstoreconnect api key infos
+  - [ ] `set-config.update-responses`
+    - `update_responses_repository_dir`: directory where you cloned `git@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 as `var/torbrowser_version` in `rbm.conf` (examples: `11.5a12`, `11.0.13`)
+    - `tbb_version_build`: the tor-browser-build build number (if `var/torbrowser_build` in `rbm.conf` is `buildN` then this value is `N`)
+    - `tbb_version_type`: either `alpha` for alpha releases or `release` for stable releases
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, ensure tor daemon is running with SOCKS5 proxy on the default port 9050
+- [ ] On `${STAGING_SERVER}` in a separate `screen` session, run do-all-signing script:
+  - Run:
+    ```bash
+    cd tor-browser-build/tools/signing/ && ./do-all-signing.torbrowser
+    ```
+  - **NOTE**: on successful execution, the signed binaries and mars should have been copied to `staticiforme` and update responses pushed
+
+</details>
+
+<details>
+  <summary>Signature verification</summary>
+
+  <details>
+    <summary>Check whether the .exe files got properly signed and timestamped</summary>
+
+```bash
+# Point OSSLSIGNCODE to your osslsigncode binary
+pushd tor-browser-build/torbrowser/${channel}/signed/$TORBROWSER_VERSION
+OSSLSIGNCODE=/path/to/osslsigncode
+../../../../tools/authenticode_check.sh
+popd
+```
+
+  </details>
+  <details>
+    <summary>Check whether the MAR files got properly signed</summary>
+
+```bash
+# Point NSSDB to your nssdb containing the mar signing certificate
+# Point SIGNMAR to your signmar binary
+# Point LD_LIBRARY_PATH to your mar-tools directory
+pushd tor-browser-build/torbrowser/${channel}/signed/$TORBROWSER_VERSION
+NSSDB=/path/to/nssdb
+SIGNMAR=/path/to/mar-tools/signmar
+LD_LIBRARY_PATH=/path/to/mar-tools/
+../../../../tools/marsigning_check.sh
+popd
+```
+
+  </details>
+</details>
+
+<details>
+  <summary>Publishing</summary>
+
+### website
+- [ ] On `staticiforme.torproject.org`, static update components:
+  - Run:
+    ```bash
+    static-update-component cdn.torproject.org && static-update-component dist.torproject.org
+    ```
+- [ ] Deploy `tor-website` MR
+- [ ] Deploy `tor-blog` MR
+- [ ] On `staticiforme.torproject.org`, enable update responses:
+  - Run:
+    ```bash
+    sudo -u tb-release ./deploy_update_responses-release.sh
+    ```
+- [ ] On `staticiforme.torproject.org`, remove old release:
+  - **NOTE**: Skip this step if we need to hold on to older versions for some reason (for example, this is an Andoid or Desktop-only release, or if we need to hold back installers in favor of build-to-build updates if there are signing issues, etc)
+  - [ ] `/srv/cdn-master.torproject.org/htdocs/aus1/torbrowser`
+  - [ ] `/srv/dist-master.torproject.org/htdocs/torbrowser`
+  - Run:
+    ```bash
+    static-update-component cdn.torproject.org && static-update-component dist.torproject.org
+    ```
+
+### Google Play: https://play.google.com/apps/publish
+- [ ] Publish APKs to Google Play:
+  - Select `Tor Browser` app
+  - Navigate to `Release > Production` and click `Create new release` button:
+    - Upload the `tor-browser-android-*.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
+  - 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
+
+</details>
+
+<details>
+  <summary>Communications</summary>
+
+### tor-announce mailing list
+- [ ] Email tor-announce mailing list
+  - **Recipients**
+    ```
+    tor-announce@lists.torproject.org
+    ```
+  - **Subject**
+    ```
+    New Release: Tor Browser ${TOR_BROWSER_VERSION} (Android, Windows, macOS, Linux)
+    ```
+  - **Body**
+    ```
+    Hi everyone,
+
+    Tor Browser ${TOR_BROWSER_VERSION} has now been published for all platforms. For details please see our blog post:
+    - ${BLOG_POST_URL}
+
+    Changelog:
+    # paste changelog as quote here
+    ```
+
+### packagers
+- [ ] Email packagers:
+  - **Recipients**
+    - Guardian Project: nathan@guardianproject.info
+    - FreeBSD port: freebsd@sysctl.cz <!-- Gitlab user maxfx -->
+    - OpenBSD port: caspar@schutijser.com <!-- Gitlab user cschutijser -->
+    - torbrowser-launcher: mail@asciiwolf.com <!-- Gitlab user asciiwolf -->
+    - Anti-Censorship: meskio@torproject.org <!-- Gitlab user meskio -->
+    ```
+    nathan@guardianproject.info, freebsd@sysctl.cz, caspar@schutijser.com, mail@asciiwolf.com, meskio@torproject.org,
+    ```
+  - **Subject**
+    ```
+    New Release: Tor Browser ${TOR_BROWSER_VERSION} (Android, Windows, macOS, Linux)
+    ```
+  - **Body**
+    ```
+    Hi everyone,
+
+    Tor Browser ${TOR_BROWSER_VERSION} has now been published for all platforms. For details please see our blog post:
+    - ${BLOG_POST_URL}
+
+    Changelog:
+    # paste changelog as quote here
+    ```
+  - [ ] Note any changes which may affect packaging/downstream integration
+</details>
+
+/label ~"Apps::Type::ReleasePreparation"

.gitlab/issue_templates/Uplift.md

+<!--
+Title:
+    Uplift tor-browser-build#12345: Title of Issue
+
+This is an issue for tracking uplift of a patch-set to an upstream build-dependency (e.g. MinGW, clang, etc)
+
+-->
+
+## Uplift Patchset
+
+### Book-keeping
+
+#### Gitlab Issue(s)
+- tor-browser-build#12345
+
+#### Merge Request(s)
+- tor-browser-build!1234
+
+#### Upstream Project Issue(s):
+
+
+### Notes
+
+<!-- whatever additional info, context, etc that would be helpful for uplifting -->
+
+/label ~"Apps::Type::Uplift"

.gitlab/merge_request_templates/default.md

+## Merge Info
+
+<!-- Bookkeeping information for release management -->
+
+### Issues
+
+#### Resolves
+- tor-browser-build#xxxxx
+- tor-browser#xxxxx
+- mullvad-browser#xxxxx
+
+#### Related
+- tor-browser-build#xxxxx
+- tor-browser#xxxxx
+- mullvad-browser#xxxxx
+
+### Merging
+
+<!-- This block tells the merger where commits need to be merged and future code archaeologists where commits were *supposed* to be merged -->
+
+#### Target Branches
+  - [ ] **`main`**: esr128-14.5
+  - [ ] **`maint-14.0`**: esr128-14.0
+  - [ ] **`maint-13.5`**: esr115-13.5
+
+### Backporting
+
+#### Timeline
+- [ ] **No Backport (preferred)**: patchset for the next major stable
+- [ ] **Immediate**: patchset needed as soon as possible
+- [ ] **Next Minor Stable Release**: patchset that needs to be verified in nightly before backport
+- [ ] **Eventually**: patchset that needs to be verified in alpha before backport
+
+#### (Optional) Justification
+- [ ] **Emergency security update**: patchset fixes CVEs, 0-days, etc
+- [ ] **Censorship event**: patchset enables censorship circumvention
+- [ ] **Critical bug-fix**: patchset fixes a bug in core-functionality
+- [ ] **Consistency**: patchset which would make development easier if it were in both the alpha and release branches; developer tools, build system changes, etc
+- [ ] **Sponsor required**: patchset required for sponsor
+- [ ] **Other**: please explain
+
+### Issue Tracking
+- [ ] Link resolved issues with appropriate [Release Prep issue](https://gitlab.torproject.org/groups/tpo/applications/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=Apps%3A%3AType%3A%3AReleasePreparation&first_page_size=20) for changelog generation
+
+### Uplifting
+- [ ] Patchset is a candidate for uplift to upstream projects (e.g. mingw, clang, etc)
+
+### Review
+
+#### Request Reviewer
+
+- [ ] Request review from an applications developer depending on modified system:
+  - **NOTE**: if the MR modifies multiple areas, please `/cc` all the relevant reviewers (since gitlab only allows 1 reviewer)
+  - **accessibility** : henry
+  - **android** : clairehurst, dan
+  - **build system** : boklm
+  - **extensions** : ma1
+  - **firefox internals (XUL/JS/XPCOM)** : jwilde, ma1
+  - **fonts** : pierov
+  - **frontend (implementation)** : henry
+  - **frontend (review)** : donuts, morgan
+  - **localization** : henry, pierov
+  - **macOS** : clairehurst, dan
+  - **nightly builds** : boklm
+  - **rebases/release-prep** : boklm, dan, ma1, morgan, pierov
+  - **security** : jwilde, ma1
+  - **signing** : boklm, morgan
+  - **updater** : pierov
+  - **windows** : jwilde, morgan
+  - **misc/other** : morgan, pierov
+
+#### Change Description
+
+<!-- Whatever context the reviewer needs to effectively review the patchset; if the patch includes UX updates be sure to include screenshots/video of how any new behaviour -->
+
+#### How Tested
+
+<!-- Description of steps taken to verify the change -->

.gitlab/merge_request_templates/relprep.md

+## Release Prep
+
+### Issues
+
+#### Resolves
+
+- tor-browser-build#xxxxx
+- tor-browser-build#xxxxx
+
+#### Related
+
+- tor-browser-build#xxxxx
+- tor-browser#xxxxx
+- mullvad-browser#xxxxx
+
+### Self-review + reviewer's template
+
+- [ ] `rbm.conf` updates:
+  - [ ] `var/torbrowser_version`
+  - [ ] `var/torbrowser_build`: should be `build1`, unless bumping a previous release preparation
+  - [ ] `var/browser_release_date`: must not be in the future when we start building
+  - [ ] `var/torbrowser_incremental_from` (not needed for Android-only releases)
+  - [ ] `var/torbrowser_legacy_version` (For Tor Browser 14.0.x stable releases only)
+  - [ ] `var/torbrowser_legacy_platform_version` (For Tor Browser 14.0.x stable releases only)
+- [ ] Tag updates:
+  - [ ] [Firefox](https://gitlab.torproject.org/tpo/applications/tor-browser/-/tags)
+  - [ ] Geckoview - should match Firefox
+  - **NOTE**: Tags might be speculative in the release preparation: i.e., they might not exist yet.
+- [ ] Addon updates:
+  - [ ] [NoScript](https://addons.mozilla.org/en-US/firefox/addon/noscript/)
+  - [ ] [uBlock Origin](https://addons.mozilla.org/en-US/firefox/addon/ublock-origin/) (Mullvad Browser only)
+  - [ ] [Mullvad Browser Extension](https://github.com/mullvad/browser-extension/releases) (Mullvad Browser only)
+  - ⚠️ **IMPORTANT**: For AMO extension (NoScript and uBlock), updating the version in the URL is not enough, check that also a numeric ID from the URL has changed
+- [ ] Tor and dependencies updates (Tor Browser only)
+  - [ ] [Tor](https://gitlab.torproject.org/tpo/core/tor/-/tags)
+  - [ ] [OpenSSL](https://www.openssl.org/source/): we stay on the latest LTS channel (currently 3.0.x)
+  - [ ] [zlib](https://github.com/madler/zlib/releases)
+  - [ ] [Zstandard](https://github.com/facebook/zstd/releases) (Android only, at least for now)
+  - [ ] [Go](https://go.dev/dl): avoid major updates, unless planned
+- [ ] Manual version update (Tor Browser only, optional)
+- [ ] Changelogs
+  - [ ] Check the browser name
+  - [ ] Check the version
+  - [ ] Check the release date
+  - [ ] Check we include only the platform we're releasing for (e.g., no Android in desktop-only releases)
+  - [ ] Check all the updates from above are reported in the changelogs
+  - [ ] Check for major errors
+    - If you find errors such as platform or category (build system) please adjust the issue label accordingly
+    - You can run `tools/relprep.py --only-changelogs --date $date $version` to update only the changelogs
+
+### Review
+
+#### Request Reviewer
+
+- [ ] Request review from a release engineer: boklm, dan, ma1, morgan, pierov
+
+#### Change Description
+

.gitmodules

 [submodule "rbm"]
 	path = rbm
-	url = https://git.torproject.org/builders/rbm.git
+	url = https://gitlab.torproject.org/tpo/applications/rbm.git

ChangeLog-MB.txt

+projects/browser/Bundle-Data/Docs-MB/ChangeLog.txt
\ No newline at end of file

ChangeLog-TBB.txt

+projects/browser/Bundle-Data/Docs-TBB/ChangeLog.txt
\ No newline at end of file

LICENSE

+This file contains the license for the build recipes and tools used in
+the Tor Browser development process, that are included in this repository.
+
+For the license of specific components included in Tor Browser, see
+directory projects/browser/Bundle-Data/Docs/Licenses.
+
+===============================================================================
+
+Copyright (c) 2020, The Tor Project, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+
+    * Neither the names of the copyright owners nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README

@@ -4,16 +4,16 @@ Tor Browser Build
 Installing build dependencies
 -----------------------------
 
-To build Tor Browser, you need a Linux distribution that has support
-for Docker (such as Debian jessie, Ubuntu 14.04, Fedora 20, etc ...).
-The Docker package is usually named docker.io or docker-io.
-On Debian jessie, the docker.io package is available in backports.
+To build Tor Browser, you need a recent Linux distribution with support
+for user_namespaces(7) (such as Debian Buster, Ubuntu 16.04, Fedora 30,
+etc ...). You will need to install the uidmap package, providing the
+newuidmap and newgidmap commands.
 
-Your user account should have access to the docker command without using
-sudo, so it should be in the docker group. The docker daemon should
-also be running.
+The sources of most components are downloaded using git, which needs to
+be installed.
 
-The sources are downloaded using git which needs to be installed.
+Zstandard (zstd) is used to compress some tarballs and needs to be
+installed. You'll also need tar >= 1.31, for zstd support.
 
 You also need a few perl modules installed:
 - YAML::XS
@@ -21,24 +21,81 @@ You also need a few perl modules installed:
 - Getopt::Long
 - Template
 - IO::Handle
-- IO::CaptureOutput
+- Capture::Tiny
+- JSON
 - File::Temp
-- File::Slurp
+- Path::Tiny
 - File::Path
+- File::Slurp
+- File::Copy::Recursive
 - String::ShellQuote
 - Sort::Versions
 - Digest::SHA
 - Data::UUID
 - Data::Dump
+- DateTime
+- XML::Writer
+- Parallel::ForkManager
 
 If you are running Debian or Ubuntu, you can install them with:
 
-# apt-get install libyaml-libyaml-perl libtemplate-perl \
-                  libio-handle-util-perl libio-all-perl \
-                  libio-captureoutput-perl libfile-slurp-perl \
-                  libstring-shellquote-perl libsort-versions-perl \
-                  libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
-                  git
+# apt-get install libdata-dump-perl libdata-uuid-perl libdatetime-perl \
+                  libdigest-sha-perl libfile-copy-recursive-perl \
+                  libfile-slurp-perl libio-all-perl libcapture-tiny-perl \
+                  libio-handle-util-perl libjson-perl \
+                  libparallel-forkmanager-perl libpath-tiny-perl \
+                  libsort-versions-perl libstring-shellquote-perl \
+                  libtemplate-perl libxml-libxml-perl libxml-writer-perl \
+                  libyaml-libyaml-perl git uidmap zstd
+
+If you are running Fedora, CentOS or RHEL, you can install them with:
+
+# dnf install "perl(YAML::XS)" "perl(File::Basename)" "perl(Getopt::Long)" \
+              "perl(Template)" "perl(IO::Handle)" "perl(Capture::Tiny)" \
+              "perl(JSON)" "perl(File::Temp)" "perl(Path::Tiny)" \
+              "perl(File::Path)" "perl(File::Slurp)" \
+              "perl(File::Copy::Recursive)" "perl(String::ShellQuote)" \
+              "perl(Sort::Versions)" "perl(Digest::SHA)" "perl(Data::UUID)" \
+              "perl(Data::Dump)" "perl(DateTime)" "perl(XML::Writer)" \
+              "perl(Parallel::ForkManager)" perl-ph git zstd
+
+If you are running an Arch based system, you should be able to install them with:
+
+# pacman -S perl-datetime perl-path-tiny perl-yaml perl-yaml-libyaml \
+            perl-yaml-tiny perl-template-toolkit perl-capture-tiny \
+            perl-file-copy-recursive perl-string-shellquote \
+            perl-sort-versions perl-data-uuid perl-data-dump perl-json \
+            perl-digest-sha1 perl-io-all perl-file-slurp perl-sys-syscall \
+            perl-parallel-forkmanager perl-xml-libxml perl-lwp-protocol-https \
+            zstd
+
+On Arch based systems you also need to generate some .ph files RBM expects:
+
+	# cd /usr/include/sys; h2ph syscall.h
+	# cd /usr/include/; h2ph asm/unistd.h asm/unistd_64.h bits/syscall.h
+
+The build system is based on rbm, which is included as a git submodule
+in the rbm/ directory. You can fetch the rbm git submodule by running
+'make submodule-update'.
+
+The build uses user_namespaces(7), which are disabled by default on Debian
+and on Ubuntu v24.04 and later. To enable them on Debian you can use the
+following command as root:
+
+  # sysctl -w kernel.unprivileged_userns_clone=1
+
+To enable them on Ubuntu v24.04 and later, you can use the following command
+as root:
+
+  # sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+
+You can enable them permanently by adding the settings to /etc/sysctl.d/
+
+The user you use to build needs to have a range of subordinate uids and
+gids in /etc/subuid and /etc/subgid. Most of the time they are added by
+default when the user is created. If it was not the case, you can use
+usermod(8) with the --add-subuids and --add-subgids options. See also
+the subuid(5) and subgid(5) man pages.
 
 
 Starting a build
@@ -47,36 +104,61 @@ Starting a build
 To start a build, run one of the following commands, depending on the
 channel you want to build:
 
-  $ make release
-  $ make alpha
-  $ make nightly
-  $ make alpha_nightly
+  $ make torbrowser-release
+  $ make torbrowser-alpha
+  $ make torbrowser-nightly
 
-You can find the build result in the directory release/unsigned/$version
-or alpha/unsigned/$version for release or alpha builds. The result of
-nightly or alpha_nightly can be found in the nightly/$date or
-alpha_nightly/$date directory.
-
-The alpha and alpha_nightly make target will build the same thing. The
-only difference is the output directory. The alpha_nightly target can be
-useful if you want to do a test build without polluting your alpha
-directory.
+You can find the build result in the directory
+torbrowser/release/unsigned/$version or torbrowser/alpha/unsigned/$version
+for release or alpha builds. The result of nightly can be found in the
+torbrowser/nightly/$version directory.
 
 If you want to build for a specific platform only, append the platform
 name to the makefile target:
 
-  $ make nightly-linux-x86_64
-  $ make nightly-linux-i686
-  $ make nightly-windows-i686
-  $ make nightly-osx-x86_64
+  $ make torbrowser-nightly-linux-x86_64
+  $ make torbrowser-nightly-linux-i686
+  $ make torbrowser-nightly-windows-i686
+  $ make torbrowser-nightly-windows-x86_64
+  $ make torbrowser-nightly-macos
+  $ make torbrowser-nightly-android-armv7
+  $ make torbrowser-nightly-android-aarch64
+  $ make torbrowser-nightly-android-x86
+  $ make torbrowser-nightly-android-x86_64
+
+When you want to quickly do a build to test a change, you can use the
+testbuild makefile target, and find the build in the testbuild directory.
+The build will be the same as regular alpha builds, except that in order
+to make the build faster, only the en-US locale will be built, and no
+mar file will be created. If you want to base your testbuild on the latest
+nightly code insted, rename rbm.local.conf.example to rbm.local.conf
+and adapt the torbrowser-testbuild option accordingly.
+
+Similar makefile targets exist for building Base Browser and Privacy Browser
+instead of Tor Browser. To build Base Browser, replace `torbrowser` by
+`basebrowser` in the target name. For Privacy Browser, use `privacybrowser`.
 
 
 Updating git sources
 --------------------
 
-You can run "make fetch" to fetch the latest sources from git for all
+You can run `make fetch` to fetch the latest sources from git for all
 components included in Tor Browser. You should run this if you want to
-make a nightly build with the latest commits.
+make a nightly build with the latest commits, and you disabled automatic
+fetching of new commits for nightly builds in rbm.local.conf.
+
+
+Number of make processes
+------------------------
+
+By default `nproc` is used to determine the number of processes to run
+simultaneously (with make -jN where N is the number returned by `nproc`).
+If you want to change the number of processes used, you can set the
+RBM_NUM_PROCS environment variable:
+
+  $ export RBM_NUM_PROCS=8
+
+You can also set the num_procs option in rbm.local.conf.
 
 
 Automated builds
@@ -93,17 +175,17 @@ Or set the debug option to 0 in the rbm.local.conf file.
 
 If you want to select the output directory, you can use rbm's --output-dir
 option. You can look at the Makefile to find the rbm command for what
-you want to build, and add the --output-dir option. For example if you
+you want to build, and add the --output-dir option. For example, if you
 want to build Tor Browser nightly for linux-x86_64:
 
-   ./rbm/rbm build release --output-dir=/var/builds/nightly/2017-01-23 \
+   ./rbm/rbm build release --output-dir=/var/builds/nightly/2020-05-23 \
                         --target nightly --target torbrowser-linux-x86_64
 
 The files will be put in the directory selected by --output-dir in a
 subdirectory named as the version number (or current date for nightly).
 To remove this version subdirectory, add the noversiondir target:
 
-   ./rbm/rbm build release --output-dir=/var/builds/nightly/2017-01-23 \
+   ./rbm/rbm build release --output-dir=/var/builds/nightly/2020-05-23 \
                         --target nightly --target torbrowser-linux-x86_64 \
                         --target noversiondir
 
@@ -112,78 +194,82 @@ Automated builds using tbb-testsuite
 ------------------------------------
 
 The Tor Browser testsuite scripts can also be used to do nightly builds
-and publish the build logs.
+and publish the build logs. This page has some information about the
+setup we use for nightly builds:
+https://gitlab.torproject.org/tpo/applications/tor-browser/-/wikis/Nightly_Builds_Setup
 
-If you want to do that, start by cloning the git repository:
 
-   $ git clone https://git.torproject.org/boklm/tor-browser-bundle-testsuite.git
+Signing builds
+--------------
 
-Install some dependencies:
+If the environment variable RBM_SIGN_BUILD is set to 1, the
+sha256sums-unsigned-build.txt and sha256sums-unsigned-build.incrementals.txt
+files will be signed with gpg. You can use the RBM_GPG_OPTS environment
+variable to add some options to the gpg command used to sign the file.
+You can also set the var/sign_build and var/sign_build_gpg_opts options
+in the rbm.local.conf file.
 
-   # apt-get install -y libdata-dump-perl libfile-slurp-perl \
-               libio-captureoutput-perl perlmagick libjson-perl \
-               libwww-perl liblwp-protocol-https-perl libtemplate-perl \
-               libyaml-syck-perl libdatetime-perl \
-               libemail-sender-perl libemail-simple-perl libfile-type-perl \
-               libipc-run-perl libxml-libxml-perl
 
-Copy the config/tor-browser_build-boklm file and edit it:
+Cleaning obsolete files and containers images
+---------------------------------------------
 
-   $ cd tor-browser-bundle-testsuite
-   $ cp config/tor-browser_build-boklm config/tor-browser_build-$user
-   $ vim config/tor-browser_build-$user
+You can run `make clean` to clean old build files and containers that
+are no longer used in current builds. Before doing that, you need to
+configure the branches and build targets you are using in the
+rbm.local.conf file. The cleaning script will check out all the configured
+branches to create a list of used build files, and delete the files
+from the 'out' directory that are not used. If you want to see the list
+of files and containers that would be removed without doing it, you can
+use `make clean-dry-run`.
 
-Change the publish_dir and publish_url options. The publish_dir option is
-the local directory where the builds will be stored. The publish_url
-option is the public URL where the builds will be available.
 
-Copy the tools/tor-browser-builds-boklm file and edit it to change the
---config= option:
+Building without containers (Android builds only)
+-------------------------------------------------
 
-   $ cp tools/tor-browser-builds-boklm tools/tor-browser-builds-$user
-   $ vim tools/tor-browser-builds-$user
+By default the build is done inside containers. Adding the no_containers
+target will disable the use of containers. The following commands can
+be used to build the alpha version for e.g. android-armv7:
 
-You can now run ./tools/tor-browser-builds-$user to start the build, and
-add it to you crontab.
+  ./rbm/rbm build release --target no_containers --target testbuild \
+                          --target torbrowser-android-armv7
 
-The html build reports will be available in the reports/ directory, and
-the build files in the tor-browser-builds/ directory (unless you changed
-the publish_dir option).
+Note: the logs will still show the use and creation of a container image
+called "containers_disabled". This is due to the way we disable the use
+of containers: the container-image project is still called, but it will
+just create an empty file instead of a real container image.
 
+The build without containers is currently only supported for the Android
+builds, and will require that you run Debian Bullseye or Bookworm and
+install build dependencies for all the components that are built. This can
+be done with the following command:
 
-Signing builds
---------------
+  # apt-get install 7zip apksigner autoconf autoconf2.13 automake autopoint \
+                    autotools-dev bison bsdiff build-essential bzip2 \
+                    gettext-base gyp jq libfile-slurp-perl \
+                    libparallel-forkmanager-perl libssl-dev libtool libtool \
+                    openjdk-11-jdk pkg-config python3 python3-venv tcl unzip \
+                    wget xz-utils yasm zip zlib1g-dev
 
-If the environment variable RBM_SIGN_BUILD is set to 1, the
-sha256sums-unsigned-build.txt file will be signed with gpg.
-You can use the RBM_GPG_OPTS environment variable to add some options
-to the gpg command used to sign the file. You can also set the
-var/sign_build and var/sign_build_gpg_opts options in the rbm.local.conf
-file.
+Note that Debian Bullseye requires the bullseye-backports repository to
+get the 7zip package.
 
 
-Cleaning obsolete files and containers images
----------------------------------------------
+Common Build Errors
+-------------------
 
-There will be a script to clean old build files and containers that are
-no longer used, but it has not been added yet.
+You can look at the file doc/BUILD_ERRORS.txt for a list of common build
+errors and their solutions.
 
 
-Multiple build directories on the same host
--------------------------------------------
+Hacking on the Tor Browser build
+--------------------------------
 
-You can do multiple builds of Tor Browser in different directories on
-the same host. However the docker images namespace is global, so you
-may have some conflicts with the same image names used by the
-different builds. By default, the docker images are prefixed with
-tor-browser_$USER. You can change this prefix by defining the
-docker_image_prefix option in rbm.local.conf, using a different prefix
-for each of your build directories.
+The file doc/HACKING.txt tries to list the main things to know when
+making changes to the Tor Browser build.
 
 
-Common Build Errors
--------------------
+Description of makefile rules
+-----------------------------
 
-You can look at the README.BUILD_ERRORS file for a list of common build
-errors and their solutions.
+You can find a description of the Makefile rules in the file doc/MAKEFILE.txt.
 

README.BUILD_ERRORS

-This file lists some common build errors and their solutions.
-
-
-Error starting remote
----------------------
-
-If you have an error like this:
-
-----
-Error: Error starting remote:
-/bin/sh: 1: adduser: not found
-Segmentation fault (core dumped)
-----
-
-You might be having this issue:
-https://github.com/docker/docker/issues/28705
-
-When the kernel is configured with CONFIG_LEGACY_VSYSCALL_NONE, running
-Debian Wheezy containers fails with a segfault. This should be fixed by
-adding "vsyscall=emulate"to the kernel cmdline.
-
-If you are building inside Qubes, you can change the kernel cmdline for
-the VM you are using with something like this in dom0:
-
-----
-$ qvm-pref --get [vmname] kernelopts
-nopat
-$ qvm-pref --set [vmname] kernelopts 'nopat vsyscall=emulate'
-----
-
-
-tmp partition is full
----------------------
-
-If your /tmp partition is small, you will get a 'No space left on device'
-error during the build. To select an other directory with more space
-available to store temporary files, you can define the TMPDIR environment
-variable:
-
-----
-$ mkdir /home/user/tmp
-$ export TMPDIR=/home/user/tmp
-----
-
-You can also define the tmp_dir option in the rbm.local.conf file.
-

doc/BUILD_ERRORS.txt

+This file lists some common build errors and their solutions.
+
+
+Error starting remote
+---------------------
+
+If you have an error like this:
+
+----
+Error: Error starting remote:
+could not synchronise with container process: no subsystem for mount
+----
+
+You may be experiencing a similar but different problem. Anecdotally
+this occured on Ubuntu 18.04 Bionic, kernel 4.15.0-24-generic. You need
+to add systemd.legacy_systemd_cgroup_controller=1 to the kernel
+boot commandline in /etc/default/grub (followed by `sudo update-grub`).
+
+
+Error during debootstrap image creation
+---------------------------------------
+
+If the debootstrap-image-.log contains errors similar to the following:
+W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/zesty/InRelease
+   Temporary failure resolving 'archive.ubuntu.com'
+
+Check /etc/resolv.conf on the host to see if the nameserver is set to
+127.0.0.1. This can happen when runc performs a bind mount of
+/etc/resolv.conf and the host system is running systemd-resolved.
+
+sudo systemctl disable systemd-resolved.service
+sudo service systemd-resolved stop
+
+Put the following line in the [main] section of your
+/etc/NetworkManager/NetworkManager.conf:
+
+dns=default
+
+Delete the symlink /etc/resolv.conf
+
+rm /etc/resolv.conf
+
+Restart network-manager
+
+sudo service network-manager restart
+
+
+Could not find uid in /etc/subuid
+---------------------------------
+
+In some cases you can have the error:
+
+  Error: Error starting remote:
+  Error: Could not find uid in /etc/subuid
+  Error: failed to set uidmap
+
+The user you use to build needs to have a range of subordinate uids and
+gids in /etc/subuid and /etc/subgid. Most of the time they are added by
+default when the user is created. If it was not the case, you can use
+usermod(8) with the --add-subuids and --add-subgids options. See also
+the subuid(5) and subgid(5) man pages.
+
+Note that the root user is not exempted from the requirement for a
+valid /etc/subuid and /etc/subgid entry, if you are building as root.

doc/HACKING.txt

+Hacking on Tor Browser Build
+============================
+
+This file tries to list the main things to know when making changes to
+the Tor Browser build.
+
+
+rbm documentation
+-----------------
+
+If you go to directory rbm/doc, you can find the rbm documentation. You
+can build it with 'make html' or 'make man'.
+
+
+Using and defining options
+--------------------------
+
+Options can be used in templates with the following syntax:
+
+  [% c("option_name") %]
+
+More details about the templates syntax can be found in
+rbm/doc/rbm_templates.7 and [http://template-toolkit.org/docs/manual/index.html].
+
+Some options have a specific meaning to rbm. You can see their descriptions
+in rbm/doc/rbm_config.7 and rbm/doc/rbm_input_files.7.
+
+When the option does not have a specific meaning to rbm, it is a good
+idea to define it under var/ to avoid potential conflicts in option names
+with a future version of rbm.
+
+The options can be defined in different places:
+
+- rbm.conf for options available to all components
+- project/$project/config for options available to one component
+- rbm.local.conf for user defined options
+
+In each of those places, an option can be defined:
+
+- at the root of the document
+- under targets/$target/, in which case the definition only applies when
+  a specific target is defined
+
+The targets are usually used to select:
+
+- the platform: torbrowser-linux-x86_64, torbrowser-linux-i686,
+  torbrowser-windows-i686, torbrowser-windows-x86_64, torbrowser-macos,
+  torbrowser-android-armv7, torbrowser-android-aarch64, torbrowser-android-x86,
+  torbrowser-android-x86_64
+- the channel: release, nightly, alpha
+
+The targets torbrowser-linux-x86_64, torbrowser-linux-i686,
+torbrowser-windows-i686, torbrowser-windows-x86_64, torbrowser-macos,
+torbrowser-android-armv7, torbrowser-android-x86, torbrowser-android-aarch64,
+torbrowser-android-x86_64 are special cases. They do not contain options
+directly, instead they contain a list of other targets. For instance, the
+torbrowser-linux-x86_64 target is pointing to the linux-x86_64 and linux
+targets. You should define an option under the linux target if it applies to
+Linux on both architectures, or under the linux-x86_64 if it only applies to
+the x86_64 architecture.
+
+An option that is defined at the root of rbm.conf can be overridden by
+an other definition under a target, or inside projects/$project/config.
+You can find the complete priority order in rbm/doc/rbm_config.7.
+
+
+Defining a project's filename
+-----------------------------
+
+The filename option defines the output file or directory from the build
+of a component. If the file or directory exists in the out/$component
+directory, the component will not be rebuilt when it is used as a
+dependency from an other component.
+
+The filename is usually something like this:
+
+  filename: '[% project %]-[% c("version") %]-[% c("var/osname") %]-[% c("var/build_id") %].tar.gz'
+
+The var/build_id value is a hash that is based on the build inputs of
+the component:
+ - the build script (after template evaluation)
+ - the container definition
+ - the input files (the filename when it is a dependency on an other
+   project, the filename and hash of its content otherwise)
+This means that each time the build script, the container or one of the
+dependencies is modified, the output filename will change and a rebuild
+of the component will be required.
+
+The version and var/osname values could be removed from the filename,
+but they are useful to get an idea of what a file contains.
+
+
+Adding some Linux/Windows/OSX specific changes to a build script
+----------------------------------------------------------------
+
+You can use the following template syntax in the build scripts:
+
+  [% IF c("var/linux") -%]
+    # do something for linux
+  [% ELSIF c("var/windows") -%]
+    # do something for windows
+  [% ELSIF c("var/macos") -%]
+    # do something for macOS
+  [% END -%]
+
+You can also use var/linux-x86_64 and var/linux-i686 for things that
+only apply to x86_64 and i686 linux builds. You can use the var/release,
+var/alpha and var/nightly options to do things depending on the channel.
+
+As an alternative you can define an option with a different value
+depending on the target:
+
+  targets:
+    linux:
+      var:
+        do_something: 'do something for linux'
+    windows-i686:
+      var:
+        do_something: 'do something for windows'
+    macos-x86_64:
+      var:
+        do_something: 'do something for macos'
+
+And in the build script, use:
+
+  [% c("var/do_something") %]
+
+
+Evaluating a component's build script
+-------------------------------------
+
+If you want to look at the build script used to build a component for a
+specific platform/channel, you can use the following command:
+
+   $ ./rbm/rbm showconf $component build --target $channel --target $platform
+
+$component should be replaced by the name of the component.
+
+$channel should be one of the following:
+
+ - release
+
+ - alpha
+
+ - nightly
+
+$platform should be one of the following:
+
+ - torbrowser-linux-x86_64
+
+ - torbrowser-linux-i686
+
+ - torbrowser-windows-i686
+
+ - torbrowser-windows-x86_64
+
+ - torbrowser-macos
+
+ - torbrowser-android-armv7
+
+ - torbrowser-android-aarch64
+
+ - torbrowser-android-x86
+
+ - torbrowser-android-x86_64
+
+For example, to see tor's build script for linux x86_64 on the alpha
+channel, you can use:
+
+  $ ./rbm/rbm showconf tor build --target alpha --target \
+    torbrowser-linux-x86_64
+
+If the component you are looking at has many dependencies, the display
+can take some time as various build_id values need to be computed. If
+you don't care about the accuracy of input and output file names, you
+can add '--target no_build_id' to the command line. For instance, if you
+want to look at the build script for the browser component (which
+has a lot of dependencies), you can use:
+
+  $ ./rbm/rbm showconf browser build --target alpha --target \
+     torbrowser-linux-x86_64 --target no_build_id
+
+The same type of commands can be used to look at any option values,
+replacing build with the name of the option you want to look at. For
+instance, if you want to know the output filename of tor on linux-x86_64
+on the alpha channel, you can use:
+
+  $ ./rbm/rbm showconf tor filename --target alpha --target \
+    torbrowser-linux-x86_64
+
+
+Building a single component
+---------------------------
+
+When you are working on some changes to a component, before creating a
+full bundle with those changes, you might want to try a build of the
+component you modified only.
+
+This can be done with the following command:
+
+   $ ./rbm/rbm build $component --target $channel --target $platform
+
+See the previous section "Evaluating a component's build script" for a
+list of possible values for $channel and $platform.
+
+For instance, if you want to build tor for linux-x86_64 on the alpha
+channel, you can run:
+
+   $ ./rbm/rbm build tor --target alpha --target torbrowser-linux-x86_64
+
+To find the resulting file from the build, you can use 'ls -ltr out/tor/'
+to find the file with the last modification time.
+
+
+Patching Firefox (or an other component)
+----------------------------------------
+
+If you want to test a Firefox patch, the easiest way to do it is to
+copy the patch file to the projects/firefox/ directory, then edit
+projects/firefox/config to add the new patch to the list of input_files:
+
+  - filename: patch-for-XXXX.patch
+
+Then edit projects/firefox/build to add a line somewhere (probably just
+before running the configure script) to apply the patch:
+
+  patch -p1 < $rootdir/patch-for-XXXX.patch
+
+You can now run 'make torbrowser-testbuild' (or an other build target)
+to start a build with the patch.
+
+As an alternative, if you have your patch in a git repository, you can
+edit projects/firefox/config to change the git_url option to point to
+your git repository, and change the git_hash option to point to the
+commit you want to build. If the new git_hash option is not pointing to
+a signed tag, you will also need to comment the 'tag_gpg_id: 1' line.
+The git_hash option can point to a tag, a commit, a branch or anything
+that is understood by git.
+
+If you specify a branch in the git_hash option, you don't need to prefix
+it with a git remote name as all branches from the git repository
+selected in the git_url option are created as local branches.
+
+If you want to work on a local git repository, it is not a good idea to
+work on the git_clones/firefox repository directly. Instead you should
+create a separate git repository and update the git_url option with a
+file:// URL pointing to your repository.
+
+After changing the git_url option or when new commits have been added
+to a branch, you should run "make fetch" before starting a build to get
+the new commits. If you want to fetch new commits automatically when
+starting a new build you can add a "fetch: 1" line to
+projects/firefox/config.
+
+Remember that the git_hash option has different definitions for alpha
+and nightly builds, so you should modify the right one depending on
+what type of build you are doing (see also the "Types of builds" section).
+
+The first alternative is not working in case patches contain binary diffs,
+which the patch command can't handle. However, working with submodules can
+make the git branch alternative tricky to use. In that case you can resort
+to a third option by installing git in the build container (via var/deps in
+the respective config file). Then you can change to the submodule directory
+in the build script and do a
+
+  git apply patch-for-XXXX.patch
+
+after adding the patch to the project's config file (see above).
+
+The Firefox mozconfig files
+---------------------------
+
+In the gitian build, we are using the mozconfig files included in the
+tor-browser.git repository (the .mozconfig, .mozconfig-mac and
+.mozconfig-mingw files).
+
+In the rbm build however, we need to make some small modifications to
+those files, so we are instead using mozconfig files stored in the
+projects/firefox/ directory, ignoring the .mozconfig files from the
+tor-browser.git repository.
+
+This could change in the future, when we are not using Gitian anymore.
+
+
+Debugging a build error
+-----------------------
+
+If the build fails, a debugging shell will automatically be opened in
+the container used for the build (unless you set debug to 0 in
+rbm.local.conf).
+
+Before using the debugging shell, you can first look at the build logs
+in an other terminal (the filename of the log file is indicated in the
+rbm output).
+
+In the debug shell, you can type 'bash' to get a shell with completion.
+You can then look at the 'build' file, and copy paste some of its commands
+to debug the problem. If you need to edit files, vim is not installed
+in the build containers, but vi can be used instead.
+
+When you press ctrl+d (twice if you opened a bash shell) the debug shell
+is closed and the container containing the failed build is removed.
+
+The path to the container should be printed on the screen in case you
+want to backup its rootfs to be able to look at it later.
+
+
+Manually removing old containers
+--------------------------------
+
+When a build finishes or when you exit a debugging shell, the old
+container should automatically be removed. In some cases however, for
+example your computer is rebooted in the middle of a build, some old
+container directories may be left in the tmp directory. Some of the
+files in the container directories are owned by subordinate user ids
+(see the subuid man page), which will prevent you from removing them
+with your normal user id. To remove them you can open a container
+shell (a new User namespace) using the following command:
+
+   $ ./rbm/container run -- /bin/bash
+
+From this shell you should be able to remove the old containers
+directories in the tmp directory.
+
+It is also possible to pass the rm command directly without opening a
+shell:
+
+   $ ./rbm/container run -- rm -Rf ./tmp/rbm-*
+
+
+Testing an rbm patch
+--------------------
+
+When you are working on a patch to rbm, you might want to try a Tor
+Browser build using your patched version of rbm. You could patch the
+rbm in the rbm/ directory, however your patch can be reverted if you
+use any of the makefile rules that does a 'git submodule update'.
+To avoid this you can clone the rbm git repository to a separate
+directory, where you will apply your patch. To do a build using your
+patched rbm, take the command from the makefile, but replace $(rbm)
+with the path to your patched rbm.
+
+For example, if you want to try a Linux x86_64 alpha build, you can run:
+  $ /path_to_rbm/rbm build release --target alpha --target \
+                                                torbrowser-linux-x86_64
+
+
+Types of builds: nightly, alpha, release, and testbuild
+-------------------------------------------------------
+
+The torbrowser-testbuild makefile target allows you to do a build
+quickly in the testbuild directory, skipping the generation of all the
+locales and the .mar files. This is useful during development.
+
+In the case of Android builds, we are generating a multi-locale apk,
+contrary to the desktop builds where we have one bundle for each locale.
+Removing locales in a multi-locale bundle does not make a significant
+difference in build time, therefore we still include all the locales in
+the Android testbuild. There are also no .mar files generated in the
+Android builds, so currently, in the Android case, the only difference
+introduced by the testbuild target is the output directory.
+
+By default the testbuild is based on the alpha build. All the options
+can have a different definition for the alpha, release and nightly builds.
+Usually the git_hash option has a different definition for the nightly
+builds in order to point to the main branch.
+
+If you want your testbuild target to create builds based on nightly
+rather than alpha, you can edit your rbm.local.conf file and uncomment
+the targets/torbrowser-testbuild definition.