1Release Process 2==================== 3 4## Branch updates 5 6### Before every release candidate 7 8* Update translations see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). 9* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh). 10* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`). 11 12### Before every major and minor release 13 14* Update [bips.md](bips.md) to account for changes since the last release (don't forget to bump the version number on the first line). 15* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`). 16* Write release notes (see "Write the release notes" below). 17 18### Before every major release 19 20* On both the master branch and the new release branch: 21 - update `CLIENT_VERSION_MAJOR` in [`configure.ac`](../configure.ac) 22 - update `CLIENT_VERSION_MAJOR`, `PACKAGE_VERSION`, and `PACKAGE_STRING` in [`build_msvc/bitcoin_config.h`](/build_msvc/bitcoin_config.h) 23* On the new release branch in [`configure.ac`](../configure.ac) and [`build_msvc/bitcoin_config.h`](/build_msvc/bitcoin_config.h) (see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)): 24 - set `CLIENT_VERSION_MINOR` to `0` 25 - set `CLIENT_VERSION_BUILD` to `0` 26 - set `CLIENT_VERSION_IS_RELEASE` to `true` 27 28#### Before branch-off 29 30* Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/7415) for an example. 31* Update [`src/chainparams.cpp`](/src/chainparams.cpp) m_assumed_blockchain_size and m_assumed_chain_state_size with the current size plus some overhead (see [this](#how-to-calculate-assumed-blockchain-and-chain-state-size) for information on how to calculate them). 32* Update [`src/chainparams.cpp`](/src/chainparams.cpp) chainTxData with statistics about the transaction count and rate. Use the output of the `getchaintxstats` RPC, see 33 [this pull request](https://github.com/bitcoin/bitcoin/pull/20263) for an example. Reviewers can verify the results by running `getchaintxstats <window_block_count> <window_final_block_hash>` with the `window_block_count` and `window_final_block_hash` from your output. 34* Update `src/chainparams.cpp` nMinimumChainWork and defaultAssumeValid (and the block height comment) with information from the `getblockheader` (and `getblockhash`) RPCs. 35 - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip. 36 - Testnet should be set some tens of thousands back from the tip due to reorgs there. 37 - This update should be reviewed with a reindex-chainstate with assumevalid=0 to catch any defect 38 that causes rejection of blocks in the past history. 39- Clear the release notes and move them to the wiki (see "Write the release notes" below). 40- Translations on Transifex 41 - Create [a new resource](https://www.transifex.com/bitcoin/bitcoin/content/) named after the major version with the slug `[bitcoin.qt-translation-<RRR>x]`, where `RRR` is the major branch number padded with zeros. Use `src/qt/locale/bitcoin_en.xlf` to create it. 42 - In the project workflow settings, ensure that [Translation Memory Fill-up](https://docs.transifex.com/translation-memory/enabling-autofill) is enabled and that [Translation Memory Context Matching](https://docs.transifex.com/translation-memory/translation-memory-with-context) is disabled. 43 - 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. 44 - Make an announcement that translators can start translating for the new version. You can use one of the [previous announcements](https://www.transifex.com/bitcoin/bitcoin/announcements/) as a template. 45 - Change the auto-update URL for the resource to `master`, e.g. `https://raw.githubusercontent.com/bitcoin/bitcoin/master/src/qt/locale/bitcoin_en.xlf`. (Do this only after the previous steps, to prevent an auto-update from interfering.) 46 47#### After branch-off (on the major release branch) 48 49- Update the versions. 50- Create a pinned meta-issue for testing the release candidate (see [this issue](https://github.com/bitcoin/bitcoin/issues/17079) for an example) and provide a link to it in the release announcements where useful. 51- Translations on Transifex 52 - 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.xlf`. Do not forget this or it will keep tracking the translations on master instead, drifting away from the specific major release. 53 54#### Before final release 55 56- Merge the release notes from the wiki into the branch. 57- Ensure the "Needs release note" label is removed from all relevant pull requests and issues. 58 59#### Tagging a release (candidate) 60 61To 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: 62 63 ../bitcoin-maintainer-tools/make-tag.py v(new version, e.g. 0.20.0) 64 65This will perform a few last-minute consistency checks in the build system files, and if they pass, create a signed tag. 66 67## Building 68 69### First time / New builders 70 71Install Guix using one of the installation methods detailed in 72[contrib/guix/INSTALL.md](/contrib/guix/INSTALL.md). 73 74Check out the source code in the following directory hierarchy. 75 76 cd /path/to/your/toplevel/build 77 git clone https://github.com/bitcoin-core/guix.sigs.git 78 git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git 79 git clone https://github.com/bitcoin/bitcoin.git 80 81### Write the release notes 82 83Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki. 84 85For 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`. 86 87Generate the change log. As this is a huge amount of work to do manually, there is the `list-pulls` script to do a pre-sorting step based on github PR metadata. See the [documentation in the README.md](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/master/README.md#list-pulls). 88 89Generate list of authors: 90 91 git log --format='- %aN' v(current version, e.g. 0.20.0)..v(new version, e.g. 0.20.1) | sort -fiu 92 93### Setup and perform Guix builds 94 95Checkout the Bitcoin Core version you'd like to build: 96 97```sh 98pushd ./bitcoin 99SIGNER='(your builder key, ie bluematt, sipa, etc)' 100VERSION='(new version without v-prefix, e.g. 0.20.0)' 101git fetch "v${VERSION}" 102git checkout "v${VERSION}" 103popd 104``` 105 106Ensure your guix.sigs are up-to-date if you wish to `guix-verify` your builds 107against other `guix-attest` signatures. 108 109```sh 110git -C ./guix.sigs pull 111``` 112 113### Create the macOS SDK tarball: (first time, or when SDK version changes) 114 115Create the macOS SDK tarball, see the [macdeploy 116instructions](/contrib/macdeploy/README.md#deterministic-macos-dmg-notes) for 117details. 118 119### Build and attest to build outputs: 120 121Follow the relevant Guix README.md sections: 122- [Performing a build](/contrib/guix/README.md#performing-a-build) 123- [Attesting to build outputs](/contrib/guix/README.md#attesting-to-build-outputs) 124 125### Verify other builders' signatures to your own. (Optional) 126 127Add other builders keys to your gpg keyring, and/or refresh keys: See `../bitcoin/contrib/builder-keys/README.md`. 128 129Follow the relevant Guix README.md sections: 130- [Verifying build output attestations](/contrib/guix/README.md#verifying-build-output-attestations) 131 132### Next steps: 133 134Commit your signature to guix.sigs: 135 136```sh 137pushd ./guix.sigs 138git add "${VERSION}/${SIGNER}"/noncodesigned.SHA256SUMS{,.asc} 139git commit -m "Add ${VERSION} unsigned sigs for ${SIGNER}" 140git push # Assuming you can push to the guix.sigs tree 141popd 142``` 143 144Codesigner only: Create Windows/macOS detached signatures: 145- Only one person handles codesigning. Everyone else should skip to the next step. 146- Only once the Windows/macOS builds each have 3 matching signatures may they be signed with their respective release keys. 147 148Codesigner only: Sign the macOS binary: 149 150 transfer bitcoin-osx-unsigned.tar.gz to macOS for signing 151 tar xf bitcoin-osx-unsigned.tar.gz 152 ./detached-sig-create.sh -s "Key ID" 153 Enter the keychain password and authorize the signature 154 Move signature-osx.tar.gz back to the guix-build host 155 156Codesigner only: Sign the windows binaries: 157 158 tar xf bitcoin-win-unsigned.tar.gz 159 ./detached-sig-create.sh -key /path/to/codesign.key 160 Enter the passphrase for the key when prompted 161 signature-win.tar.gz will be created 162 163Code-signer only: It is advised to test that the code signature attaches properly prior to tagging by performing the `guix-codesign` step. 164However 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. 165 166Codesigner only: Commit the detached codesign payloads: 167 168```sh 169pushd ./bitcoin-detached-sigs 170# checkout the appropriate branch for this release series 171rm -rf ./* 172tar xf signature-osx.tar.gz 173tar xf signature-win.tar.gz 174git add -A 175git commit -m "point to ${VERSION}" 176git tag -s "v${VERSION}" HEAD 177git push the current branch and new tag 178popd 179``` 180 181Non-codesigners: wait for Windows/macOS detached signatures: 182 183- Once the Windows/macOS builds each have 3 matching signatures, they will be signed with their respective release keys. 184- 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. 185 186Create (and optionally verify) the codesigned outputs: 187 188- [Codesigning](/contrib/guix/README.md#codesigning) 189 190Commit your signature for the signed macOS/Windows binaries: 191 192```sh 193pushd ./guix.sigs 194git add "${VERSION}/${SIGNER}"/all.SHA256SUMS{,.asc} 195git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures" 196git push # Assuming you can push to the guix.sigs tree 197popd 198``` 199 200### After 3 or more people have guix-built and their results match: 201 202Combine the `all.SHA256SUMS.asc` file from all signers into `SHA256SUMS.asc`: 203 204```bash 205cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc 206``` 207 208 209- Upload to the bitcoincore.org server (`/var/www/bin/bitcoin-core-${VERSION}/`): 210 1. The contents of each `./bitcoin/guix-build-${VERSION}/output/${HOST}/` directory, except for 211 `*-debug*` files. 212 213 Guix will output all of the results into host subdirectories, but the SHA256SUMS 214 file does not include these subdirectories. In order for downloads via torrent 215 to verify without directory structure modification, all of the uploaded files 216 need to be in the same directory as the SHA256SUMS file. 217 218 The `*-debug*` files generated by the guix build contain debug symbols 219 for troubleshooting by developers. It is assumed that anyone that is 220 interested in debugging can run guix to generate the files for 221 themselves. To avoid end-user confusion about which file to pick, as well 222 as save storage space *do not upload these to the bitcoincore.org server, 223 nor put them in the torrent*. 224 225 ```sh 226 find guix-build-${VERSION}/output/ -maxdepth 2 -type f -not -name "SHA256SUMS.part" -and -not -name "*debug*" -exec scp {} user@bitcoincore.org:/var/www/bin/bitcoin-core-${VERSION} \; 227 ``` 228 229 2. The `SHA256SUMS` file 230 231 3. The `SHA256SUMS.asc` combined signature file you just created 232 233- Create a torrent of the `/var/www/bin/bitcoin-core-${VERSION}` directory such 234 that at the top level there is only one file: the `bitcoin-core-${VERSION}` 235 directory containing everything else. Name the torrent 236 `bitcoin-${VERSION}.torrent` (note that there is no `-core-` in this name). 237 238 Optionally help seed this torrent. To get the `magnet:` URI use: 239 240 ```sh 241 transmission-show -m <torrent file> 242 ``` 243 244 Insert the magnet URI into the announcement sent to mailing lists. This permits 245 people without access to `bitcoincore.org` to download the binary distribution. 246 Also put it into the `optional_magnetlink:` slot in the YAML file for 247 bitcoincore.org. 248 249- Update other repositories and websites for new version 250 251 - bitcoincore.org blog post 252 253 - bitcoincore.org maintained versions update: 254 [table](https://github.com/bitcoin-core/bitcoincore.org/commits/master/_includes/posts/maintenance-table.md) 255 256 - bitcoincore.org RPC documentation update 257 258 - Install [golang](https://golang.org/doc/install) 259 260 - Install the new Bitcoin Core release 261 262 - Run bitcoind on regtest 263 264 - Clone the [bitcoincore.org repository](https://github.com/bitcoin-core/bitcoincore.org) 265 266 - Run: `go run generate.go` while being in `contrib/doc-gen` folder, and with bitcoin-cli in PATH 267 268 - Add the generated files to git 269 270 - Update packaging repo 271 272 - Push the flatpak to flathub, e.g. https://github.com/flathub/org.bitcoincore.bitcoin-qt/pull/2 273 274 - Push the latest version to master (if applicable), e.g. https://github.com/bitcoin-core/packaging/pull/32 275 276 - Create a new branch for the major release "0.xx" from master (used to build the snap package) and request the 277 track (if applicable), e.g. https://forum.snapcraft.io/t/track-request-for-bitcoin-core-snap/10112/7 278 279 - Notify MarcoFalke so that he can start building the snap package 280 281 - https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging (Click "Import Now" to fetch the branch) 282 - https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging/+ref/0.xx (Click "Create snap package") 283 - Name it "bitcoin-core-snap-0.xx" 284 - Leave owner and series as-is 285 - Select architectures that are compiled via guix 286 - Leave "automatically build when branch changes" unticked 287 - Tick "automatically upload to store" 288 - Put "bitcoin-core" in the registered store package name field 289 - Tick the "edge" box 290 - Put "0.xx" in the track field 291 - Click "create snap package" 292 - Click "Request builds" for every new release on this branch (after updating the snapcraft.yml in the branch to reflect the latest guix results) 293 - Promote release on https://snapcraft.io/bitcoin-core/releases if it passes sanity checks 294 295 - This repo 296 297 - Archive the release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) 298 299 - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes 300 301- Announce the release: 302 303 - bitcoin-dev and bitcoin-core-dev mailing list 304 305 - Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/ 306 307 - Bitcoin Core Twitter https://twitter.com/bitcoincoreorg 308 309 - Celebrate 310 311### Additional information 312 313#### <a name="how-to-calculate-assumed-blockchain-and-chain-state-size"></a>How to calculate `m_assumed_blockchain_size` and `m_assumed_chain_state_size` 314 315Both variables are used as a guideline for how much space the user needs on their drive in total, not just strictly for the blockchain. 316Note that all values should be taken from a **fully synced** node and have an overhead of 5-10% added on top of its base value. 317 318To calculate `m_assumed_blockchain_size`: 319- For `mainnet` -> Take the size of the data directory, excluding `/regtest` and `/testnet3` directories. 320- For `testnet` -> Take the size of the `/testnet3` directory. 321 322 323To calculate `m_assumed_chain_state_size`: 324- For `mainnet` -> Take the size of the `/chainstate` directory. 325- For `testnet` -> Take the size of the `/testnet3/chainstate` directory. 326 327Notes: 328- When taking the size for `m_assumed_blockchain_size`, there's no need to exclude the `/chainstate` directory since it's a guideline value and an overhead will be added anyway. 329- The expected overhead for growth may change over time, so it may not be the same value as last release; pay attention to that when changing the variables. 330