Conventional Commits & Automated Releases
A tiny commit-message convention that machines can parse into changelogs and semantic version bumps.
Conventional Commits is a lightweight standard for commit subjects: a type, an optional scope, and a short description. It reads well for humans and, crucially, tools can parse it to generate changelogs and pick the next version number automatically.
The shape
<type>(<optional scope>): <description>
[optional body]
[optional footer]Common types
feat:— a new feature (bumps the MINOR version).fix:— a bug fix (bumps the PATCH version).docs:,test:,refactor:,chore:,ci:— no version bump.
Breaking changes
Add a ! after the type (feat!:) or a BREAKING CHANGE: footer to trigger a MAJOR bump. Tools like semantic-release or release-please read these to tag releases and write the changelog with zero manual effort.
Example
# A feature — bumps the MINOR version automatically
git commit -m "feat(auth): add passkey sign-in"
# A fix — bumps PATCH
git commit -m "fix(cart): prevent negative quantities"
# A breaking change — bumps MAJOR
git commit -m "feat(api)!: drop deprecated v1 endpoints" \
-m "BREAKING CHANGE: clients must migrate to /v2."When to use it
- A team uses semantic-release with Conventional Commits so every merge to main automatically computes the next semver version and publishes a changelog.
- A developer marks a commit with BREAKING CHANGE in the footer so the automated release tool knows to bump the major version number.
- A contributor uses the 'fix' type prefix so the CI pipeline distinguishes bug fixes from features when generating the GitHub release notes.
More examples
Conventional Commit with breaking change
The ! after the scope and the BREAKING CHANGE footer both signal a major version bump to tools like semantic-release and release-please.
git commit -m "feat(api)!: remove v1 endpoints
Migrate to v2 REST API. All /v1/* paths return 410 Gone.
BREAKING CHANGE: /v1/users and /v1/posts are removed."Install and run semantic-release
Installs semantic-release with the plugins needed to analyse commit types and publish GitHub Releases automatically.
npm install --save-dev semantic-release \
@semantic-release/commit-analyzer \
@semantic-release/release-notes-generator \
@semantic-release/github
# .releaserc.json
cat .releaserc.json
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/github"
]
}GitHub Actions workflow for auto-release
Runs semantic-release on every push to main; it reads commit messages, decides the version bump, and publishes a GitHub Release automatically.
name: Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
issues: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Discussion