Hopefully this software is better but this seems like an opportune place to lodge this complaint.
The idea behind auto-generating the changelog with a tool like git-cliff is to use it in conjunction with conventions on your commit messages like Conventional Commits [1]. This gives you fine grained control about what will appear in the changelog.
What you do, is to move the decision whether some information ought to appear in the changelog from the time of release to the time of the commit. You also shift the responsibility from the release manager to the individual developers. The big advantage of this process is that it is much harder to forget to include things.
If that is a good idea depends on your project and team. For open source projects, where everything is public anyways, the generated changelog could act as a pretty-printed, filtered and limited view of the git history.
For proprietary software I believe the commit messages should be a space where the developers can express themselves without having to worry about that anything they write could end up at the customer (which I presume is the ultimate consumer of the changelog).
I also think there is a difference between a changelog and release notes with the former not being a replacement for the latter. For a good example how in my opinion useful release notes could look like see [2].
Apart from all of that git-cliff is an excellent implementation.
Which doesn't make any sense.
20 commits/PRs might fit together in as one line in the changelog. There is nothing that one can write in any one of those commits that make any sense at the time of commiting.
Still, stuff like:
7a48c5b (cell) Add EMPTY and
(const) new method by @EdJoPaTo in #1143
This simplifies calls to
`Buffer::filled` in tests.
A better example, in my eyes, is teamcity.
https://www.jetbrains.com/help/teamcity/what-s-new-in-teamci...
A curated overview that actually explains the change rather than just states a difference.
They also have a similar view of fixed tickets: https://www.jetbrains.com/help/teamcity/teamcity-2024-03-rel...
Doing what teamcity does takes some effort. And I guess my gripe is the belief that these conventional commits will save the majority of work of the release notes. It can be a convenience but it needs curation and work to be presentable. And most projects seem to pick them to avoid that work.
My knee-jerk reaction is that now we’re just inventing something to sandwich in-between two already existing and useful things: the git log and the curated end-user change documentation.
This is not useful to decide if I should upgrade now, or what should I try out after upgrade --- and this is what a release note should be doing.
I disagree: I think it's extremely helpful for users to read dozens or even hundreds of commit messages saying "fixed typo".
/s
Normally, commits must match a particular pattern to be included. Those that start with "feat:" might appear in the features section, while those starting with "bug:" show up in fixes.
A few simple rules are enough to ensure that an intelligible changelog is generated. Minimal cleanup can then focus on making it presentable.
You could even set up your pull request rules to handle this for you. On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates.
>On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates.
Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.)
Making snarky comments isn't particularly interesting, nor does it offer much opportunity for discussing the actual benefits/drawbacks of the topic.
> Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.)
That's an issue with the policies of those specific organisations rather than with the idea of generating a changelog from commit messages.
Squashing/Rebasing isn't necessary to generate a clean changelog. You don't need to include every commit by default.