Conventional Commits Tooling

Also Known As

TL;DR

Explanation

Conventional Commits (feat:, fix:, chore:, BREAKING CHANGE:) enable automated tooling. commitizen: interactive CLI for writing conventional commits. commitlint: lints commit messages in CI and pre-commit hooks. standard-version: bumps version (major/minor/patch) and generates CHANGELOG.md based on commit history. semantic-release: full automation — analyses commits, bumps version, generates changelog, and publishes to npm/Packagist/GitHub Releases. PHP projects: use semantic-release with @semantic-release/changelog and @semantic-release/github. The workflow: write conventional commits → merge to main → CI auto-bumps version → CHANGELOG generated → release tagged.

Common Misconception

Why It Matters

Common Mistakes

• feat: in patch releases — feat: bumps the minor version, not patch.
• Forgetting BREAKING CHANGE in commit footer — must be in footer for major version bump.
• Not enforcing conventions with commitlint — conventions only work if everyone follows them.
• Running semantic-release manually — it should run only in CI to prevent manual tampering.

Code Examples

# Manual release process — error-prone:
# 1. Grep through commits to find what changed
# 2. Manually decide if it is major/minor/patch
# 3. Edit CHANGELOG.md by hand
# 4. Edit composer.json version by hand
# 5. Commit, tag, push
# Mistakes: wrong version, missed entries, stale changelog

# .commitlintrc.json:
{"extends": ["@commitlint/config-conventional"]}

# .releaserc.json (semantic-release):
{"branches": ["main"],
 "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
     "@semantic-release/changelog",
     "@semantic-release/github"
 ]}

# Developer writes:
# git commit -m 'feat(auth): add WebAuthn support'
# Merged to main → CI runs semantic-release:
# Detects 'feat' → bumps 1.5.0 → 1.6.0
# Generates CHANGELOG entry
# Creates GitHub Release
# Publishes to Packagist

References

• ↗ https://semantic-release.gitbook.io/semantic-release/

Tags

Related Terms