Comment by lloydatkinson | Hacker News Reader

Comment by lloydatkinson | Hacker News Reader

Parent Full thread

Did you look at the example changelogs git-cliff creates?

> I try to put the important things first in the changelog and keep it brief. The changelog is a heads-up for users that things have changed or been fixed and users don't want to spend hours reading it.

Provided the commits use conventional commit format such as "feat(thing): fixed crash when copying file to xyz backend" or "fix(database): generate migrations correctly" not only do you get the type of commit but also the category or area.

git-cliff and others then use that to automatically add sections for each category of commit. This wouls surely needing to spend hours on writing changelogs, which seems an insane amount of time to me.

> I also spend maybe an hour each release editing the auto generated changelog, removing the noise (refactored X, fixed docs for Y, made tests for Z work), condensing multiple entries, reorganizing, moving things to the correct section, linking stuff etc.

I find that conventional commit wastes space in the summary for little gain. Categories are subjective and just not worth discussing much of the time. Even with it, how do you deal with things like reverts to commits that shouldn't be mentioned in the changelog anymore? Updating text or copy is also annoying.

I've found that storing changelog snippets in the repository is far more scalable (one file per note in a directory). This allows future changes to update changelog entries and reverts to just remove them completely.

There's also enough trouble getting Github and GitLab to support commenting on commit messages (something they should do anyways!) that feedback on release notes stuffed into commit messages is then a third-class process. They can still be collated and gathered just like from the commit messages, but they're actually tracked by git and there's no confusion when backporting changes: the release note comes with it without having to merge with conflict notes, `cherry-pick -x` notes, etc. You're also not limited to a measly single line for describing your change.

> I find that conventional commit wastes space in the summary for little gain

The things that conventional commits adds to commits were intended to be accomplished by commit trailers (Co-authored-by, Signed-off-by, etc.). Nobody is stopping anyone from having a “Change-type” trailer and a “Product-area” one too. You can have these in a template on your machine so it’s the same amount of typing involved. You can even tack on `--trailer` to `git commit` if you insist on using `-m` for everything and never filling out the commit body (commits devoid of detail are another plague on repositories).

Yes, trailers are built-in and serve the metadata purpose in a fair amount of projects already.

There’s also more freedom to be verbose (“Change-For-Downstream-X”) since they are at the very bottom of the commit message. You can even filter out certain trailers with git log.

The Conventional Commits people were apparently not aware of this capability when they started (understandable since the tooling is niche). You can see they had some back and forths about trying to get their “footers” in line with trailers and how they had to stumble across misunderstandings about how they work.

> I've found that storing changelog snippets in the repository is far more scalable (one file per note in a directory).

Do you have an example repo that you can share? This sounds really ideal but wondering how this is managed and organized between releases.

See https://gitlab.kitware.com/cmake/cmake/-/tree/master/Help/re... for where CMake stores its "release snippets". There's a template file to anchor the directory and serve as an example. At each release, the directory is emptied out and release notes put into sorted order and edited for consistency/clarity.

> Did you look at the example changelogs git-cliff creates?

This isn't easily discoverable from the landing page -- I think the site could benefit from an "examples" sections. Given the focus on customizability, it'd be good to get a sense of what's possible, rather than diving straight into Get Started, before I've decided that I want to use the tool.

Reply on news.ycombinator.com