From 338e467927f8a0cba34eb24288f0be9b0972d05d Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Tue, 21 Nov 2023 00:46:06 +1100 Subject: [PATCH] docs: document new CHANGELOG-management strategy At the moment, we have to send a separate PR that removes the `- unreleased` suffix in `CHANGELOG.md` before we can make a release. This is annoying and unnecessarily delays being able to make releases for features that have been merged into master. As of #4620, we have CI checks that ensure we add a changelog entry when a particular crate is modified. Additionally, the CI check also ensures we bump the version in case the top-most one of the changelog is already released. The combination of these checks should ensure that we add a section for the new version in case the top-most one is already released. Previously, the presence of `- unreleased` would notify us of that. In the future, we can add a CI job that allows us to release at the press of a button (think `workflow_dispatch`). Until then, this setup should already make it much easier to release crates. Pull-Request: #4894. --- docs/release.md | 37 +++++++++++++------------------- protocols/gossipsub/CHANGELOG.md | 2 +- protocols/identify/CHANGELOG.md | 2 +- protocols/kad/CHANGELOG.md | 2 +- protocols/mdns/CHANGELOG.md | 2 +- scripts/add-changelog-header.sh | 2 +- 6 files changed, 20 insertions(+), 27 deletions(-) diff --git a/docs/release.md b/docs/release.md index 8edc621c127..50b7b0605c7 100644 --- a/docs/release.md +++ b/docs/release.md @@ -17,43 +17,34 @@ Non-breaking changes are typically merged very quickly and often released as pat Every crate that we publish on `crates.io` has a `CHANGELOG.md` file. Substantial PRs should add an entry to each crate they modify. -The next unreleased version is tagged with ` - unreleased`, for example: `0.17.0 - unreleased`. +We have a CI check[^1] that enforces adding a changelog entry if you modify code in a particular crate. +In case the current version is already released (we also check that in CI), you'll have to add a new header at the top. +For example, the top-listed version might be `0.17.3` but it is already released. +In that case, add a new heading `## 0.17.4` with your changelog entry in case it is a non-breaking change. -In case there isn't a version with an ` - unreleased` postfix yet, add one for the next version. -The next version number depends on the impact of your change (breaking vs non-breaking, see above). - -If you are making a non-breaking change, please also bump the version number: - -- in the `Cargo.toml` manifest of the respective crate -- in the `[workspace.dependencies]` section of the workspace `Cargo.toml` manifest - -For breaking changes, a changelog entry itself is sufficient. -Bumping the version in the `Cargo.toml` file would lead to many merge conflicts once we decide to merge them. -Hence, we are going to bump those versions once we work through the milestone that collects the breaking changes. +The version in the crate's `Cargo.toml` and the top-most version in the `CHANGELOG.md` file always have to be in sync. +Additionally, we also enforce that all crates always depend on the latest version of other workspace-crates through workspace inheritance. +As a consequence, you'll also have to bump the version in `[workspace.dependencies]` in the workspace `Cargo.toml` manifest. ## Releasing one or more crates +The above changelog-management strategy means `master` is always in a state where we can make a release. + ### Prerequisites - [cargo release](https://github.com/crate-ci/cargo-release/) ### Steps -1. Remove the ` - unreleased` tag for each crate to be released in the respective `CHANGELOG.md`. - Create a pull request with the changes against the rust-libp2p `master` branch. - -2. Once merged, run the two commands below on the (squash-) merged commit on the `master` branch. +1. Run the two commands below on the (squash-) merged commit on the `master` branch. 1. `cargo release publish --execute` 2. `cargo release tag --sign-tag --execute` -3. Confirm that `cargo release` tagged the commit correctly via `git push - $YOUR_ORIGIN --tag --dry-run` and then push the new tags via `git push - $YOUR_ORIGIN --tag`. Make sure not to push unrelated git tags. - - Note that dropping the `--no-push` flag on `cargo release` might as well do - the trick. +2. Confirm that `cargo release` tagged the commit correctly via `git push $YOUR_ORIGIN --tag --dry-run` + Push the new tags via `git push $YOUR_ORIGIN --tag`. + Make sure not to push unrelated git tags. ## Patch release @@ -77,3 +68,5 @@ To avoid accidental breaking changes for our users, we employ the following conv Example: `0.1.0-alpha` to `0.2.0-alpha`. - For a non-breaking change in a crate with an alpha release, bump or append number to the "alpha" tag. Example: `0.1.0-alpha` to `0.1.0-alpha.1`. + +[^1]: See [ci.yml](../.github/workflows/ci.yml) and look for "Ensure manifest and CHANGELOG are properly updated". diff --git a/protocols/gossipsub/CHANGELOG.md b/protocols/gossipsub/CHANGELOG.md index 68041f2dcd3..5ff4cfa27d6 100644 --- a/protocols/gossipsub/CHANGELOG.md +++ b/protocols/gossipsub/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.46.1 - unreleased +## 0.46.1 - Deprecate `Rpc` in preparation for removing it from the public API because it is an internal type. See [PR 4833](https://github.com/libp2p/rust-libp2p/pull/4833). diff --git a/protocols/identify/CHANGELOG.md b/protocols/identify/CHANGELOG.md index d2f67bd908c..22c74b28cae 100644 --- a/protocols/identify/CHANGELOG.md +++ b/protocols/identify/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.44.1 - unreleased +## 0.44.1 - Ensure `Multiaddr` handled and returned by `Behaviour` are `/p2p` terminated. See [PR 4596](https://github.com/libp2p/rust-libp2p/pull/4596). diff --git a/protocols/kad/CHANGELOG.md b/protocols/kad/CHANGELOG.md index d59ea8acb17..4740e4b1f95 100644 --- a/protocols/kad/CHANGELOG.md +++ b/protocols/kad/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.45.2 - unreleased +## 0.45.2 - Ensure `Multiaddr` handled and returned by `Behaviour` are `/p2p` terminated. See [PR 4596](https://github.com/libp2p/rust-libp2p/pull/4596). diff --git a/protocols/mdns/CHANGELOG.md b/protocols/mdns/CHANGELOG.md index c6a9359c23b..6f5aa6945fd 100644 --- a/protocols/mdns/CHANGELOG.md +++ b/protocols/mdns/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.45.1 - unreleased +## 0.45.1 - Ensure `Multiaddr` handled and returned by `Behaviour` are `/p2p` terminated. See [PR 4596](https://github.com/libp2p/rust-libp2p/pull/4596). diff --git a/scripts/add-changelog-header.sh b/scripts/add-changelog-header.sh index 8050857c52e..4717940c8d7 100755 --- a/scripts/add-changelog-header.sh +++ b/scripts/add-changelog-header.sh @@ -7,4 +7,4 @@ if [[ $header == $prefix* ]]; then exit fi -sed -i "1i ## ${NEW_VERSION} - unreleased\n\n" "$CRATE_ROOT/CHANGELOG.md" +sed -i "1i ## ${NEW_VERSION}\n\n" "$CRATE_ROOT/CHANGELOG.md"