docs: document new CHANGELOG-management strategy

[thomaseizinger]

Description

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.

Notes & open questions

Change checklist

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• A changelog entry has been made in the appropriate crates

[mxinden]

🚀

Thanks. This is cool. Didn't fully realize we are this far.

Soon our CI will be stricter and thus more famous than the Rust borrow checker.

[thomaseizinger]

Thanks. This is cool. Didn't fully realize we are this far.

I hope we have all the things in place now. At some point we just need to try and see whether the plan works as intended.

[nazar-pc]

This in particular makes it a bit harder to contribute. Previously it was clear from changelog alone if it is released or not. Now I guess I'll need to check crates.io as well to see if I need to add new section or not.

This whole changelog management process seems quite heavy to be honest.

[thomaseizinger]

I recognize that it is not ideal but I'd assume that most PRs go through at least one review cycle and multiple CI runs. Thus, a viable approach for contributors should be to just add to the top-most changelog entry and see if CI accepts that or not.

In fact, other than for experienced contributors like yourself, I'd expect this to be the default.

This whole changelog management process seems quite heavy to be honest.

I am definitely open to other ideas. So far, I've mostly tried to optimise for correctness and ease of maintainability, hence the high degree of automation here.

[nazar-pc]

If checks are smart enough to verify that already released entry is updated with more changes I think it is good, can't imagine how much debugging it took to make it work 😮

[thomaseizinger]

If checks are smart enough to verify that already released entry is updated with more changes I think it is good, can't imagine how much debugging it took to make it work 😮

Essentially, we check top_most_version_in_changelog_is_unreleased && changelog_has_been_modified. There is a corner-case where the top-most entry is unreleased and you modify an entry further down below. I don't really see why anybody would do that so I didn't bother codifying that (plus it is easy to catch during the review) :)

It took several attempts at making the checks robust but they've been working quite well recently :)