alt Hacker NewsWhile more automation certainly is useful, I find that auto-generating changelogs in this manner has a number of problems:
Auto-genertaed changelogs lack business-aware context about what is important. You get a big list of new features, but which ones are the most important to stakeholders? You have a few breaking changes, which are likely to have the most widespread impact? Without being judicious about what information is included, you risk overwhelming readers with line noise and burying important notes.
Some things go beyond the scope of a commit message - deployment nuance, interaction with other relases, featureset compatibility matrices. These are best summarised at the top level, they don't fit in individual disparate messages.
One of OP's motivations for starting this thread was to see how people tailor changelogs to different types of stakeholders; techincal vs non-technical, for example. This approach doesn't solve that problem. In fact, I think it's worse due to an additional side effect: the commits are now forced to do double duty; they must be useful commits for developers looking at code history, but now they also must be useful messages to be included in a changelog. While there is some overlap, it's hard to do both simultaneously. One must pick between writing good commit messages for the codebase & developers, versus writing a coherent changelog.
As a matter of personal taste, I think it looks lazy. Changelogs are a unique opportunity to communicate something important, they're written once and read by many. With a list of commits, myself and all other readers must now put in the work to find out what's relevant - it's disrespectful of others' time.
> You get a big list of new features, but which ones are the most important to stakeholders?
I worked for one startup with one major customer who was really skeptic of investing further because of stability problems, feature delay problems, and lack of transparency. Along with a complete list of changes that gave them insight into how we prioritised between stability and feature development, I wrote a human summary of what this meant — experiments, summaries of statistics, summary of most important changes to business logic.
Writing personally to your stakeholders does not exclude being systematic, and vice versa.
> As a matter of personal taste, I think it looks lazy.
That’s funny, because I find the lack of automation to be the lazy choice. Forgetting to add to the changelog because the requirement is checked by humans, or because single commits fix things below some bar of noteworthiness that is entirely subjective and driven by lack of structure. Not writing commit messages worth putting in release notes (fix sht, asdasdasd, etc.)
> Changelogs are a unique opportunity to communicate something important, they're written once and read by many. with a list of commits, myself and all other readers must now put in the work to find out what's relevant - it's disrespectful of others' time.*
When I migrate software, I’m very interested in the complete picture. I’ll ask my AI agent to go over the links in the changelog and summaries for me what are the breaking changes and what manual steps do I need to take. Having them in human-readable form ahead of time would be nice.
Since git-cliff has different sections, I can skip changes to documentation. Because of SemVer, I know if there’s something breaking.