How to write release notes from commits (Conventional Commits)
Your commit history is the raw material for release notes, not the finished product. Conventional Commits give that raw material enough structure for a tool to draft a changelog, and you still edit the draft before it ships.
Updated Last checked 5 min readOpen-source libraries and packages
The short answer
- Conventional Commits look like
type(scope): description, with!or aBREAKING CHANGE:footer for breaking changes. featmaps to a minor version and an ‘Added’ line,fixto a patch and ‘Fixed’, and a breaking change to a major.- semantic-release, release-please and git-cliff turn these commits into a changelog; GitHub can generate notes from merged pull requests instead.
- Edit the draft: merge related commits, drop internal ones (refactor, test, ci) and add migration steps.
Commit messages that produce good release notes
Each line below is the first line of a commit. The last commit adds a footer, separated from the summary by a blank line.
feat(parser): add parseStream() for large inputs
fix: handle Windows (CRLF) line endings
feat!: require Node.js 20 or later
refactor(parser): split the tokenizer into smaller functions
feat(api): rename the timeout option to timeoutMs
BREAKING CHANGE: timeout was in seconds; timeoutMs is in
milliseconds. Replace timeout: 30 with timeoutMs: 30_000.Changelog generators typically list the text after BREAKING CHANGE: under a breaking-changes heading, so write it as the migration step.
Free tool · no sign-up
Can a coding agent read your changelog?
Paste your repository, a GitHub release or a CHANGELOG.md link. The free converter shows every version, breaking change, migration step and deprecation it can extract, as JSON plus an llms.txt summary.
No AI and nothing stored. Or paste a CHANGELOG.md instead
01Why a raw commit log isn't release notes
A git log is written for reviewers. It includes refactors, test fixes, reverted experiments and ten commits for one feature. Keep a Changelog 2.0.0 puts it bluntly: “Do not use a list of commits as a changelog. It is full of noise.” It's just as direct about generated changelogs: “A generated changelog is raw material at best: a person still has to choose what is notable, group it, and write it for the reader.” The answer isn't to ignore commits; it's to give them enough structure that a tool can sort them, then edit the result.
02The Conventional Commits format
A Conventional Commits message starts with a type, an optional scope in parentheses and a description: fix(parser): handle CRLF line endings. A ! before the colon, or a footer starting with BREAKING CHANGE:, marks a breaking change. Types other than feat and fix are allowed; the Angular-based commitlint config, for example, recommends build, chore, ci, docs, style, refactor, perf and test.
| Commit | Changelog section | SemVer bump |
|---|---|---|
feat: … | Added | Minor |
fix: … | Fixed | Patch |
feat!: …, or any commit with a BREAKING CHANGE: footer | Changed or Removed, marked **Breaking:** (generators often add a separate breaking-changes section instead) | Major |
perf: … | Changed (often shown as Performance) | Depends on your tool's configuration |
docs, refactor, test, ci, chore | Usually left out | None |
The feat → minor, fix → patch and breaking → major mapping comes from the spec and lines up with Semantic Versioning.
03Tools that turn commits into a changelog
| Tool | What it does | A good fit when |
|---|---|---|
| semantic-release | Works out the next version from commits, then publishes the release, its notes and the package from CI. Uses the Angular commit conventions by default. | You want every merge to the main branch released automatically. |
| release-please | Opens a release pull request that updates CHANGELOG.md and the version; merging it creates the GitHub release. It doesn't publish to package managers. | You want a person to decide when to release, and to edit notes in the pull request. |
| git-cliff | A configurable changelog generator for repositories that follow Conventional Commits. | You want full control of the changelog format. |
| Changesets | Contributors add a small change file with a bump type and summary; at release time they're combined into versions and changelogs. | Monorepos, or when commit messages aren't reliable. |
| GitHub generated release notes | Lists merged pull requests, contributors and a compare link, grouped by labels in .github/release.yml. | Your team labels pull requests consistently. |
For setup, monorepo support and what each one publishes, see semantic-release vs release-please vs Changesets. To pull a quick draft out of history without any tool, use plain git commands. For the GitHub release alone, the free LogPulse GitHub Action groups the commits since the last tag by type on every release, with BREAKING CHANGE: footers as migration steps. It's one workflow step, uses: kalmwerk/release-notes-action@v1 (on GitHub).
04Squash merges: the pull request title becomes the commit
If you squash-merge pull requests, the squashed commit message is what these tools read, not the commits inside the pull request. GitHub can default that message to the pull request title, so check titles against the convention during review, or with a CI check such as commitlint.
05Edit the draft before you publish
Generated notes are a first draft. Before you tag:
- Merge related commits into one line per user-visible change.
- Delete internal changes that slipped through: a
fixto a test helper isn't a fix for users. - Rewrite descriptions around what users notice. “Files with CRLF line endings now parse” beats “handle CRLF in lexer”.
- Add a migration step to every breaking change; a commit footer rarely has room for one.
- Add two or three highlights at the top of the GitHub release.
Then compare the result with the Markdown release notes templates and run the open-source release notes checklist.
Before and after
Too vague
Generated straight from the log: fix: lexer crlf · chore: deps · feat: stream · test: fixtures · feat: stream part 2
Specific and actionable
Added: parseStream() parses large files without loading them into memory (#412). Fixed: files with Windows (CRLF) line endings now parse correctly (#405).
Fictional example: use your own verified names, versions and behavior.
LogPulse
Generate release notes with LogPulse
LogPulse is a hosted changelog that people and coding agents can both read. Here's exactly what it can do for the steps above, and what it can't.
Check your changelog, free
Paste a CHANGELOG.md or a GitHub releases link. A deterministic parser (no AI, nothing stored) shows the versions, breaking changes, migration steps and deprecations an agent can extract.
Draft notes from GitHub
Connect a repository: merged pull requests, commits to your default branch and published GitHub releases collect in an inbox. AI drafts a note in the tone you pick, listing breaking changes and deprecations only when the changes clearly show them. Nothing is published until you approve it. 3 AI drafts on Free; unlimited on Open source and Pro. Pro opens soon: .
Publish once, read everywhere
Approved notes go to a hosted changelog and an in-app widget, to email subscribers on Open source and Pro (Pro opens soon), and to a JSON feed and MCP server coding agents can query. CI and agents can publish with an API key.
What it doesn't do: LogPulse doesn't tag releases, bump versions, publish to npm or PyPI, or write CHANGELOG.md back to your repository; keep your release tooling for those. AI drafts can miss context, so review them like a pull request.
Before you publish
- The commit (or pull request title) convention is documented in CONTRIBUTING.md
- Every incompatible change uses ! or a BREAKING CHANGE: footer
- The generated draft is edited: merged, trimmed and rewritten for users
- Every breaking change has a migration step
- The version bump matches the changes (major for anything breaking)
Common questions
Do I need Conventional Commits to generate release notes?
No. GitHub can generate notes from merged pull requests and labels, and Changesets uses change files instead of commit messages. Conventional Commits help most when you want both the version number and the changelog derived from history.
What if a contributor forgets the convention?
If you squash-merge, fix the pull request title before merging. Many projects add a CI check that lints pull request titles or commit messages; commitlint is a common choice.
Should chore and refactor commits appear in release notes?
Usually not, because nothing changes for users. If a refactor changes behavior or performance in a way people notice, describe that effect under Changed.
Can AI write release notes from my commits?
It can draft them. LogPulse's AI drafts read merged pull requests, commits and GitHub releases from a connected repository and write a note in the tone you choose; you review and approve it before anything is published. Treat any AI draft like a pull request and check each claim against the diff.
Sources
Facts last checked against these sources on .
Read next
Keep a Changelog vs GitHub Releases
CHANGELOG.md or GitHub Releases? See them side by side, when to use each, and how to keep both in sync with release.yml. Includes a CHANGELOG.md skeleton.
Read the guide Breaking changes, deprecations and versioningSemantic versioning cheat sheet for changelogs
Which change needs a major, minor or patch bump? A cheat sheet of 12 common changes with the changelog line for each, plus 0.x and prerelease rules.
Read the guide Open-source libraries and packagesHow to write release notes for open-source libraries
How to write release notes: a copy-paste template, 3 examples (library, CLI, breaking change), a 7-point checklist and how Django and Node.js do it.
Read the guide Open-source libraries and packagesHow to keep a changelog for an npm package
Where npm users look for changes, how to keep versions, git tags and headings in sync, ship prereleases without moving latest, and deprecate old versions.
Read the guide Open-source libraries and packagessemantic-release vs release-please vs Changesets (and git-cliff)
How semantic-release, release-please, Changesets and git-cliff pick the next version, write CHANGELOG.md, create GitHub releases and publish, from their own docs.
Read the guideMore guides: open-source libraries and packages
- Changelog vs release notes: what's the difference?
- CHANGELOG.md format, explained line by line
- Release notes templates in Markdown
- How to generate a changelog from git commits
- How to keep a changelog for a Python package on PyPI
Tools and resources
- Developer tool changelog template
- How to generate a changelog from git commits
- Free tool: convert a CHANGELOG.md or GitHub release to JSON
- Free GitHub Action: release notes from your CHANGELOG.md on every tag
- kalmwerk/release-notes-action on GitHub: the Action's code and releases
- LogPulse developer docs: feed, API and MCP server
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.