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