release-process.md (5968B)
1 # Release process 2 3 This document outlines the process for releasing versions of the form `$MAJOR.$MINOR.$PATCH`. 4 5 We distinguish between two types of releases: *regular* and *maintenance* releases. 6 Regular releases are releases of a new major or minor version as well as patches of the most recent release. 7 Maintenance releases, on the other hand, are required for patches of older releases. 8 9 You should coordinate with the other maintainers on the release date, if possible. 10 This date will be part of the release entry in [CHANGELOG.md](../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). 11 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. 12 13 This process also assumes that there will be no minor releases for old major releases. 14 15 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. 16 17 ## Sanity checks 18 Perform these checks when reviewing the release PR (see below): 19 20 1. Ensure `make distcheck` doesn't fail. 21 ```shell 22 ./autogen.sh && ./configure --enable-dev-mode && make distcheck 23 ``` 24 2. Check installation with autotools: 25 ```shell 26 dir=$(mktemp -d) 27 ./autogen.sh && ./configure --prefix=$dir && make clean && make install && ls -RlAh $dir 28 gcc -o ecdsa examples/ecdsa.c $(PKG_CONFIG_PATH=$dir/lib/pkgconfig pkg-config --cflags --libs libsecp256k1) -Wl,-rpath,"$dir/lib" && ./ecdsa 29 ``` 30 3. Check installation with CMake: 31 ```shell 32 dir=$(mktemp -d) 33 build=$(mktemp -d) 34 cmake -B $build -DCMAKE_INSTALL_PREFIX=$dir && cmake --build $build --target install && ls -RlAh $dir 35 gcc -o ecdsa examples/ecdsa.c -I $dir/include -L $dir/lib*/ -l secp256k1 -Wl,-rpath,"$dir/lib",-rpath,"$dir/lib64" && ./ecdsa 36 ``` 37 4. Use the [`check-abi.sh`](/tools/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. 38 ```shell 39 tools/check-abi.sh 40 ``` 41 42 ## Regular release 43 44 1. Open a PR to the master branch with a commit (using message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that 45 * finalizes the release notes in [CHANGELOG.md](../CHANGELOG.md) by 46 * adding a section for the release (make sure that the version number is a link to a diff between the previous and new version), 47 * removing the `[Unreleased]` section header, and 48 * including an entry for `### ABI Compatibility` if it doesn't exist, 49 * sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`, and, 50 * if this is not a patch release, 51 * updates `_PKG_VERSION_*` and `_LIB_VERSION_*` in `configure.ac`, and 52 * updates `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_*` in `CMakeLists.txt`. 53 2. Perform the [sanity checks](#sanity-checks) on the PR branch. 54 3. After the PR is merged, tag the commit, and push the tag: 55 ``` 56 RELEASE_COMMIT=<merge commit of step 1> 57 git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH" $RELEASE_COMMIT 58 git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH 59 ``` 60 4. Open a PR to the master branch with a commit (using message `"release cleanup: bump version after $MAJOR.$MINOR.$PATCH"`, for example) that 61 * sets `_PKG_VERSION_IS_RELEASE` to `false` and increments `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac`, 62 * increments the `$PATCH` component of `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_REVISION` in `CMakeLists.txt`, and 63 * adds an `[Unreleased]` section header to the [CHANGELOG.md](../CHANGELOG.md). 64 65 If other maintainers are not present to approve the PR, it can be merged without ACKs. 66 5. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md). 67 6. Send an announcement email to the bitcoin-dev mailing list. 68 69 ## Maintenance release 70 71 Note that bug fixes need to be backported only to releases for which no compatible release without the bug exists. 72 73 1. If there's no maintenance branch `$MAJOR.$MINOR`, create one: 74 ``` 75 git checkout -b $MAJOR.$MINOR v$MAJOR.$MINOR.$((PATCH - 1)) 76 git push git@github.com:bitcoin-core/secp256k1.git $MAJOR.$MINOR 77 ``` 78 2. Open a pull request to the `$MAJOR.$MINOR` branch that 79 * includes the bug fixes, 80 * finalizes the release notes similar to a regular release, 81 * increments `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac` 82 and the `$PATCH` component of `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_REVISION` in `CMakeLists.txt` 83 (with commit message `"release: bump versions for $MAJOR.$MINOR.$PATCH"`, for example). 84 3. Perform the [sanity checks](#sanity-checks) on the PR branch. 85 4. After the PRs are merged, update the release branch, tag the commit, and push the tag: 86 ``` 87 git checkout $MAJOR.$MINOR && git pull 88 git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH" 89 git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH 90 ``` 91 6. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md). 92 7. Send an announcement email to the bitcoin-dev mailing list. 93 8. Open 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](../CHANGELOG.md).