Find a better way to add to the changelog

[kamalmarhubi]

Every time a PR gets merged, almost all other PRs end up requiring a rebase to fix up the changelog. This is annoying for everyone involved.

[lucab]

I definitely agree. If it may help as a source of inspiration, this is what we use in rkt: basically a script to collect all PR titles and summaries since last tag. It is up to the release pilot (the one currently owning the GPG key) to do the final cosmetic pass and push the artifacts. I think it could be even further automated via cargo-release.

/cc @sunng87

[sunng87]

Thank you for mentioning. For now cargo-release cannot generate changelog because I still haven't found a standard way to collect changes. In my previous team, we use (feat), (fix) to prefix our commit message. But generating meaningful changelog is still difficult with that.

Changelog is an important part of software and maybe we need to write it formally just like our code.

Any suggestion is welcomed.

[Susurrus]

I think there should be a command-line option like --auto-changelog that you can opt into that will compile the changelog from commits that use the special syntax. The syntax should follow from that used by keepachangelog.com, which is Added, Changed, Fixed, Removed. Maybe something like:

Commit title:

Add AioCb::from_boxed_slice

Commit body:

The existing AioCb constructors work for simple programs where
everything is stored on the stack. But in more complicated programs the.
borrow checker can't prove that a buffer will outlive the AioCb that
references it. Fix this problem by introducting
AioCb::from_boxed_slice, which takes a reference-counted buffer.

Added AioCb::from_boxed_slice #582

This would then be appended to the end of the "Added" section of the changelog like:

Added AioCb::from_boxed_slice (#582)

So that last line follows the format of starting with one "Added", "Changed", "Fixed", or "Removed" (and various other conjugates of those verbs) following by a bunch of text. If there's a #XXX at the end, assume it's a valid PR and format it as a hyperlink as shown above with the proper URL.

I have another couple of projects on GitLab (gattii and serialport-rs) and I'd love if this could be designed from the beginning to support GitLab as well as GitHub (there they call PRs MRs) and I can help with testing that as well.

[lucab]

@Susurrus I'd be wary of mandating a single syntax, as I already seen multiple attempted proposals and all of them with limited success. Mostly because different projects have different requirements, and a one-size-fits-all quickly becomes too baroque.

To avoid stealing this thread I'm moving this cargo-release discussion over to crate-ci/cargo-release#31, so that nix maintainers can still discuss what they need here without too much noise.