Create a tool to automate updating changelog files

[ia0]

See this doc for a description of the problem. The goal of this issue is to write a tool that would update the CHANGELOG.md file of a crate, and if necessary the Cargo.toml too as well as all the dependents Cargo.toml and CHANGELOG.md files if any.

It should probably look something like:

cargo xtask change crates/prelude minor 'Add foo::bar module to support FooBar'
cargo xtask change crates/board major 'Change Foo::bar() to return an error'

It should also provide a CI test to make sure changelog are correctly modified in PRs:

• Only the pre-release is modified (or the skip changelog counter) and changes are only prepended.
• If the skip changelog counter is bumped, then there must be a pre-release.
• The pre-release version is bumped accordingly to the highest sub-section (major, minor, patch).

[invernizzi]

Would https://github.com/google-github-actions/release-please-action solve this issue?

[ia0]

Would https://github.com/google-github-actions/release-please-action solve this issue?

Not really. I haven't yet seen a tool that supports more than simple repositories. In particular, most tools (like release-please) rely on conventional commits which has deep issues for mono-repos (this repository contains 72 crates of which 14 are published). In particular, conventional commits don't support PRs that touch multiple crates in different ways but still with the same purpose. There is this issue trying to add mono-repo support but it has been stale for 2 years and doesn't even fix the problem. It only suggests to support multiple scopes (which also has a stale issue). But multiple scopes is not enough because changes may be of different nature to different crates. This is particularly true in Rust with proc-macro, where a change to the proc-macro crate may be minor while its usage in another crate may be major (typically api-macro and api in the case of this repository).¹

However, it's a good point that a part of this task could be to look for existing tools to get inspiration or even find something working that doesn't need more setup and maintenance than writing something custom (I don't expect the tool we need to be more than 100 lines of code, in particular given most of the code will be shared with other tooling or reuse existing crates like semver or maybe git2, while I expect most of those tools to need more than 100 lines of configuration because they don't scale with the number of crates).

Footnotes

1. That's actually something that is not automatable. The tool could either try to detect those cases or simply do something wrong which is going to be caught during review. ↩