For me automating release notes is like recording an audio and play it each time you introduce your kid to somebody.
You worked hard you added all those new features and fixed several bugs and hopefully introduced no new ones, take the time and write the release notes yourself or with the team, make it a moment of celebration, read them and refine them (even with LLMs) but be proud of what you just accomplished.
For me writing release notes is a joy moment why should automate it?
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.
All I can say is I hate when projects just lazily list every pull request for its change log / release notes. It makes it very difficult to discover what breaking changes there are.
That has been my concern as well. The script I wrote tries to bucket entries into categories, including "Backward Incompatible Change" so those are easier to spot. Since it is automated I am trading some accuracy for time saved, which seemed like the only practical choice for me, since I had to backfill a lot of history, but it’s been surprisingly decent so far.
I am also planning to add some PR templates so contributors include the context up front, which should make any release note generation more accurate.
Are you using any tooling to help with changelog curration? I know towncrier is all about fragments, so contributors must had write a brief summary of their contribution, which would be more in-line with your preference.
Not related really, as you can (and should) publish BREAKING.md separately. Release notes should inform more about new stuff than the update process. Usually PRs have details, so release notes can be easily automated. Migrations, on the other hand…
+1 on separating "how to upgrade" due to breaking changes from "what’s new". A dedicated BREAKING.md / MIGRATIONS.md is a really good idea.
One thing I am trying to do is make the generator surface breaking/migration items explicitly, but I still think anything that requires human judgment (migration steps, caveats) should be hand-curated in a dedicated document like you suggested.
I add release notes to a draft Markdown file in the same commit as every change, under the appropriate Breaking / Changes etc. heading, so when I'm ready to release that becomes the next release notes.
I've never seen an auto-generated set of release notes I liked, a list of PRs doesn't cut it.
I hear what you are saying, there is a risk that auto-generated release notes end up as PR-title soup. I put a lot of effort in my script to mitigate against that.
If you are willing and interested enough to take a quick look, here is what my script generated for our 2025 changelog (no hand-curation yet, this is the raw output):
I am curious: does this still seem too noisy in your opinion, or is it getting closer? And what would you want to see for breaking changes/migrations to make it actually useful?
I now have 2024 & 2025 generated; to fully hand-curate two years of history just wasn’t practical, so I’m trying to get the "80% draft" automatically and then curate over time.
We have our release notes fully automated from git tags, and it's unfortunately useless as people don't actually the right tags on things, so everyone ends up manually editing it.
Yeah, that matches what I have seen: if the upstream metadata isn’t reliable, automation can amplify the mess.
I tried to avoid relying solely on contributors to accurately label or tag things correctly. The script is tag-driven only for release boundaries (version tags), while categorization is derived from PR title & body with optional GitHub metadata. The script is idempotent and preserves edits/omissions so you can correct the few bad ones post-generation.
If you are curious, I am happy to share my script and would be genuinely interested whether it reduces the manual cleanup for your workflow. Also, if you run it with `--ai --github` and a PR body is sparse, it fetches a truncated PR diff and uses that as extra context for the LLM summary.
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.
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?
For me automating release notes is like recording an audio and play it each time you introduce your kid to somebody.
You worked hard you added all those new features and fixed several bugs and hopefully introduced no new ones, take the time and write the release notes yourself or with the team, make it a moment of celebration, read them and refine them (even with LLMs) but be proud of what you just accomplished.
For me writing release notes is a joy moment why should automate it?
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.
All I can say is I hate when projects just lazily list every pull request for its change log / release notes. It makes it very difficult to discover what breaking changes there are.
That has been my concern as well. The script I wrote tries to bucket entries into categories, including "Backward Incompatible Change" so those are easier to spot. Since it is automated I am trading some accuracy for time saved, which seemed like the only practical choice for me, since I had to backfill a lot of history, but it’s been surprisingly decent so far.
I am also planning to add some PR templates so contributors include the context up front, which should make any release note generation more accurate.
Are you using any tooling to help with changelog curration? I know towncrier is all about fragments, so contributors must had write a brief summary of their contribution, which would be more in-line with your preference.
Not related really, as you can (and should) publish BREAKING.md separately. Release notes should inform more about new stuff than the update process. Usually PRs have details, so release notes can be easily automated. Migrations, on the other hand…
+1 on separating "how to upgrade" due to breaking changes from "what’s new". A dedicated BREAKING.md / MIGRATIONS.md is a really good idea.
One thing I am trying to do is make the generator surface breaking/migration items explicitly, but I still think anything that requires human judgment (migration steps, caveats) should be hand-curated in a dedicated document like you suggested.
I add release notes to a draft Markdown file in the same commit as every change, under the appropriate Breaking / Changes etc. heading, so when I'm ready to release that becomes the next release notes.
I've never seen an auto-generated set of release notes I liked, a list of PRs doesn't cut it.
I hear what you are saying, there is a risk that auto-generated release notes end up as PR-title soup. I put a lot of effort in my script to mitigate against that.
If you are willing and interested enough to take a quick look, here is what my script generated for our 2025 changelog (no hand-curation yet, this is the raw output):
https://raw.githubusercontent.com/confident-ai/deepeval/refs...
I am curious: does this still seem too noisy in your opinion, or is it getting closer? And what would you want to see for breaking changes/migrations to make it actually useful?
I now have 2024 & 2025 generated; to fully hand-curate two years of history just wasn’t practical, so I’m trying to get the "80% draft" automatically and then curate over time.
Claude - write some plausible release notes that management will buy but make no actual sense and save it as xml.
We have our release notes fully automated from git tags, and it's unfortunately useless as people don't actually the right tags on things, so everyone ends up manually editing it.
Yeah, that matches what I have seen: if the upstream metadata isn’t reliable, automation can amplify the mess.
I tried to avoid relying solely on contributors to accurately label or tag things correctly. The script is tag-driven only for release boundaries (version tags), while categorization is derived from PR title & body with optional GitHub metadata. The script is idempotent and preserves edits/omissions so you can correct the few bad ones post-generation.
If you are curious, I am happy to share my script and would be genuinely interested whether it reduces the manual cleanup for your workflow. Also, if you run it with `--ai --github` and a PR body is sparse, it fetches a truncated PR diff and uses that as extra context for the LLM summary.
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.
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?