Commit messages that cut releases

A version number looks like decoration. It’s a promise. Semantic Versioning spells it out: bump the MAJOR version “when you make incompatible API changes”, the MINOR version “when you add functionality in a backward compatible manner”, and the PATCH version “when you make backward compatible bug fixes”.

People’s tools act on that promise without asking. When you npm install a package, npm writes the dependency with a ^ in front by default. And ^1.4.2 means >=1.4.2 <2.0.0: every minor and patch release is accepted automatically, on the next install, by every project that depends on you. A major release is the only kind nobody gets by accident.

So the question that matters at release time is: is anything in here breaking? Answering it by hand, for every release, from memory, is how breaking changes ship as patches.

Say it in the commit

Conventional Commits moves the answer to the moment you know it best: when you write the change. Every commit message starts with a type:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• fix: patches a bug. It lines up with a PATCH release.
• feat: adds a feature. It lines up with a MINOR release.
• A ! after the type or scope, or a BREAKING CHANGE: footer, marks a breaking API change. It lines up with MAJOR - whatever the type.
• Other types - docs:, chore:, refactor:, test:, ci: and so on - are allowed and “have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE)”.

Two separate commits, straight from the spec’s examples. A ! in the first line:

feat(api)!: send an email to the customer when a product is shipped

A BREAKING CHANGE: footer:

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Types aren’t case-sensitive, but BREAKING CHANGE must be uppercase (BREAKING-CHANGE means the same thing). This site’s own repository is a real example: run git log --oneline in it and nearly every commit starts with a type such as feat:, fix:, docs:, chore: or ci: - the rest are merge commits.

Let a robot read them

release-please reads those messages on your main branch and keeps a release PR open: a pull request that bumps the version and adds a CHANGELOG entry for everything since the last release. Each push updates it. When you merge it, release-please tags the commit and creates a GitHub release. Publishing - to npm, a registry, an app store - stays your job, triggered by that release.

Its defaults follow the spec: fix proposes a patch, feat a minor, and anything marked breaking a major. The releasable units are feat, fix and deps commits (the README adds docs for Java and Python), so in most projects a week of chore: and docs: commits opens no release PR at all. In the CHANGELOG, breaking changes get their own section at the top - release-please’s own changelog shows one under ### ⚠ BREAKING CHANGES - followed by Features and Bug Fixes.

Try it

Your package is at v1.4.2, and your users installed it with ^1.4.2. Make four changes, write a message for each, and merge the release PRs. The release PR below only ever reads what you type.

Details that bite

• Squash merges. The release-please README highly recommends squash-merging for a linear history, and both squash and merge commits work. With a squash, the one commit that lands is the one release-please reads - so that message has to be conventional, not just the commits inside the PR.
• Overriding the number. A commit with Release-As: 2.0.0 in its body opens a release PR for exactly that version.
• Before 1.0.0. SemVer says “Major version zero (0.y.z) is for initial development. Anything MAY change at any time.” By default a breaking change still takes release-please from 0.x to 1.0.0; its bump-minor-pre-major option (off unless you set it) keeps breaking changes as minor bumps while you’re below 1.0.0. And note that npm’s ^0.2.3 only accepts 0.2.x - caret ranges are already cautious below 1.0.
• This site doesn’t use it. A website has no one pinning ^1.4 - visitors always get the latest page. Release automation pays off when other code depends on yours: libraries, CLIs, APIs, Helm charts.

on:
  push:
    branches:
      - main
permissions:
  contents: write
  issues: write
  pull-requests: write
name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: simple

git commit --allow-empty -m "feat: first release-please release"
git push