Ask HN: How do you automate your release notes?

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?

Full disclosure, I’m one of the owners of ReleaseNotes.io. Not trying to pitch, just sharing what we see across a lot of teams.

1. For OSS projects, GitHub Releases honestly work really well. You usually have contributors who understand the context, and readers who are technical enough to parse a changelog.

2. If you're talking to users, Release notes stop being a dev artifact and become a communication channel. They need to show up where users already are, in-app, email, Slack, etc. There are a bunch of tools like us (ReleaseNotes.io), LaunchNotes, AnnounceKit, Canny and others that help with that.

3. From what we see, the teams that have the most success with automation of this process treat GitHub PRs or Jira, Azure DevOps, Linear, GitHub issues as the source of truth. Also their issues/PR descriptions tend to clearly describe the problem and the solution.

4. Any automation of this process leans heavily on the quality of your issue/PR descriptions as garbage-in = garbage-out. Because of this it's tricky to fully automate the process as at some level you usually need a person casting an eye over the release note just to sense check.

I agree that the best quality notes are the ones hand written by a thoughtful human. In my case we had about two years of history with no curated notes, and writing that by hand would have meant significant time investment vs shipping fixes and features. The generator helped us get coverage fast, organized the notes chronologically and categorically. I specifically designed the generator with your your concern in mind, in that it preserves manual edits as well as omissions, so we can gradually curate it into something we are proud of.