Conventional Commits Tooling
debt(d5/e3/b5/t5)
Closest to 'specialist tool catches it' (d5). The term's detection_hints show automated: no with code_pattern noting 'Absence or misuse of Conventional Commits Tooling patterns'. Detection requires specialist tools like commitlint to catch malformed commits at commit-time or in CI. Without these tools configured, violations are only caught through code review.
Closest to 'simple parameterised fix' (e3). The quick_fix indicates reviewing documentation and applying to project context. Fixing misuse like 'feat: in patch releases' or 'forgetting BREAKING CHANGE in footer' requires understanding the convention and rewriting commit messages, but this is localized work. Setting up commitlint/semantic-release initially touches config files but is a contained refactor within build tooling.
Closest to 'persistent productivity tax' (b5). Applies to web and cli contexts broadly. Once adopted, conventional commits become a persistent workflow requirement affecting every developer on every commit. The tooling shapes how the entire team writes commits and manages releases. While not architectural, it creates ongoing friction if team members resist the conventions or forget the format.
Closest to 'notable trap' (t5). The misconception explicitly states developers think 'conventional commits are just a style preference' when they actually enable automated semantic versioning. Common mistakes like using 'feat:' expecting a patch release (when it bumps minor) or forgetting BREAKING CHANGE must be in the footer for major bumps are documented gotchas that most developers eventually learn but initially get wrong.
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