docs: document new CHANGELOG-management strategy #4894
Conversation
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. |
| @@ -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. | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 😮
There was a problem hiding this comment.
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 :)
Description
At the moment, we have to send a separate PR that removes the
- unreleasedsuffix inCHANGELOG.mdbefore 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
- unreleasedwould 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