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