1Release Process 2==================== 3 4## Branch updates 5 6### Before every release candidate 7 8* Update translations (ping wumpus on IRC) 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_MINOR` in [`configure.ac`](../configure.ac) 22 - update `CLIENT_VERSION_MINOR`, `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_REVISION` to `0` 25 - set `CLIENT_VERSION_IS_RELEASE` to `true` 26 27#### Before branch-off 28 29* Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/7415) for an example. 30* 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-m_assumed_blockchain_size-and-m_assumed_chain_state_size) for information on how to calculate them). 31* Update `src/chainparams.cpp` chainTxData with statistics about the transaction count and rate. Use the output of the RPC `getchaintxstats`, see 32 [this pull request](https://github.com/bitcoin/bitcoin/pull/17002) for an example. Reviewers can verify the results by running `getchaintxstats <window_block_count> <window_last_block_hash>` with the `window_block_count` and `window_last_block_hash` from your output. 33* Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc. 34* Update `src/chainparams.cpp` defaultAssumeValid with information from the getblockhash rpc. 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 41#### After branch-off (on master) 42 43- Update the version of `contrib/gitian-descriptors/*.yml`. 44 45#### After branch-off (on the major release branch) 46 47- Update the versions. 48- 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. 49 50#### Before final release 51 52- Merge the release notes from the wiki into the branch. 53- Ensure the "Needs release note" label is removed from all relevant pull requests and issues. 54 55 56## Building 57 58### First time / New builders 59 60If you're using the automated script (found in [contrib/gitian-build.py](/contrib/gitian-build.py)), then at this point you should run it with the "--setup" command. Otherwise ignore this. 61 62Check out the source code in the following directory hierarchy. 63 64 cd /path/to/your/toplevel/build 65 git clone https://github.com/bitcoin-core/gitian.sigs.git 66 git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git 67 git clone https://github.com/devrandom/gitian-builder.git 68 git clone https://github.com/bitcoin/bitcoin.git 69 70### Write the release notes 71 72Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki. 73 74For 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`. 75 76Write the release notes. `git shortlog` helps a lot, for example: 77 78 git shortlog --no-merges v(current version, e.g. 0.19.2)..v(new version, e.g. 0.20.0) 79 80(or ping @wumpus on IRC, he has specific tooling to generate the list of merged pulls 81and sort them into categories based on labels). 82 83Generate list of authors: 84 85 git log --format='- %aN' v(current version, e.g. 0.20.0)..v(new version, e.g. 0.20.1) | sort -fiu 86 87Tag the version (or release candidate) in git: 88 89 git tag -s v(new version, e.g. 0.20.0) 90 91### Setup and perform Gitian builds 92 93If you're using the automated script (found in [contrib/gitian-build.py](/contrib/gitian-build.py)), then at this point you should run it with the "--build" command. Otherwise ignore this. 94 95Setup Gitian descriptors: 96 97 pushd ./bitcoin 98 export SIGNER="(your Gitian key, ie bluematt, sipa, etc)" 99 export VERSION=(new version, e.g. 0.20.0) 100 git fetch 101 git checkout v${VERSION} 102 popd 103 104Ensure your gitian.sigs are up-to-date if you wish to gverify your builds against other Gitian signatures. 105 106 pushd ./gitian.sigs 107 git pull 108 popd 109 110Ensure gitian-builder is up-to-date: 111 112 pushd ./gitian-builder 113 git pull 114 popd 115 116### Fetch and create inputs: (first time, or when dependency versions change) 117 118 pushd ./gitian-builder 119 mkdir -p inputs 120 wget -O inputs/osslsigncode-2.0.tar.gz https://github.com/mtrojnar/osslsigncode/archive/2.0.tar.gz 121 echo '5a60e0a4b3e0b4d655317b2f12a810211c50242138322b16e7e01c6fbb89d92f inputs/osslsigncode-2.0.tar.gz' | sha256sum -c 122 popd 123 124Create the macOS SDK tarball, see the [macdeploy instructions](/contrib/macdeploy/README.md#deterministic-macos-dmg-notes) for details, and copy it into the inputs directory. 125 126### Optional: Seed the Gitian sources cache and offline git repositories 127 128NOTE: Gitian is sometimes unable to download files. If you have errors, try the step below. 129 130By default, Gitian will fetch source files as needed. To cache them ahead of time, make sure you have checked out the tag you want to build in bitcoin, then: 131 132 pushd ./gitian-builder 133 make -C ../bitcoin/depends download SOURCES_PATH=`pwd`/cache/common 134 popd 135 136Only missing files will be fetched, so this is safe to re-run for each build. 137 138NOTE: Offline builds must use the --url flag to ensure Gitian fetches only from local URLs. For example: 139 140 pushd ./gitian-builder 141 ./bin/gbuild --url bitcoin=/path/to/bitcoin,signature=/path/to/sigs {rest of arguments} 142 popd 143 144The gbuild invocations below <b>DO NOT DO THIS</b> by default. 145 146### Build and sign Bitcoin Core for Linux, Windows, and macOS: 147 148 pushd ./gitian-builder 149 ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml 150 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml 151 mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../ 152 153 ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml 154 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml 155 mv build/out/bitcoin-*-win-unsigned.tar.gz inputs/bitcoin-win-unsigned.tar.gz 156 mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../ 157 158 ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml 159 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml 160 mv build/out/bitcoin-*-osx-unsigned.tar.gz inputs/bitcoin-osx-unsigned.tar.gz 161 mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../ 162 popd 163 164Build output expected: 165 166 1. source tarball (`bitcoin-${VERSION}.tar.gz`) 167 2. linux 32-bit and 64-bit dist tarballs (`bitcoin-${VERSION}-linux[32|64].tar.gz`) 168 3. windows 32-bit and 64-bit unsigned installers and dist zips (`bitcoin-${VERSION}-win[32|64]-setup-unsigned.exe`, `bitcoin-${VERSION}-win[32|64].zip`) 169 4. macOS unsigned installer and dist tarball (`bitcoin-${VERSION}-osx-unsigned.dmg`, `bitcoin-${VERSION}-osx64.tar.gz`) 170 5. Gitian signatures (in `gitian.sigs/${VERSION}-<linux|{win,osx}-unsigned>/(your Gitian key)/`) 171 172### Verify other gitian builders signatures to your own. (Optional) 173 174Add other gitian builders keys to your gpg keyring, and/or refresh keys: See `../bitcoin/contrib/gitian-keys/README.md`. 175 176Verify the signatures 177 178 pushd ./gitian-builder 179 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-linux ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml 180 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-win.yml 181 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml 182 popd 183 184### Next steps: 185 186Commit your signature to gitian.sigs: 187 188 pushd gitian.sigs 189 git add ${VERSION}-linux/"${SIGNER}" 190 git add ${VERSION}-win-unsigned/"${SIGNER}" 191 git add ${VERSION}-osx-unsigned/"${SIGNER}" 192 git commit -m "Add ${VERSION} unsigned sigs for ${SIGNER}" 193 git push # Assuming you can push to the gitian.sigs tree 194 popd 195 196Codesigner only: Create Windows/macOS detached signatures: 197- Only one person handles codesigning. Everyone else should skip to the next step. 198- Only once the Windows/macOS builds each have 3 matching signatures may they be signed with their respective release keys. 199 200Codesigner only: Sign the macOS binary: 201 202 transfer bitcoin-osx-unsigned.tar.gz to macOS for signing 203 tar xf bitcoin-osx-unsigned.tar.gz 204 ./detached-sig-create.sh -s "Key ID" 205 Enter the keychain password and authorize the signature 206 Move signature-osx.tar.gz back to the gitian host 207 208Codesigner only: Sign the windows binaries: 209 210 tar xf bitcoin-win-unsigned.tar.gz 211 ./detached-sig-create.sh -key /path/to/codesign.key 212 Enter the passphrase for the key when prompted 213 signature-win.tar.gz will be created 214 215Codesigner only: Commit the detached codesign payloads: 216 217 cd ~/bitcoin-detached-sigs 218 checkout the appropriate branch for this release series 219 rm -rf * 220 tar xf signature-osx.tar.gz 221 tar xf signature-win.tar.gz 222 git add -A 223 git commit -m "point to ${VERSION}" 224 git tag -s v${VERSION} HEAD 225 git push the current branch and new tag 226 227Non-codesigners: wait for Windows/macOS detached signatures: 228 229- Once the Windows/macOS builds each have 3 matching signatures, they will be signed with their respective release keys. 230- 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. 231 232Create (and optionally verify) the signed macOS binary: 233 234 pushd ./gitian-builder 235 ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml 236 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml 237 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-signed ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml 238 mv build/out/bitcoin-osx-signed.dmg ../bitcoin-${VERSION}-osx.dmg 239 popd 240 241Create (and optionally verify) the signed Windows binaries: 242 243 pushd ./gitian-builder 244 ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml 245 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml 246 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-signed ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml 247 mv build/out/bitcoin-*win64-setup.exe ../bitcoin-${VERSION}-win64-setup.exe 248 popd 249 250Commit your signature for the signed macOS/Windows binaries: 251 252 pushd gitian.sigs 253 git add ${VERSION}-osx-signed/"${SIGNER}" 254 git add ${VERSION}-win-signed/"${SIGNER}" 255 git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures" 256 git push # Assuming you can push to the gitian.sigs tree 257 popd 258 259### After 3 or more people have gitian-built and their results match: 260 261- Create `SHA256SUMS.asc` for the builds, and GPG-sign it: 262 263```bash 264sha256sum * > SHA256SUMS 265``` 266 267The list of files should be: 268``` 269bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz 270bitcoin-${VERSION}-arm-linux-gnueabihf.tar.gz 271bitcoin-${VERSION}-riscv64-linux-gnu.tar.gz 272bitcoin-${VERSION}-x86_64-linux-gnu.tar.gz 273bitcoin-${VERSION}-osx64.tar.gz 274bitcoin-${VERSION}-osx.dmg 275bitcoin-${VERSION}.tar.gz 276bitcoin-${VERSION}-win64-setup.exe 277bitcoin-${VERSION}-win64.zip 278``` 279The `*-debug*` files generated by the gitian build contain debug symbols 280for troubleshooting by developers. It is assumed that anyone that is interested 281in debugging can run gitian to generate the files for themselves. To avoid 282end-user confusion about which file to pick, as well as save storage 283space *do not upload these to the bitcoin.org server, nor put them in the torrent*. 284 285- GPG-sign it, delete the unsigned file: 286``` 287gpg --digest-algo sha256 --clearsign SHA256SUMS # outputs SHA256SUMS.asc 288rm SHA256SUMS 289``` 290(the digest algorithm is forced to sha256 to avoid confusion of the `Hash:` header that GPG adds with the SHA256 used for the files) 291Note: check that SHA256SUMS itself doesn't end up in SHA256SUMS, which is a spurious/nonsensical entry. 292 293- Upload zips and installers, as well as `SHA256SUMS.asc` from last step, to the bitcoin.org server 294 into `/var/www/bin/bitcoin-core-${VERSION}` 295 296- A `.torrent` will appear in the directory after a few minutes. Optionally help seed this torrent. To get the `magnet:` URI use: 297```bash 298transmission-show -m <torrent file> 299``` 300Insert the magnet URI into the announcement sent to mailing lists. This permits 301people without access to `bitcoin.org` to download the binary distribution. 302Also put it into the `optional_magnetlink:` slot in the YAML file for 303bitcoin.org (see below for bitcoin.org update instructions). 304 305- Update bitcoin.org version 306 307 - First, check to see if the Bitcoin.org maintainers have prepared a 308 release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Core 309 310 - If they have, it will have previously failed their Travis CI 311 checks because the final release files weren't uploaded. 312 Trigger a Travis CI rebuild---if it passes, merge. 313 314 - If they have not prepared a release, follow the Bitcoin.org release 315 instructions: https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md#release-notes 316 317 - After the pull request is merged, the website will automatically show the newest version within 15 minutes, as well 318 as update the OS download links. 319 320- Update other repositories and websites for new version 321 322 - bitcoincore.org blog post 323 324 - bitcoincore.org maintained versions update: 325 [table](https://github.com/bitcoin-core/bitcoincore.org/commits/master/_includes/posts/maintenance-table.md) 326 327 - bitcoincore.org RPC documentation update 328 329 - Update packaging repo 330 331 - Push the flatpak to flathub, e.g. https://github.com/flathub/org.bitcoincore.bitcoin-qt/pull/2 332 333 - Push the latest version to master (if applicable), e.g. https://github.com/bitcoin-core/packaging/pull/32 334 335 - Create a new branch for the major release "0.xx" from master (used to build the snap package) and request the 336 track (if applicable), e.g. https://forum.snapcraft.io/t/track-request-for-bitcoin-core-snap/10112/7 337 338 - Notify MarcoFalke so that he can start building the snap package 339 340 - https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging (Click "Import Now" to fetch the branch) 341 - https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging/+ref/0.xx (Click "Create snap package") 342 - Name it "bitcoin-core-snap-0.xx" 343 - Leave owner and series as-is 344 - Select architectures that are compiled via gitian 345 - Leave "automatically build when branch changes" unticked 346 - Tick "automatically upload to store" 347 - Put "bitcoin-core" in the registered store package name field 348 - Tick the "edge" box 349 - Put "0.xx" in the track field 350 - Click "create snap package" 351 - Click "Request builds" for every new release on this branch (after updating the snapcraft.yml in the branch to reflect the latest gitian results) 352 - Promote release on https://snapcraft.io/bitcoin-core/releases if it passes sanity checks 353 354 - This repo 355 356 - Archive the release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) 357 358 - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes 359 360- Announce the release: 361 362 - bitcoin-dev and bitcoin-core-dev mailing list 363 364 - Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/ 365 366 - Update title of #bitcoin on Freenode IRC 367 368 - Optionally twitter, reddit /r/Bitcoin, ... but this will usually sort out itself 369 370 - Celebrate 371 372### Additional information 373 374#### How to calculate `m_assumed_blockchain_size` and `m_assumed_chain_state_size` 375 376Both variables are used as a guideline for how much space the user needs on their drive in total, not just strictly for the blockchain. 377Note 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. 378 379To calculate `m_assumed_blockchain_size`: 380- For `mainnet` -> Take the size of the data directory, excluding `/regtest` and `/testnet3` directories. 381- For `testnet` -> Take the size of the `/testnet3` directory. 382 383 384To calculate `m_assumed_chain_state_size`: 385- For `mainnet` -> Take the size of the `/chainstate` directory. 386- For `testnet` -> Take the size of the `/testnet3/chainstate` directory. 387 388Notes: 389- 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. 390- 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. 391