[weinzierl]

Unpopular opinions:

1. Release notes should never be created mechanically but focus on the consumer of the release.

2. The best changelog is your git. It is OK to generate a calcified changelog for an audience that prefers that.

Last and least:

3. The commit messages are a private space where developers communicate. The messages should never end up at the customer without thorough filtering and distillation.

Apart from that: git-cliff is excellent. If you must generate a document from commits, use that.

[dustfinger]

I agree with the philosophy of curating release notes for the consumer of the release. When I first started looking for a release notes strategy, I was considering towncrier for that exact reason. You are also right that commit messages are not intended for the consumer of the release, but a dialogue between developers.

Your points are well received and largely why I went PR-based (title/body with optional GitHub metadata) instead of commit-based. A PR title and body tend to be focused on the deliverable, whereas commit messages are narrowly focused on the code change at that moment with developers as the intended audience.

Re: git-cliff, I honestly hadn’t evaluated this one, but it looks solid for commit-driven changelogs. I like the rationale behind conventional commits being parsable and templates enforcing consistency. What constraints pushed you toward git-cliff vs writing release notes by hand, and do you have a config/template you have found works well for surfacing breaking changes?