https://github.com/orhun/git-cliff
https://www.conventionalcommits.org/en/v1.0.0/
This changelog is copied into the release on github, or wherever the release is announced.
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.
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.
> That’s funny, because I find the lack of automation to be the lazy choice.
Automation is cheap these days. Many automations make things that exceed human ability, but this isn't one of those cases. You'll get something good-enough, but not great. Perhaps that's what your organisation has time and budget for, in which case your use of automation makes sense, but if we're trying to make the best audience-tailored summaries of software releases with specific purpose, the strategy falls short.
> Forgetting to add to the changelog because the requirement is checked by humans,
Individual developers definitely can, which is why you must also have organizational process. If a valid changelog checked by a release manager is a requirement for a software release, it can't be forgotten.
> 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.)
I'm curious about the implication of insignificant commits coming from a lack of structure. I think it's entirely normal to have single commits fix something innocuous. If there's a typo in one file, you wouldn't fix it as part of creating a feature, because that's work outside the scope of the feature. So it would have to be in its own commit, or alongside other similar refinements. And those examples are indeed unacceptable commit messages that would not make it through code review in any serious shop, but I get what you mean, and it's part of my point: developers are supposed to write commit messages for developers, and the needs of developers are different to the needs of people reading a changelog, so it's only natural that the text should be changed for the different audience.
> 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.
I really think this is backwards and exactly the thing I was advocating against. The changelog you have is so large and poorly-structured that you need to use an AI to summarise it for you, and gather the information that should have been in the changelog in the first place. If that needs to be done to make the changelog useful, clearly its original state is deficient?