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 libp2p#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: libp2p#4894.

Author: thomaseizinger

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".

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). 

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).

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).

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).

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"