bitcoin/doc/release-process.md

Release process

This document outlines the process for releasing versions of the form $MAJOR.$MINOR.$PATCH.

We distinguish between two types of releases: regular and maintenance releases. Regular releases are releases of a new major or minor version as well as patches of the most recent release. Maintenance releases, on the other hand, are required for patches of older releases.

You should coordinate with the other maintainers on the release date, if possible. This date will be part of the release entry in CHANGELOG.md and it should match the dates of the remaining steps in the release process (including the date of the tag and the GitHub release). It is best if the maintainers are present during the release, so they can help ensure that the process is followed correctly and, in the case of a regular release, they are aware that they should not modify the master branch between merging the PR in step 1 and the PR in step 3.

This process also assumes that there will be no minor releases for old major releases.

We aim to cut a regular release every 3-4 months, approximately twice as frequent as major Bitcoin Core releases. Every second release should be published one month before the feature freeze of the next major Bitcoin Core release, allowing sufficient time to update the library in Core.

Sanity checks

Perform these checks when reviewing the release PR (see below):

1. Ensure make distcheck doesn't fail.

   ./autogen.sh && ./configure --enable-dev-mode && make distcheck
   

2. Check installation with autotools:

   dir=$(mktemp -d)
   ./autogen.sh && ./configure --prefix=$dir && make clean && make install && ls -RlAh $dir
   gcc -o ecdsa examples/ecdsa.c $(PKG_CONFIG_PATH=$dir/lib/pkgconfig pkg-config --cflags --libs libsecp256k1) -Wl,-rpath,"$dir/lib" && ./ecdsa
   

3. Check installation with CMake:

   dir=$(mktemp -d)
   build=$(mktemp -d)
   cmake -B $build -DCMAKE_INSTALL_PREFIX=$dir && cmake --build $build && cmake --install $build && ls -RlAh $dir
   gcc -o ecdsa examples/ecdsa.c -I $dir/include -L $dir/lib*/ -l secp256k1 -Wl,-rpath,"$dir/lib",-rpath,"$dir/lib64" && ./ecdsa
   

4. Use the check-abi.sh tool to verify that there are no unexpected ABI incompatibilities and that the version number and the release notes accurately reflect all potential ABI changes. To run this tool, the abi-dumper and abi-compliance-checker packages are required.

   tools/check-abi.sh
   

Preparing and tagging a release

If you're going to sign the release, make sure that your default GPG signing key is the expected one. You can see your default key by running echo "test" | gpg --sign --verbose > /dev/null.

Regular release

1. Open a PR to the master branch with a commit (using message "release: prepare for $MAJOR.$MINOR.$PATCH", for example) that

   • finalizes the release notes in CHANGELOG.md by
     • adding a section for the release (make sure that the version number is a link to a diff between the previous and new version),
     • removing the [Unreleased] section header,
     • ensuring that the release notes are not missing entries (check the needs-changelog label on GitHub and also go manually through the list of commits since the previous release), and
     • including an entry for ### ABI Compatibility if it doesn't exist,
   • sets _PKG_VERSION_IS_RELEASE to true in configure.ac, and,
   • if this is not a patch release,
     • updates _PKG_VERSION_* and _LIB_VERSION_* in configure.ac, and
     • updates project(libsecp256k1 VERSION ...) and ${PROJECT_NAME}_LIB_VERSION_* in CMakeLists.txt.

2. Perform the sanity checks on the PR branch and attach the output of the check-abi tool (screenshot of the generated compatibility HTML report) to the PR description.

3. After the PR has been merged, tag the commit, and push the tag:

   RELEASE_COMMIT=<merge commit of step 1>
   git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH" $RELEASE_COMMIT
   git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
   

4. Open a PR to the master branch with a commit (using message "release cleanup: bump version after $MAJOR.$MINOR.$PATCH", for example) that

   • sets _PKG_VERSION_IS_RELEASE to false and increments _PKG_VERSION_PATCH and _LIB_VERSION_REVISION in configure.ac,
   • increments the $PATCH component of project(libsecp256k1 VERSION ...) and ${PROJECT_NAME}_LIB_VERSION_REVISION in CMakeLists.txt, and
   • adds an [Unreleased] section header and a corresponding [Unreleased] link at the bottom of CHANGELOG.md.

   If other maintainers are not present to approve the PR, it can be merged without ACKs.

Maintenance release

Note that bug fixes need to be backported only to releases for which no compatible release without the bug exists.

1. If there's no maintenance branch $MAJOR.$MINOR, create one:

   git checkout -b $MAJOR.$MINOR v$MAJOR.$MINOR.$((PATCH - 1))
   git push git@github.com:bitcoin-core/secp256k1.git $MAJOR.$MINOR
   

2. Open a pull request to the $MAJOR.$MINOR branch that
   • includes the bug fixes,
   • finalizes the release notes similar to a regular release,
   • increments _PKG_VERSION_PATCH and _LIB_VERSION_REVISION in configure.ac and the $PATCH component of project(libsecp256k1 VERSION ...) and ${PROJECT_NAME}_LIB_VERSION_REVISION in CMakeLists.txt (with commit message "release: bump versions for $MAJOR.$MINOR.$PATCH", for example).
3. Perform the sanity checks on the PR branch.
4. After the PR has been merged, update the release branch, tag the commit, and push the tag:

   git checkout $MAJOR.$MINOR && git pull
   git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH"
   git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
   

5. Open a PR to the master branch that includes a commit (with commit message "release notes: add $MAJOR.$MINOR.$PATCH", for example) that adds release notes to CHANGELOG.md.
6. Get the PR merged to ensure that the CHANGELOG.md file on the master branch is current before announcing the release.

Creating a tarball and announcing the release

1. Create a tarball and a detached GPG signature covering it, and check that the signature verifies under the expected key.

   git archive --output "libsecp256k1-$MAJOR.$MINOR.$PATCH.tar.gz" --prefix "libsecp256k1-$MAJOR.$MINOR.$PATCH/" v$MAJOR.$MINOR.$PATCH
   gpg --detach-sign "libsecp256k1-$MAJOR.$MINOR.$PATCH.tar.gz"
   gpg --verify "libsecp256k1-$MAJOR.$MINOR.$PATCH.tar.gz.sig"
   

2. Create a new GitHub release with a link to the corresponding entry in CHANGELOG.md. Attach the tarball and the detached signature.
3. Send an announcement email to the bitcoin-dev mailing list.

Cleaning up

1. Close the GitHub milestone, and create a new one. Consider moving unresolved issues to the new milestone.
2. Remove the needs-changelog label from all merged PRs.