1Release Process
2====================
3
4## Branch updates
5
6### Before every release candidate
7
8* Update release candidate version in `CMakeLists.txt` (`CLIENT_VERSION_RC`).
9* Update manpages (after rebuilding the binaries), see [gen-manpages.py](/contrib/devtools/README.md#gen-manpagespy).
10* Update bitcoin.conf and commit changes if they exist, see [gen-bitcoin-conf.sh](/contrib/devtools/README.md#gen-bitcoin-confsh).
11
12### Before every major and minor release
13
14* Update [bips.md](bips.md) to account for changes since the last release.
15* Update version in `CMakeLists.txt` (don't forget to set `CLIENT_VERSION_RC` to `0`).
16* Update manpages (see previous section)
17* Write release notes (see "Write the release notes" below) in doc/release-notes.md. If necessary,
18  archive the previous release notes as doc/release-notes/release-notes-${VERSION}.md.
19
20### Before every major release
21
22* On both the master branch and the new release branch:
23  - update `CLIENT_VERSION_MAJOR` in [`CMakeLists.txt`](../CMakeLists.txt)
24* On the new release branch in [`CMakeLists.txt`](../CMakeLists.txt)(see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)):
25  - set `CLIENT_VERSION_MINOR` to `0`
26  - set `CLIENT_VERSION_BUILD` to `0`
27  - set `CLIENT_VERSION_IS_RELEASE` to `true`
28* Check with the security team whether there is any security advisory to pre-announce.
29
30#### Before branch-off
31
32* Update translations see [translation_process.md](/doc/translation_process.md#synchronising-translations).
33* Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/27488) for an example.
34* Update embedded asmap data at `/src/node/data/ip_asn.dat`, see [asmap data documentation](./asmap-data.md).
35* Update the following variables in [`src/kernel/chainparams.cpp`](/src/kernel/chainparams.cpp) for mainnet, testnet, and signet:
36  - `m_assumed_blockchain_size` and `m_assumed_chain_state_size` with the current size plus some overhead (see
37    [this](#how-to-calculate-assumed-blockchain-and-chain-state-size) for information on how to calculate them).
38  - The following updates should be reviewed with `reindex-chainstate` and `assumevalid=0` to catch any defect
39    that causes rejection of blocks in the past history.
40  - `chainTxData` with statistics about the transaction count and rate. Use the output of the `getchaintxstats` RPC with an
41    `nBlocks` of 4096 (28 days) and a `bestblockhash` of RPC `getbestblockhash`; see
42    [this pull request](https://github.com/bitcoin/bitcoin/pull/28591) for an example. Reviewers can verify the results by running
43    `getchaintxstats <window_block_count> <window_final_block_hash>` with the `window_block_count` and `window_final_block_hash` from your output.
44  - `defaultAssumeValid` with the output of RPC `getblockhash` using the `height` of `window_final_block_height` above
45    (and update the block height comment with that height), taking into account the following:
46    - On mainnet, the selected value must not be orphaned, so it may be useful to set the height two blocks back from the tip.
47    - Testnet should be set with a height some tens of thousands back from the tip, due to reorgs there.
48  - `nMinimumChainWork` with the "chainwork" value of RPC `getblockheader` using the same height as that selected for the previous step.
49  - `m_assumeutxo_data` array should be appended to with the values returned by calling `bitcoin-cli -rpcclienttimeout=0 -named dumptxoutset utxo.dat rollback=<height or hash>`
50    The same height considerations for `defaultAssumeValid` apply.
51* Consider updating the headers synchronization tuning parameters to account for the chainparams updates.
52  The optimal values change very slowly, so this isn't strictly necessary every release, but doing so doesn't hurt.
53  - Update configuration variables in [`contrib/devtools/headerssync-params.py`](/contrib/devtools/headerssync-params.py):
54    - Set `TIME` to the software's expected supported lifetime -- after this time, its ability to defend against a high bandwidth timewarp attacker will begin to degrade.
55    - Set `MINCHAINWORK_HEADERS` to the height used for the `nMinimumChainWork` calculation above.
56    - Check that the other variables still look reasonable.
57  - Run the script. It works fine in CPython, but PyPy is much faster (seconds instead of minutes): `pypy3 contrib/devtools/headerssync-params.py`.
58  - Paste the output defining the header `commitment_period` and `redownload_buffer_size` into the mainnet section of [`src/kernel/chainparams.cpp`](/src/kernel/chainparams.cpp).
59- Clear the release notes and move them to the wiki (see "Write the release notes" below).
60- Translations on Transifex:
61    - Pull translations from Transifex into the master branch.
62    - Create [a new resource](https://app.transifex.com/bitcoin/bitcoin/content/) named after the major version with the slug `qt-translation-<RRR>x`, where `RRR` is the major branch number padded with zeros. Use `src/qt/locale/bitcoin_en.ts` to create it.
63    - In the project workflow settings, ensure that [Translation Memory Fill-up](https://help.transifex.com/en/articles/6224817-setting-up-translation-memory-fill-up) is enabled and that [Translation Memory Context Matching](https://help.transifex.com/en/articles/6224753-translation-memory-with-context) is disabled.
64    - Update the Transifex slug in [`.tx/config`](/.tx/config) to the slug of the resource created in the first step. This identifies which resource the translations will be synchronized from.
65    - Make an announcement that translators can start translating for the new version. You can use one of the [previous announcements](https://app.transifex.com/bitcoin/communication/) as a template.
66    - Change the auto-update URL for the resource to `master`, e.g. `https://raw.githubusercontent.com/bitcoin/bitcoin/master/src/qt/locale/bitcoin_en.ts`. (Do this only after the previous steps, to prevent an auto-update from interfering.)
67
68#### After branch-off (on the major release branch)
69
70- Update the versions.
71- Create the draft, named "*version* Release Notes Draft", as a [collaborative wiki](https://github.com/bitcoin-core/bitcoin-devwiki/wiki/_new).
72- Clear the release notes: `cp doc/release-notes-empty-template.md doc/release-notes.md`
73- Create a pinned meta-issue for testing the release candidate (see [this issue](https://github.com/bitcoin/bitcoin/issues/27621) for an example) and provide a link to it in the release announcements where useful.
74- Translations on Transifex
75    - Change the auto-update URL for the new major version's resource away from `master` and to the branch, e.g. `https://raw.githubusercontent.com/bitcoin/bitcoin/<branch>/src/qt/locale/bitcoin_en.ts`. Do not forget this or it will keep tracking the translations on master instead, drifting away from the specific major release.
76- Prune inputs from the qa-assets repo (See [pruning
77  inputs](https://github.com/bitcoin-core/qa-assets#pruning-inputs)).
78
79#### Before final release
80
81- Merge the release notes from [the wiki](https://github.com/bitcoin-core/bitcoin-devwiki/wiki/) into the branch.
82- Ensure the "Needs release note" label is removed from all relevant pull
83  requests and issues:
84  https://github.com/bitcoin/bitcoin/issues?q=label%3A%22Needs+release+note%22
85
86#### Tagging a release (candidate)
87
88To tag the version (or release candidate) in git, use the `make-tag.py` script from [bitcoin-maintainer-tools](https://github.com/bitcoin-core/bitcoin-maintainer-tools). From the root of the repository run:
89
90    ../bitcoin-maintainer-tools/make-tag.py v(new version, e.g. 25.0)
91
92This will perform a few last-minute consistency checks in the build system files, and if they pass, create a signed tag.
93
94## Building
95
96### First time / New builders
97
98Install Guix using one of the installation methods detailed in
99[contrib/guix/INSTALL.md](/contrib/guix/INSTALL.md).
100
101Check out the source code in the following directory hierarchy.
102
103    cd /path/to/your/toplevel/build
104    git clone https://github.com/bitcoin-core/guix.sigs.git
105    git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git
106    git clone https://github.com/bitcoin/bitcoin.git
107
108### Write the release notes
109
110Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki.
111
112For the period during which the notes are being edited on the wiki, the version on the branch should be wiped and replaced with a link to the wiki which should be used for all announcements until `-final`.
113
114Generate list of authors:
115
116    git log --format='- %aN' v(current version, e.g. 25.0)..v(new version, e.g. 25.1) | grep -v 'merge-script' | sort -fiu
117
118### Setup and perform Guix builds
119
120Checkout the Bitcoin Core version you'd like to build:
121
122```sh
123pushd ./bitcoin
124SIGNER='(your builder key, ie bluematt, sipa, etc)'
125VERSION='(new version without v-prefix, e.g. 25.0)'
126git fetch origin "v${VERSION}"
127git checkout "v${VERSION}"
128popd
129```
130
131Ensure your guix.sigs are up-to-date if you wish to `guix-verify` your builds
132against other `guix-attest` signatures.
133
134```sh
135git -C ./guix.sigs pull
136```
137
138### Create the macOS SDK tarball (first time, or when SDK version changes)
139
140Create the macOS SDK tarball, see the [macdeploy
141instructions](/contrib/macdeploy/README.md#sdk-extraction) for
142details.
143
144### Build and attest to build outputs
145
146Follow the relevant Guix README.md sections:
147- [Building](/contrib/guix/README.md#building)
148- [Attesting to build outputs](/contrib/guix/README.md#attesting-to-build-outputs)
149
150### Verify other builders' signatures to your own (optional)
151
152- [Verifying build output attestations](/contrib/guix/README.md#verifying-build-output-attestations)
153
154### Commit your non codesigned signature to guix.sigs
155
156```sh
157pushd ./guix.sigs
158git add "${VERSION}/${SIGNER}"/noncodesigned.SHA256SUMS{,.asc}
159git commit -m "Add attestations by ${SIGNER} for ${VERSION} non-codesigned"
160popd
161```
162
163Then open a Pull Request to the [guix.sigs repository](https://github.com/bitcoin-core/guix.sigs).
164
165## Codesigning
166
167### macOS codesigner only: Create detached macOS signatures (assuming [signapple](https://github.com/achow101/signapple/) is installed and up to date with master branch)
168
169In the `guix-build-${VERSION}/output/x86_64-apple-darwin` and `guix-build-${VERSION}/output/arm64-apple-darwin` directories:
170
171    tar xf bitcoin-${VERSION}-${ARCH}-apple-darwin-codesigning.tar.gz
172    ./detached-sig-create.sh /path/to/codesign.p12 /path/to/AuthKey_foo.p8 uuid
173    Enter the keychain password and authorize the signature
174    signature-osx.tar.gz will be created
175
176### Windows codesigner only: Create detached Windows signatures
177
178In the `guix-build-${VERSION}/output/x86_64-w64-mingw32` directory:
179
180    tar xf bitcoin-${VERSION}-win64-codesigning.tar.gz
181    ./detached-sig-create.sh /path/to/codesign.key
182    Enter the passphrase for the key when prompted
183    signature-win.tar.gz will be created
184
185### Windows and macOS codesigners only: test code signatures
186It is advised to test that the code signature attaches properly prior to tagging by performing the `guix-codesign` step.
187However if this is done, once the release has been tagged in the bitcoin-detached-sigs repo, the `guix-codesign` step must be performed again in order for the guix attestation to be valid when compared against the attestations of non-codesigner builds. The directories created by `guix-codesign` will need to be cleared prior to running `guix-codesign` again.
188
189### Windows and macOS codesigners only: Commit the detached codesign payloads
190
191```sh
192pushd ./bitcoin-detached-sigs
193# checkout or create the appropriate branch for this release series
194git checkout --orphan <branch>
195# if you are the macOS codesigner
196rm -rf osx
197tar xf signature-osx.tar.gz
198# if you are the windows codesigner
199rm -rf win
200tar xf signature-win.tar.gz
201git add -A
202git commit -m "<version>: {osx,win} signature for {rc,final}"
203git tag -s "v${VERSION}" HEAD
204git push the current branch and new tag
205popd
206```
207
208### Non-codesigners: wait for Windows and macOS detached signatures
209
210- Once the Windows and macOS builds each have 3 matching signatures, they will be signed with their respective release keys.
211- Detached signatures will then be committed to the [bitcoin-detached-sigs](https://github.com/bitcoin-core/bitcoin-detached-sigs) repository, which can be combined with the unsigned apps to create signed binaries.
212
213### Create the codesigned build outputs
214
215- [Codesigning build outputs](/contrib/guix/README.md#codesigning-build-outputs)
216
217### Verify other builders' signatures to your own (optional)
218
219- [Verifying build output attestations](/contrib/guix/README.md#verifying-build-output-attestations)
220
221### Commit your codesigned signature to guix.sigs (for the signed macOS/Windows binaries)
222
223```sh
224pushd ./guix.sigs
225git add "${VERSION}/${SIGNER}"/all.SHA256SUMS{,.asc}
226git commit -m "Add attestations by ${SIGNER} for ${VERSION} codesigned"
227popd
228```
229
230Then open a Pull Request to the [guix.sigs repository](https://github.com/bitcoin-core/guix.sigs).
231
232## After 6 or more people have guix-built and their results match
233
234After verifying signatures, combine the `all.SHA256SUMS.asc` file from all signers into `SHA256SUMS.asc`:
235
236```bash
237cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc
238```
239
240
241- Upload to the bitcoincore.org server:
242    1. The contents of each `./bitcoin/guix-build-${VERSION}/output/${HOST}/` directory.
243
244       Guix will output all of the results into host subdirectories, but the SHA256SUMS
245       file does not include these subdirectories. In order for downloads via torrent
246       to verify without directory structure modification, all of the uploaded files
247       need to be in the same directory as the SHA256SUMS file.
248
249       Wait until all of these files have finished uploading before uploading the SHA256SUMS(.asc) files.
250