doc: improve release process

- make version on master always equal to latest release with patch+1
- separate regular from maintenance releases
- add more git commands to prevent accidents
- mention that one needs to somehow deal with release dates
- _LIB_VERSIONS_ -> _LIB_VERSION_
- don't push all tags in step 4
- add required message to git tag
- add suggested commit messages

Author: jonasnick

doc/release-process.md

@@ -1,14 +1,52 @@
 # Release Process
 
-1. Open PR to master that
-   1. adds release notes to `CHANGELOG.md` and
-   2. if this is **not** a patch release, updates `_PKG_VERSION_{MAJOR,MINOR}` and `_LIB_VERSIONS_*` in `configure.ac`
-2. After the PR is merged,
-   * if this is **not** a patch release, create a release branch with name `MAJOR.MINOR`.
-     Make sure that the branch contains the right commits.
-     Create commit on the release branch that sets `_PKG_VERSION_IS_RELEASE` in `configure.ac` to `true`.
-   * if this **is** a patch release, open a pull request with the bugfixes to the `MAJOR.MINOR` branch.
-     Also include the release note commit bump `_PKG_VERSION_PATCH` and `_LIB_VERSIONS_*` in `configure.ac`.
-4. Tag the commit with `git tag -s vMAJOR.MINOR.PATCH`.
-5. Push branch and tag with `git push origin --tags`.
-6. Create a new GitHub release with a link to the corresponding entry in `CHANGELOG.md`.
+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](../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.
+
+## 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](../CHANGELOG.md) (make sure to include an entry for `### ABI Compatibility`) and
+   * updates `_PKG_VERSION_*`, `_LIB_VERSION_*`, and sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`.
+2. After the PR is merged, tag the commit and push it:
+   ```
+   RELEASE_COMMIT=<merge commit of step 1>
+   git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH" $RELEASE_COMMIT
+   git push [email protected]:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
+   ```
+3. Open a PR to the master branch with a commit (using message `"release: bump version after $MAJOR.$MINOR.$PATCH"`, for example) that sets `_PKG_VERSION_IS_RELEASE` to `false` and `_PKG_VERSION_PATCH` to `$PATCH + 1` and increases `_LIB_VERSION_REVISION`. If other maintainers are not present to approve the PR, it can be merged without ACKs.
+4. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
+
+## Maintenance release
+
+Note that bugfixes only need to be backported to releases for which no compatible release without the bug exists.
+
+1. If `$PATCH = 1`, create maintenance branch `$MAJOR.$MINOR`:
+   ```
+   git checkout -b $MAJOR.$MINOR v$MAJOR.$MINOR.0
+   git push [email protected]:bitcoin-core/secp256k1.git $MAJOR.$MINOR
+   ```
+2. Open a pull request to the `$MAJOR.$MINOR` branch that
+   * includes the bugfixes,
+   * finalizes the release notes,
+   * bumps `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac` (with commit message `"release: update PKG_ and LIB_VERSION for $MAJOR.$MINOR.$PATCH"`, for example).
+3. After the PRs are merged, update the release branch and tag the commit:
+   ```
+   git checkout $MAJOR.$MINOR && git pull
+   git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH"
+   ```
+4. Push tag:
+   ```
+   git push [email protected]:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
+   ```
+5. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
+6. 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).