1Release Process 2==================== 3 4## Branch updates 5 6### Before every release candidate 7 8* Update manpages, see [gen-manpages.sh](https://github.com/namecoin/namecoin/blob/master/contrib/devtools/README.md#gen-manpagessh). 9* ( **Not in Namecoin yet.** ) Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). 10* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`). 11 12### Before every major and minor release 13 14* ( **Not in Namecoin yet.** ) 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-assumed-blockchain-and-chain-state-size) for information on how to calculate them). 31* Update [`src/chainparams.cpp`](/src/chainparams.cpp) chainTxData with statistics about the transaction count and rate. Use the output of the `getchaintxstats` RPC, see 32 [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. 33* Update `src/chainparams.cpp` nMinimumChainWork and defaultAssumeValid (and the block height comment) with information from the `getblockheader` (and `getblockhash`) RPCs. 34 - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip. 35 - Testnet should be set some tens of thousands back from the tip due to reorgs there. 36 - This update should be reviewed with a reindex-chainstate with assumevalid=0 to catch any defect 37 that causes rejection of blocks in the past history. 38- Clear the release notes and move them to the wiki (see "Write the release notes" below). 39 40#### After branch-off (on master) 41 42- Update the version of `contrib/gitian-descriptors/*.yml`. 43 44#### After branch-off (on the major release branch) 45 46- Update the versions. 47- 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. 48 49#### Before final release 50 51- Merge the release notes from the wiki into the branch. 52- Ensure the "Needs release note" label is removed from all relevant pull requests and issues. 53 54 55## Building 56 57### First time / New builders 58 59If 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. 60 61Check out the source code in the following directory hierarchy. 62 63 cd /path/to/your/toplevel/build 64 git clone https://github.com/namecoin/gitian.sigs.git 65 #git clone https://github.com/namecoin/namecoin-detached-sigs.git # Namecoin doesn't use detached sigs yet, so don't do this. 66 git clone https://github.com/devrandom/gitian-builder.git 67 git clone https://github.com/namecoin/namecoin-core.git 68 69### Write the release notes 70 71Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki. 72 73( **Not in Namecoin yet.** ) 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 nc(current version, e.g. 0.19.2)..nc(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' nc(current version, e.g. 0.20.0)..nc(new version, e.g. 0.20.1) | sort -fiu 86 87Tag the version (or release candidate) in git: 88 89 git tag -s nc(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 ./namecoin-core 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 nc${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 ../namecoin-core/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 namecoin=/path/to/namecoin,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 Namecoin Core for Linux, Windows, and macOS: 147 148 pushd ./gitian-builder 149 ./bin/gbuild --num-make 2 --memory 3000 --commit namecoin=nc${VERSION} ../namecoin-core/contrib/gitian-descriptors/gitian-linux.yml 150 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-linux --destination ../gitian.sigs/ ../namecoin-core/contrib/gitian-descriptors/gitian-linux.yml 151 mv build/out/namecoin-*.tar.gz build/out/src/namecoin-*.tar.gz ../ 152 153 ./bin/gbuild --num-make 2 --memory 3000 --commit namecoin=nc${VERSION} ../namecoin-core/contrib/gitian-descriptors/gitian-win.yml 154 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-unsigned --destination ../gitian.sigs/ ../namecoin-core/contrib/gitian-descriptors/gitian-win.yml 155 mv build/out/namecoin-*-win-unsigned.tar.gz inputs/namecoin-win-unsigned.tar.gz 156 mv build/out/namecoin-*.zip build/out/namecoin-*.exe ../ 157 158 ./bin/gbuild --num-make 2 --memory 3000 --commit namecoin=nc${VERSION} ../namecoin-core/contrib/gitian-descriptors/gitian-osx.yml 159 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../namecoin-core/contrib/gitian-descriptors/gitian-osx.yml 160 mv build/out/namecoin-*-osx-unsigned.tar.gz inputs/namecoin-osx-unsigned.tar.gz 161 mv build/out/namecoin-*.tar.gz build/out/namecoin-*.dmg ../ 162 popd 163 164Build output expected: 165 166 1. source tarball (`namecoin-${VERSION}.tar.gz`) 167 2. linux 32-bit and 64-bit dist tarballs (`namecoin-${VERSION}-linux[32|64].tar.gz`) 168 3. windows 32-bit and 64-bit unsigned installers and dist zips (`namecoin-${VERSION}-win[32|64]-setup-unsigned.exe`, `namecoin-${VERSION}-win[32|64].zip`) 169 4. macOS unsigned installer and dist tarball (`namecoin-${VERSION}-osx-unsigned.dmg`, `namecoin-${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 `../namecoin/contrib/gitian-keys/README.md`. 175 176Verify the signatures 177 178 pushd ./gitian-builder 179 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-linux ../namecoin-core/contrib/gitian-descriptors/gitian-linux.yml 180 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-unsigned ../namecoin-core/contrib/gitian-descriptors/gitian-win.yml 181 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-unsigned ../namecoin-core/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 196( **Not in Namecoin yet.** ) 197 198Codesigner only: Create Windows/macOS detached signatures: 199- Only one person handles codesigning. Everyone else should skip to the next step. 200- Only once the Windows/macOS builds each have 3 matching signatures may they be signed with their respective release keys. 201 202Codesigner only: Sign the macOS binary: 203 204 transfer bitcoin-osx-unsigned.tar.gz to macOS for signing 205 tar xf bitcoin-osx-unsigned.tar.gz 206 ./detached-sig-create.sh -s "Key ID" 207 Enter the keychain password and authorize the signature 208 Move signature-osx.tar.gz back to the gitian host 209 210Codesigner only: Sign the windows binaries: 211 212 tar xf bitcoin-win-unsigned.tar.gz 213 ./detached-sig-create.sh -key /path/to/codesign.key 214 Enter the passphrase for the key when prompted 215 signature-win.tar.gz will be created 216 217Codesigner only: Commit the detached codesign payloads: 218 219 cd ~/bitcoin-detached-sigs 220 checkout the appropriate branch for this release series 221 rm -rf * 222 tar xf signature-osx.tar.gz 223 tar xf signature-win.tar.gz 224 git add -A 225 git commit -m "point to ${VERSION}" 226 git tag -s nc${VERSION} HEAD 227 git push the current branch and new tag 228 229Non-codesigners: wait for Windows/macOS detached signatures: 230 231- Once the Windows/macOS builds each have 3 matching signatures, they will be signed with their respective release keys. 232- Detached signatures will then be committed to the [namecoin-detached-sigs](https://github.com/namecoin/namecoin-detached-sigs) repository, which can be combined with the unsigned apps to create signed binaries. 233 234( **Not in Namecoin yet.** ) Create (and optionally verify) the signed macOS binary: 235 236 pushd ./gitian-builder 237 ./bin/gbuild -i --commit signature=nc${VERSION} ../namecoin-core/contrib/gitian-descriptors/gitian-osx-signer.yml 238 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../namecoin-core/contrib/gitian-descriptors/gitian-osx-signer.yml 239 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-signed ../namecoin-core/contrib/gitian-descriptors/gitian-osx-signer.yml 240 mv build/out/namecoin-osx-signed.dmg ../namecoin-${VERSION}-osx.dmg 241 popd 242 243( **Not in Namecoin yet.** ) Create (and optionally verify) the signed Windows binaries: 244 245 pushd ./gitian-builder 246 ./bin/gbuild -i --commit signature=nc${VERSION} ../namecoin-core/contrib/gitian-descriptors/gitian-win-signer.yml 247 ./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-signed --destination ../gitian.sigs/ ../namecoin-core/contrib/gitian-descriptors/gitian-win-signer.yml 248 ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-signed ../namecoin-core/contrib/gitian-descriptors/gitian-win-signer.yml 249 mv build/out/namecoin-*win64-setup.exe ../namecoin-${VERSION}-win64-setup.exe 250 popd 251 252( **Not in Namecoin yet.** ) Commit your signature for the signed macOS/Windows binaries: 253 254 pushd gitian.sigs 255 git add ${VERSION}-osx-signed/"${SIGNER}" 256 git add ${VERSION}-win-signed/"${SIGNER}" 257 git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures" 258 git push # Assuming you can push to the gitian.sigs tree 259 popd 260 261### After 3 or more people have gitian-built and their results match: 262 263- Create `SHA256SUMS.asc` for the builds, and GPG-sign it: 264 265```bash 266sha256sum * > SHA256SUMS 267``` 268 269The list of files should be: 270``` 271namecoin-${VERSION}-aarch64-linux-gnu.tar.gz 272namecoin-${VERSION}-arm-linux-gnueabihf.tar.gz 273namecoin-${VERSION}-riscv64-linux-gnu.tar.gz 274namecoin-${VERSION}-x86_64-linux-gnu.tar.gz 275namecoin-${VERSION}-osx64.tar.gz 276namecoin-${VERSION}-osx.dmg 277namecoin-${VERSION}.tar.gz 278namecoin-${VERSION}-win64-setup.exe 279namecoin-${VERSION}-win64.zip 280``` 281The `*-debug*` files generated by the gitian build contain debug symbols 282for troubleshooting by developers. It is assumed that anyone that is interested 283in debugging can run gitian to generate the files for themselves. To avoid 284end-user confusion about which file to pick, as well as save storage 285space *do not upload these to the bitcoin.org server, nor put them in the torrent*. 286 287- GPG-sign it, delete the unsigned file: 288``` 289gpg --digest-algo sha256 --clearsign SHA256SUMS # outputs SHA256SUMS.asc 290rm SHA256SUMS 291``` 292(the digest algorithm is forced to sha256 to avoid confusion of the `Hash:` header that GPG adds with the SHA256 used for the files) 293Note: check that SHA256SUMS itself doesn't end up in SHA256SUMS, which is a spurious/nonsensical entry. 294 295( **The following is not in Namecoin yet.** ) 296 297- Upload zips and installers, as well as `SHA256SUMS.asc` from last step, to the bitcoin.org server 298 into `/var/www/bin/bitcoin-core-${VERSION}` 299 300- A `.torrent` will appear in the directory after a few minutes. Optionally help seed this torrent. To get the `magnet:` URI use: 301```bash 302transmission-show -m <torrent file> 303``` 304Insert the magnet URI into the announcement sent to mailing lists. This permits 305people without access to `bitcoin.org` to download the binary distribution. 306Also put it into the `optional_magnetlink:` slot in the YAML file for 307bitcoin.org (see below for bitcoin.org update instructions). 308 309- Update bitcoin.org version 310 311 - First, check to see if the Bitcoin.org maintainers have prepared a 312 release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Core 313 314 - If they have, it will have previously failed their Travis CI 315 checks because the final release files weren't uploaded. 316 Trigger a Travis CI rebuild---if it passes, merge. 317 318 - If they have not prepared a release, follow the Bitcoin.org release 319 instructions: https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md#release-notes 320 321 - After the pull request is merged, the website will automatically show the newest version within 15 minutes, as well 322 as update the OS download links. 323 324- Update other repositories and websites for new version 325 326 - bitcoincore.org blog post 327 328 - bitcoincore.org maintained versions update: 329 [table](https://github.com/bitcoin-core/bitcoincore.org/commits/master/_includes/posts/maintenance-table.md) 330 331 - bitcoincore.org RPC documentation update 332 333 - Update packaging repo 334 335 - Push the flatpak to flathub, e.g. https://github.com/flathub/org.bitcoincore.bitcoin-qt/pull/2 336 337 - Push the latest version to master (if applicable), e.g. https://github.com/bitcoin-core/packaging/pull/32 338 339 - Create a new branch for the major release "0.xx" from master (used to build the snap package) and request the 340 track (if applicable), e.g. https://forum.snapcraft.io/t/track-request-for-bitcoin-core-snap/10112/7 341 342 - Notify MarcoFalke so that he can start building the snap package 343 344 - https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging (Click "Import Now" to fetch the branch) 345 - https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging/+ref/0.xx (Click "Create snap package") 346 - Name it "bitcoin-core-snap-0.xx" 347 - Leave owner and series as-is 348 - Select architectures that are compiled via gitian 349 - Leave "automatically build when branch changes" unticked 350 - Tick "automatically upload to store" 351 - Put "bitcoin-core" in the registered store package name field 352 - Tick the "edge" box 353 - Put "0.xx" in the track field 354 - Click "create snap package" 355 - Click "Request builds" for every new release on this branch (after updating the snapcraft.yml in the branch to reflect the latest gitian results) 356 - Promote release on https://snapcraft.io/bitcoin-core/releases if it passes sanity checks 357 358 - This repo 359 360 - Archive the release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) 361 362 - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes 363 364- Announce the release: 365 366 - bitcoin-dev and bitcoin-core-dev mailing list 367 368 - Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/ 369 370 - Update title of #bitcoin on Freenode IRC 371 372 - Optionally twitter, reddit /r/Bitcoin, ... but this will usually sort out itself 373 374 - Celebrate 375 376### Additional information 377 378#### <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` 379 380Both variables are used as a guideline for how much space the user needs on their drive in total, not just strictly for the blockchain. 381Note 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. 382 383To calculate `m_assumed_blockchain_size`: 384- For `mainnet` -> Take the size of the data directory, excluding `/regtest` and `/testnet3` directories. 385- For `testnet` -> Take the size of the `/testnet3` directory. 386 387 388To calculate `m_assumed_chain_state_size`: 389- For `mainnet` -> Take the size of the `/chainstate` directory. 390- For `testnet` -> Take the size of the `/testnet3/chainstate` directory. 391 392Notes: 393- 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. 394- 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. 395