doc/release-process.md

   1 Release Process
   2 ====================
   3
   4 Before every release candidate:
   5
   6 * Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations).
   7
   8 * Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
   9
  10 Before every minor and major release:
  11
  12 * Update [bips.md](bips.md) to account for changes since the last release.
  13 * Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_IS_RELEASE` to `true`)
  14 * Write release notes (see below)
  15 * Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc.
  16 * Update `src/chainparams.cpp` defaultAssumeValid  with information from the getblockhash rpc.
  17   - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip.
  18   - Testnet should be set some tens of thousands back from the tip due to reorgs there.
  19   - This update should be reviewed with a reindex-chainstate with assumevalid=0 to catch any defect
  20      that causes rejection of blocks in the past history.
  21
  22 Before every major release:
  23
  24 * Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/7415) for an example.
  25 * Update [`BLOCK_CHAIN_SIZE`](/src/qt/intro.cpp) to the current size plus some overhead.
  26 * Update `src/chainparams.cpp` chainTxData with statistics about the transaction count and rate.
  27 * Update version of `contrib/gitian-descriptors/*.yml`: usually one'd want to do this on master after branching off the release - but be sure to at least do it before a new major release
  28
  29 ### First time / New builders
  30
  31 If you're using the automated script (found in [contrib/gitian-build.sh](/contrib/gitian-build.sh)), then at this point you should run it with the "--setup" command. Otherwise ignore this.
  32
  33 Check out the source code in the following directory hierarchy.
  34
  35     cd /path/to/your/toplevel/build
  36     git clone https://github.com/bitcoin-core/gitian.sigs.git
  37     git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git
  38     git clone https://github.com/devrandom/gitian-builder.git
  39     git clone https://github.com/bitcoin/bitcoin.git
  40
  41 ### Bitcoin maintainers/release engineers, suggestion for writing release notes
  42
  43 Write release notes. git shortlog helps a lot, for example:
  44
  45     git shortlog --no-merges v(current version, e.g. 0.7.2)..v(new version, e.g. 0.8.0)
  46
  47 (or ping @wumpus on IRC, he has specific tooling to generate the list of merged pulls
  48 and sort them into categories based on labels)
  49
  50 Generate list of authors:
  51
  52     git log --format='%aN' "$*" | sort -ui | sed -e 's/^/- /'
  53
  54 Tag version (or release candidate) in git
  55
  56     git tag -s v(new version, e.g. 0.8.0)
  57
  58 ### Setup and perform Gitian builds
  59
  60 If you're using the automated script (found in [contrib/gitian-build.sh](/contrib/gitian-build.sh)), then at this point you should run it with the "--build" command. Otherwise ignore this.
  61
  62 Setup Gitian descriptors:
  63
  64     pushd ./bitcoin
  65     export SIGNER=(your Gitian key, ie bluematt, sipa, etc)
  66     export VERSION=(new version, e.g. 0.8.0)
  67     git fetch
  68     git checkout v${VERSION}
  69     popd
  70
  71 Ensure your gitian.sigs are up-to-date if you wish to gverify your builds against other Gitian signatures.
  72
  73     pushd ./gitian.sigs
  74     git pull
  75     popd
  76
  77 Ensure gitian-builder is up-to-date:
  78
  79     pushd ./gitian-builder
  80     git pull
  81     popd
  82
  83 ### Fetch and create inputs: (first time, or when dependency versions change)
  84
  85     pushd ./gitian-builder
  86     mkdir -p inputs
  87     wget -P inputs https://bitcoincore.org/cfields/osslsigncode-Backports-to-1.7.1.patch
  88     wget -P inputs http://downloads.sourceforge.net/project/osslsigncode/osslsigncode/osslsigncode-1.7.1.tar.gz
  89     popd
  90
  91 Create the OS X SDK tarball, see the [OS X readme](README_osx.md) for details, and copy it into the inputs directory.
  92
  93 ### Optional: Seed the Gitian sources cache and offline git repositories
  94
  95 By default, Gitian will fetch source files as needed. To cache them ahead of time:
  96
  97     pushd ./gitian-builder
  98     make -C ../bitcoin/depends download SOURCES_PATH=`pwd`/cache/common
  99     popd
 100
 101 Only missing files will be fetched, so this is safe to re-run for each build.
 102
 103 NOTE: Offline builds must use the --url flag to ensure Gitian fetches only from local URLs. For example:
 104
 105     pushd ./gitian-builder
 106     ./bin/gbuild --url bitcoin=/path/to/bitcoin,signature=/path/to/sigs {rest of arguments}
 107     popd
 108
 109 The gbuild invocations below <b>DO NOT DO THIS</b> by default.
 110
 111 ### Build and sign Bitcoin Core for Linux, Windows, and OS X:
 112
 113     pushd ./gitian-builder
 114     ./bin/gbuild --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
 115     ./bin/gsign --signer $SIGNER --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
 116     mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../
 117
 118     ./bin/gbuild --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml
 119     ./bin/gsign --signer $SIGNER --release ${VERSION}-win-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml
 120     mv build/out/bitcoin-*-win-unsigned.tar.gz inputs/bitcoin-win-unsigned.tar.gz
 121     mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../
 122
 123     ./bin/gbuild --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml
 124     ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml
 125     mv build/out/bitcoin-*-osx-unsigned.tar.gz inputs/bitcoin-osx-unsigned.tar.gz
 126     mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../
 127     popd
 128
 129 Build output expected:
 130
 131   1. source tarball (`bitcoin-${VERSION}.tar.gz`)
 132   2. linux 32-bit and 64-bit dist tarballs (`bitcoin-${VERSION}-linux[32|64].tar.gz`)
 133   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`)
 134   4. OS X unsigned installer and dist tarball (`bitcoin-${VERSION}-osx-unsigned.dmg`, `bitcoin-${VERSION}-osx64.tar.gz`)
 135   5. Gitian signatures (in `gitian.sigs/${VERSION}-<linux|{win,osx}-unsigned>/(your Gitian key)/`)
 136
 137 ### Verify other gitian builders signatures to your own. (Optional)
 138
 139 Add other gitian builders keys to your gpg keyring, and/or refresh keys.
 140
 141     gpg --import bitcoin/contrib/gitian-keys/*.pgp
 142     gpg --refresh-keys
 143
 144 Verify the signatures
 145
 146     pushd ./gitian-builder
 147     ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-linux ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
 148     ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-win.yml
 149     ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml
 150     popd
 151
 152 ### Next steps:
 153
 154 Commit your signature to gitian.sigs:
 155
 156     pushd gitian.sigs
 157     git add ${VERSION}-linux/${SIGNER}
 158     git add ${VERSION}-win-unsigned/${SIGNER}
 159     git add ${VERSION}-osx-unsigned/${SIGNER}
 160     git commit -a
 161     git push  # Assuming you can push to the gitian.sigs tree
 162     popd
 163
 164 Codesigner only: Create Windows/OS X detached signatures:
 165 - Only one person handles codesigning. Everyone else should skip to the next step.
 166 - Only once the Windows/OS X builds each have 3 matching signatures may they be signed with their respective release keys.
 167
 168 Codesigner only: Sign the osx binary:
 169
 170     transfer bitcoin-osx-unsigned.tar.gz to osx for signing
 171     tar xf bitcoin-osx-unsigned.tar.gz
 172     ./detached-sig-create.sh -s "Key ID"
 173     Enter the keychain password and authorize the signature
 174     Move signature-osx.tar.gz back to the gitian host
 175
 176 Codesigner only: Sign the windows binaries:
 177
 178     tar xf bitcoin-win-unsigned.tar.gz
 179     ./detached-sig-create.sh -key /path/to/codesign.key
 180     Enter the passphrase for the key when prompted
 181     signature-win.tar.gz will be created
 182
 183 Codesigner only: Commit the detached codesign payloads:
 184
 185     cd ~/bitcoin-detached-sigs
 186     checkout the appropriate branch for this release series
 187     rm -rf *
 188     tar xf signature-osx.tar.gz
 189     tar xf signature-win.tar.gz
 190     git add -a
 191     git commit -m "point to ${VERSION}"
 192     git tag -s v${VERSION} HEAD
 193     git push the current branch and new tag
 194
 195 Non-codesigners: wait for Windows/OS X detached signatures:
 196
 197 - Once the Windows/OS X builds each have 3 matching signatures, they will be signed with their respective release keys.
 198 - 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.
 199
 200 Create (and optionally verify) the signed OS X binary:
 201
 202     pushd ./gitian-builder
 203     ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml
 204     ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml
 205     ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-signed ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml
 206     mv build/out/bitcoin-osx-signed.dmg ../bitcoin-${VERSION}-osx.dmg
 207     popd
 208
 209 Create (and optionally verify) the signed Windows binaries:
 210
 211     pushd ./gitian-builder
 212     ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml
 213     ./bin/gsign --signer $SIGNER --release ${VERSION}-win-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml
 214     ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-signed ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml
 215     mv build/out/bitcoin-*win64-setup.exe ../bitcoin-${VERSION}-win64-setup.exe
 216     mv build/out/bitcoin-*win32-setup.exe ../bitcoin-${VERSION}-win32-setup.exe
 217     popd
 218
 219 Commit your signature for the signed OS X/Windows binaries:
 220
 221     pushd gitian.sigs
 222     git add ${VERSION}-osx-signed/${SIGNER}
 223     git add ${VERSION}-win-signed/${SIGNER}
 224     git commit -a
 225     git push  # Assuming you can push to the gitian.sigs tree
 226     popd
 227
 228 ### After 3 or more people have gitian-built and their results match:
 229
 230 - Create `SHA256SUMS.asc` for the builds, and GPG-sign it:
 231
 232 ```bash
 233 sha256sum * > SHA256SUMS
 234 ```
 235
 236 The list of files should be:
 237 ```
 238 bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz
 239 bitcoin-${VERSION}-arm-linux-gnueabihf.tar.gz
 240 bitcoin-${VERSION}-i686-pc-linux-gnu.tar.gz
 241 bitcoin-${VERSION}-x86_64-linux-gnu.tar.gz
 242 bitcoin-${VERSION}-osx64.tar.gz
 243 bitcoin-${VERSION}-osx.dmg
 244 bitcoin-${VERSION}.tar.gz
 245 bitcoin-${VERSION}-win32-setup.exe
 246 bitcoin-${VERSION}-win32.zip
 247 bitcoin-${VERSION}-win64-setup.exe
 248 bitcoin-${VERSION}-win64.zip
 249 ```
 250 The `*-debug*` files generated by the gitian build contain debug symbols
 251 for troubleshooting by developers. It is assumed that anyone that is interested
 252 in debugging can run gitian to generate the files for themselves. To avoid
 253 end-user confusion about which file to pick, as well as save storage
 254 space *do not upload these to the bitcoin.org server, nor put them in the torrent*.
 255
 256 - GPG-sign it, delete the unsigned file:
 257 ```
 258 gpg --digest-algo sha256 --clearsign SHA256SUMS # outputs SHA256SUMS.asc
 259 rm SHA256SUMS
 260 ```
 261 (the digest algorithm is forced to sha256 to avoid confusion of the `Hash:` header that GPG adds with the SHA256 used for the files)
 262 Note: check that SHA256SUMS itself doesn't end up in SHA256SUMS, which is a spurious/nonsensical entry.
 263
 264 - Upload zips and installers, as well as `SHA256SUMS.asc` from last step, to the bitcoin.org server
 265   into `/var/www/bin/bitcoin-core-${VERSION}`
 266
 267 - A `.torrent` will appear in the directory after a few minutes. Optionally help seed this torrent. To get the `magnet:` URI use:
 268 ```bash
 269 transmission-show -m <torrent file>
 270 ```
 271 Insert the magnet URI into the announcement sent to mailing lists. This permits
 272 people without access to `bitcoin.org` to download the binary distribution.
 273 Also put it into the `optional_magnetlink:` slot in the YAML file for
 274 bitcoin.org (see below for bitcoin.org update instructions).
 275
 276 - Update bitcoin.org version
 277
 278   - First, check to see if the Bitcoin.org maintainers have prepared a
 279     release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Releases
 280
 281       - If they have, it will have previously failed their Travis CI
 282         checks because the final release files weren't uploaded.
 283         Trigger a Travis CI rebuild---if it passes, merge.
 284
 285   - If they have not prepared a release, follow the Bitcoin.org release
 286     instructions: https://github.com/bitcoin-dot-org/bitcoin.org#release-notes
 287
 288   - After the pull request is merged, the website will automatically show the newest version within 15 minutes, as well
 289     as update the OS download links. Ping @saivann/@harding (saivann/harding on Freenode) in case anything goes wrong
 290
 291 - Announce the release:
 292
 293   - bitcoin-dev and bitcoin-core-dev mailing list
 294
 295   - Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/
 296
 297   - bitcoincore.org blog post
 298
 299   - Update title of #bitcoin on Freenode IRC
 300
 301   - Optionally twitter, reddit /r/Bitcoin, ... but this will usually sort out itself
 302
 303   - Notify BlueMatt so that he can start building [the PPAs](https://launchpad.net/~bitcoin/+archive/ubuntu/bitcoin)
 304
 305   - Archive release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release)
 306
 307   - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes.
 308
 309   - Celebrate