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