logoalt Hacker News

sshineyesterday at 8:17 PM2 repliesview on HN

I automate one changelog per project using git-cliff and conventional commits:

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.


Replies

RadiozRadiozyesterday at 8:39 PM

While 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.

show 1 reply
Thoughtfulyesterday at 8:26 PM

really helpful, thanks for sharing!