Lorixen.
EN

Commit messages that write your release notes for you

Short answer: If your release notes are written from memory and version numbers are chosen by gut feel, a commit message convention can do both jobs for you. The Conventional Commits format starts each message with a type, such as fix: or feat:, and marks breaking changes explicitly. Release tools read those messages to decide whether the next version is a patch, minor or major release and to build a draft changelog grouped by type. Adopt it gradually: agree the types, check messages automatically, and keep a human review of the generated notes before they reach customers.

The problem it solves

In many small teams the commit history reads like "updates", "fix", "more changes" and "wip". When release day comes, someone scrolls through pull requests trying to remember what changed. Release notes miss things, and nobody is sure whether a change could break a client's integration.

The Conventional Commits specification describes itself as a lightweight convention on top of commit messages that makes it easier to write automated tools on top of the history. It lists the benefits plainly: automatically generating changelogs, determining a semantic version bump from the types of commits, communicating the nature of changes, and triggering build and publish processes.

The format in practice

A commit message follows this shape:

type(optional scope): short description

optional body

optional footers

The core rules from the spec:

  • fix: patches a bug and corresponds to a patch release.
  • feat: adds a feature and corresponds to a minor release.
  • A breaking change is marked either with ! after the type or scope, as in feat(api)!: remove legacy endpoint, or with a BREAKING CHANGE: footer. Either corresponds to a major release, whatever the type.
  • Other types are allowed. The spec mentions a widely used set, including build, chore, ci, docs, style, refactor, perf and test, which don't affect the version on their own.
  • A scope in brackets adds context, such as fix(checkout): or feat(bookings):.
  • Footers follow a format similar to Git trailers, for example Refs: #123.

For a business app, scopes that match areas of the product make the generated notes much easier to read: checkout, admin, emails, api.

What the automation does

Release tools that understand the convention typically:

  1. find the commits since the last release tag,
  2. work out the next version from the highest-impact change,
  3. group the commits into sections such as "Features" and "Bug fixes",
  4. create a tag and a draft release or changelog entry.

Because the version follows directly from the messages, a breaking change marked with ! can't slip out as a minor update.

Making it stick

A convention only helps if messages actually follow it.

Check messages automatically. commitlint checks commit messages against a configuration, and its setup guide notes that it needs a commit-msg hook, which you can install with a Git hooks manager such as Husky. Add the same check in CI so commits made without the hook are caught.

Use squash merges if your team prefers freedom. The spec's FAQ points out that with a squash-based workflow, maintainers can write a proper conventional message when merging a pull request, so casual contributors don't have to follow the format in every small commit. Many teams then check the pull request title instead, because it becomes the squash commit message.

Fix mistakes before release. The spec suggests editing history with git rebase -i if the wrong type was used before merging or releasing. After a release, correct the generated notes instead.

Keep customer notes human

Commit messages are written for developers. "fix(checkout): handle null region in tax lookup" is accurate but means nothing to a customer. A sensible split:

  • Technical changelog: generated automatically from commits, kept in the repository or release page for your team and technical clients.
  • Customer release notes: written or edited by a person from the generated list, in plain language, leaving out internal changes like refactors and CI tweaks.

The generated list makes the human version faster and more complete, because nothing is forgotten.

Rolling it out

  1. Agree the types and scopes in a short document in the repository. Keep the list small.
  2. Start from the next release. Don't rewrite old history.
  3. Add the commit or pull request title check with a clear error message linking to your document.
  4. Run the release tool in "dry run" mode for a couple of releases and compare its output with what you would have written.
  5. Switch on tagging and draft notes once the team trusts the output.

Common pitfalls

  • Everything becomes chore:. If people choose the vaguest type to avoid thinking, the notes go empty. Review types in code review like any other part of the change.
  • Breaking changes aren't marked. The convention depends on people knowing what "breaking" means for your users. Agree examples: a removed API field, a changed webhook format, a required new setting.
  • One commit, many changes. Smaller, focused commits produce better notes.

An illustrative example

A web agency in Boston maintains a booking platform used by several clinics, and clients complain that updates arrive without warning. The team adopts Conventional Commits with scopes for bookings, payments, emails and api, checks pull request titles in CI, and uses squash merges. Their release tool proposes version numbers and a grouped changelog. A project manager turns each draft into a short client-facing note, and API changes marked with ! trigger a direct email to clients who integrate.

FAQ

Does every developer have to learn the format?

With squash merges and a title check, mostly only the person merging does.

Can we use our own types?

Yes. The spec allows extra types; only fix, feat and breaking-change markers affect the version.

Does this work for apps that don't use semantic versioning?

You still get grouped release notes, even if your app store version numbers follow a different scheme.

What if we already have a changelog file?

Keep it and let the tool add new entries at the top from the next release.

If your release notes and version numbers depend on someone's memory and you'd like them generated reliably, tell us how you release today.

Sources

WhatsAppBook a call