- Update translations see translation_process.md.
- Update release candidate version in
configure.ac
(CLIENT_VERSION_RC
). - Update manpages (after rebuilding the binaries), see gen-manpages.py.
- Update bitcoin.conf and commit, see gen-bitcoin-conf.sh.
- Update bips.md to account for changes since the last release.
- Update version in
configure.ac
(don't forget to setCLIENT_VERSION_RC
to0
). - Update manpages (see previous section)
- Write release notes (see "Write the release notes" below).
- On both the master branch and the new release branch:
- update
CLIENT_VERSION_MAJOR
inconfigure.ac
- update
- On the new release branch in
configure.ac
(see this commit):- set
CLIENT_VERSION_MINOR
to0
- set
CLIENT_VERSION_BUILD
to0
- set
CLIENT_VERSION_IS_RELEASE
totrue
- set
- Update hardcoded seeds, see this pull request for an example.
- Update the following variables in
src/kernel/chainparams.cpp
for mainnet, testnet, and signet:m_assumed_blockchain_size
andm_assumed_chain_state_size
with the current size plus some overhead (see this for information on how to calculate them).- The following updates should be reviewed with
reindex-chainstate
andassumevalid=0
to catch any defect that causes rejection of blocks in the past history. chainTxData
with statistics about the transaction count and rate. Use the output of thegetchaintxstats
RPC with annBlocks
of 4096 (28 days) and abestblockhash
of RPCgetbestblockhash
; see this pull request for an example. Reviewers can verify the results by runninggetchaintxstats <window_block_count> <window_final_block_hash>
with thewindow_block_count
andwindow_final_block_hash
from your output.defaultAssumeValid
with the output of RPCgetblockhash
using theheight
ofwindow_final_block_height
above (and update the block height comment with that height), taking into account the following:- On mainnet, the selected value must not be orphaned, so it may be useful to set the height two blocks back from the tip.
- Testnet should be set with a height some tens of thousands back from the tip, due to reorgs there.
nMinimumChainWork
with the "chainwork" value of RPCgetblockheader
using the same height as that selected for the previous step.
- Consider updating the headers synchronization tuning parameters to account for the chainparams updates.
The optimal values change very slowly, so this isn't strictly necessary every release, but doing so doesn't hurt.
- Update configuration variables in
contrib/devtools/headerssync-params.py
:- Set
TIME
to the software's expected supported lifetime -- after this time, its ability to defend against a high bandwidth timewarp attacker will begin to degrade. - Set
MINCHAINWORK_HEADERS
to the height used for thenMinimumChainWork
calculation above. - Check that the other variables still look reasonable.
- Set
- Run the script. It works fine in CPython, but PyPy is much faster (seconds instead of minutes):
pypy3 contrib/devtools/headerssync-params.py
. - Paste the output defining
HEADER_COMMITMENT_PERIOD
andREDOWNLOAD_BUFFER_SIZE
into the top ofsrc/headerssync.cpp
.
- Update configuration variables in
- Clear the release notes and move them to the wiki (see "Write the release notes" below).
- Translations on Transifex:
- Pull translations from Transifex into the master branch.
- Create a new resource named after the major version with the slug
qt-translation-<RRR>x
, whereRRR
is the major branch number padded with zeros. Usesrc/qt/locale/bitcoin_en.xlf
to create it. - In the project workflow settings, ensure that Translation Memory Fill-up is enabled and that Translation Memory Context Matching is disabled.
- Update the Transifex slug in
.tx/config
to the slug of the resource created in the first step. This identifies which resource the translations will be synchronized from. - Make an announcement that translators can start translating for the new version. You can use one of the previous announcements as a template.
- Change the auto-update URL for the resource to
master
, e.g.https://raw.githubusercontent.com/bitcoin/bitcoin/master/src/qt/locale/bitcoin_en.xlf
. (Do this only after the previous steps, to prevent an auto-update from interfering.)
- Update the versions.
- Create the draft, named "version Release Notes Draft", as a collaborative wiki.
- Clear the release notes:
cp doc/release-notes-empty-template.md doc/release-notes.md
- Create a pinned meta-issue for testing the release candidate (see this issue for an example) and provide a link to it in the release announcements where useful.
- Translations on Transifex
- Change the auto-update URL for the new major version's resource away from
master
and to the branch, e.g.https://raw.githubusercontent.com/bitcoin/bitcoin/<branch>/src/qt/locale/bitcoin_en.xlf
. Do not forget this or it will keep tracking the translations on master instead, drifting away from the specific major release.
- Change the auto-update URL for the new major version's resource away from
- Prune inputs from the qa-assets repo (See pruning inputs).
- Merge the release notes from the wiki into the branch.
- Ensure the "Needs release note" label is removed from all relevant pull requests and issues.
To tag the version (or release candidate) in git, use the make-tag.py
script from bitcoin-maintainer-tools. From the root of the repository run:
../bitcoin-maintainer-tools/make-tag.py v(new version, e.g. 25.0)
This will perform a few last-minute consistency checks in the build system files, and if they pass, create a signed tag.
Install Guix using one of the installation methods detailed in contrib/guix/INSTALL.md.
Check out the source code in the following directory hierarchy.
cd /path/to/your/toplevel/build
git clone https://github.com/bitcoin-core/guix.sigs.git
git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git
git clone https://github.com/bitcoin/bitcoin.git
Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki.
For 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
.
Generate list of authors:
git log --format='- %aN' v(current version, e.g. 25.0)..v(new version, e.g. 25.1) | grep -v 'merge-script' | sort -fiu
Checkout the Bitcoin Core version you'd like to build:
pushd ./bitcoin
SIGNER='(your builder key, ie bluematt, sipa, etc)'
VERSION='(new version without v-prefix, e.g. 25.0)'
git fetch origin "v${VERSION}"
git checkout "v${VERSION}"
popd
Ensure your guix.sigs are up-to-date if you wish to guix-verify
your builds
against other guix-attest
signatures.
git -C ./guix.sigs pull
Create the macOS SDK tarball, see the macdeploy instructions for details.
Follow the relevant Guix README.md sections:
pushd ./guix.sigs
git add "${VERSION}/${SIGNER}"/noncodesigned.SHA256SUMS{,.asc}
git commit -m "Add attestations by ${SIGNER} for ${VERSION} non-codesigned"
popd
Then open a Pull Request to the guix.sigs repository.
macOS codesigner only: Create detached macOS signatures (assuming signapple is installed and up to date with master branch)
tar xf bitcoin-osx-unsigned.tar.gz
./detached-sig-create.sh /path/to/codesign.p12
Enter the keychain password and authorize the signature
signature-osx.tar.gz will be created
tar xf bitcoin-win-unsigned.tar.gz
./detached-sig-create.sh -key /path/to/codesign.key
Enter the passphrase for the key when prompted
signature-win.tar.gz will be created
It is advised to test that the code signature attaches properly prior to tagging by performing the guix-codesign
step.
However if this is done, once the release has been tagged in the bitcoin-detached-sigs repo, the guix-codesign
step must be performed again in order for the guix attestation to be valid when compared against the attestations of non-codesigner builds.
pushd ./bitcoin-detached-sigs
# checkout the appropriate branch for this release series
rm -rf ./*
tar xf signature-osx.tar.gz
tar xf signature-win.tar.gz
git add -A
git commit -m "point to ${VERSION}"
git tag -s "v${VERSION}" HEAD
git push the current branch and new tag
popd
- Once the Windows and macOS builds each have 3 matching signatures, they will be signed with their respective release keys.
- Detached signatures will then be committed to the bitcoin-detached-sigs repository, which can be combined with the unsigned apps to create signed binaries.
pushd ./guix.sigs
git add "${VERSION}/${SIGNER}"/all.SHA256SUMS{,.asc}
git commit -m "Add attestations by ${SIGNER} for ${VERSION} codesigned"
popd
Then open a Pull Request to the guix.sigs repository.
Combine the all.SHA256SUMS.asc
file from all signers into SHA256SUMS.asc
:
cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc
-
Upload to the bitcoincore.org server (
/var/www/bin/bitcoin-core-${VERSION}/
):-
The contents of each
./bitcoin/guix-build-${VERSION}/output/${HOST}/
directory, except for*-debug*
files.Guix will output all of the results into host subdirectories, but the SHA256SUMS file does not include these subdirectories. In order for downloads via torrent to verify without directory structure modification, all of the uploaded files need to be in the same directory as the SHA256SUMS file.
The
*-debug*
files generated by the guix build contain debug symbols for troubleshooting by developers. It is assumed that anyone that is interested in debugging can run guix to generate the files for themselves. To avoid end-user confusion about which file to pick, as well as save storage space do not upload these to the bitcoincore.org server, nor put them in the torrent.find guix-build-${VERSION}/output/ -maxdepth 2 -type f -not -name "SHA256SUMS.part" -and -not -name "*debug*" -exec scp {} user@bitcoincore.org:/var/www/bin/bitcoin-core-${VERSION} \;
-
The
SHA256SUMS
file -
The
SHA256SUMS.asc
combined signature file you just created
-
-
Create a torrent of the
/var/www/bin/bitcoin-core-${VERSION}
directory such that at the top level there is only one file: thebitcoin-core-${VERSION}
directory containing everything else. Name the torrentbitcoin-${VERSION}.torrent
(note that there is no-core-
in this name).Optionally help seed this torrent. To get the
magnet:
URI use:transmission-show -m <torrent file>
Insert the magnet URI into the announcement sent to mailing lists. This permits people without access to
bitcoincore.org
to download the binary distribution. Also put it into theoptional_magnetlink:
slot in the YAML file for bitcoincore.org. -
Update other repositories and websites for new version
-
bitcoincore.org blog post
-
bitcoincore.org maintained versions update: table
-
Delete post-EOL release branches and create a tag
v${branch_name}-final
. -
Delete "Needs backport" labels for non-existing branches.
-
bitcoincore.org RPC documentation update
-
Update packaging repo
-
Push the flatpak to flathub, e.g. flathub/org.bitcoincore.bitcoin-qt#2
-
Push the snap, see https://github.com/bitcoin-core/packaging/blob/main/snap/local/build.md
-
-
This repo
-
Archive the release notes for the new version to
doc/release-notes/
(branchmaster
and branch of the release) -
Create a new GitHub release with a link to the archived release notes
-
-
-
Announce the release:
-
bitcoin-dev and bitcoin-core-dev mailing list
-
Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/
-
Bitcoin Core Twitter https://twitter.com/bitcoincoreorg
-
Celebrate
-
Both variables are used as a guideline for how much space the user needs on their drive in total, not just strictly for the blockchain. Note 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.
To calculate m_assumed_blockchain_size
, take the size in GiB of these directories:
- For
mainnet
-> the data directory, excluding the/testnet3
,/signet
, and/regtest
directories and any overly large files, e.g. a hugedebug.log
- For
testnet
->/testnet3
- For
signet
->/signet
To calculate m_assumed_chain_state_size
, take the size in GiB of these directories:
- For
mainnet
->/chainstate
- For
testnet
->/testnet3/chainstate
- For
signet
->/signet/chainstate
Notes:
- 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. - The expected overhead for growth may change over time. Consider whether the percentage needs to be changed in response; if so, update it here in this section.