From conventional commits to changelog — the full pipeline

What are conventional commits?

Conventional Commits is a commit-message convention that makes history machine-readable: each message starts with a type (feat, fix, chore, docs…), an optional scope, and a description — with ! or a BREAKING CHANGE: footer marking breaking changes:

feat(auth): add SAML single sign-on
fix(webhooks): prevent double-fire on retry
feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: v1 REST endpoints have been removed; migrate to v2.

Because types are machine-parseable, tooling can derive two things from history alone: the next semantic version (fix → patch, feat → minor, breaking → major) and a changelog grouped by type.

How do you generate a changelog from conventional commits?

The standard pipeline has four stages, all runnable in CI:

• 1. Enforce the convention — commitlint + husky reject non-conforming messages at commit time; a CI check catches the rest.
• 2. Parse history — on merge to main, semantic-release (or standard-version / release-please) reads commits since the last tag.
• 3. Version and tag — the tool computes the next SemVer, tags the release, and updates CHANGELOG.md with commits grouped under Features / Bug Fixes / Breaking Changes.
• 4. Publish — the same run creates the GitHub release and, for libraries, publishes the package.

When the discipline holds, this is excellent automation: versioning, tagging, and a changelog with zero release-day work, entirely from free tooling.

Where does the conventional-commits pipeline break down?

Three failure modes show up repeatedly in real teams:

The discipline tax never ends. The changelog is only as good as the worst commit message in the release. Every engineer, every contractor, every squash-merge must follow the convention forever — and the moment someone types fix: stuff, that is what your customers read.

The output is commit prose. These tools reorganize commit messages; they do not rewrite them. fix(webhooks): prevent double-fire on retry is a fine commit and a poor customer sentence. For developer-facing libraries that is acceptable; for a SaaS changelog page it reads like a build log.

Commit granularity is wrong for announcements. One feature is often ten commits, and one commit sometimes contains three unrelated fixes. Customers think in shipped capabilities — which map to merged pull requests, not commits.

When is PR-based AI generation the better trade?

When your changelog audience is customers rather than developers, and your unit of shipping is the merged PR. The AI approach inverts the pipeline: instead of enforcing structure before the fact, it takes the context your team already writes — PR titles, descriptions, labels — and has a language model draft categorized, benefit-first notes after the release exists. No commit convention, no enforcement tooling, and the output is prose written for readers (see the phrasing rules in how to write release notes users actually read).

Honest comparison — pick by audience and discipline:

The two are not exclusive: plenty of teams run semantic-release for versioning and tagging, and let ShipNotes write the human-facing notes from the PRs behind each tag — the release event is the same trigger for both (pipeline details).

Related reading

• The complete guide to changelogs for SaaS products — the pillar guide, including formats and distribution
• How to write release notes users actually read — the writing craft
• ShipNotes getting started — the PR-based pipeline, set up in ten minutes