Conventional Commits
Specification for structured commit messages that enable automated changelog generation and semantic versioning.
Quick Reference
Format
[optional body]
[optional footer(s)]
Common Types Type Purpose SemVer feat New feature MINOR fix Bug fix PATCH docs Documentation only - style Formatting, no code change - refactor Code change, no feature/fix - perf Performance improvement - test Adding/fixing tests - build Build system, dependencies - ci CI configuration - chore Maintenance tasks - revert Revert previous commit - Breaking Changes feat!: send email when product shipped
feat(api)!: change response format
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
Examples Simple Commits feat: add user authentication fix: resolve memory leak in cache docs: update API documentation style: format code with prettier refactor: extract validation logic perf: optimize database queries test: add unit tests for auth module build: upgrade webpack to v5 ci: add GitHub Actions workflow chore: update dependencies
With Scope feat(auth): add OAuth2 support fix(parser): handle empty arrays docs(readme): add installation guide refactor(api): simplify error handling
With Body fix: prevent request racing
Introduce a request id and reference to latest request. Dismiss incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are obsolete now.
With Footer fix: correct minor typos in code
Reviewed-by: John Doe Refs: #123
Breaking Change in Footer feat: allow config object to extend other configs
BREAKING CHANGE: extends key in config file is now used
for extending other config files.
Breaking Change with ! and Footer chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
Revert Commit revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
Specification Rules MUST Commits MUST be prefixed with a type (feat, fix, etc.) Type MUST be followed by colon and space Description MUST immediately follow the colon and space feat MUST be used for new features fix MUST be used for bug fixes Breaking changes MUST be indicated by ! before : OR BREAKING CHANGE: footer BREAKING CHANGE MUST be uppercase Footer token MUST use - instead of spaces (e.g., Reviewed-by) MAY Scope MAY be provided after type: feat(parser): Body MAY be provided after description (blank line between) Footer MAY be provided after body (blank line between) Types other than feat and fix MAY be used ! MAY be used with BREAKING CHANGE: footer Case Sensitivity Types: case-insensitive (lowercase recommended for consistency) BREAKING CHANGE: MUST be uppercase BREAKING-CHANGE: synonym for BREAKING CHANGE SemVer Mapping Commit Type SemVer Bump Version Change fix: PATCH 1.0.0 → 1.0.1 feat: MINOR 1.0.0 → 1.1.0 BREAKING CHANGE or ! MAJOR 1.0.0 → 2.0.0
Breaking changes override type — fix!: results in MAJOR bump.
Changelog Integration
Conventional Commits map directly to changelog entries:
Commit Type Changelog Section feat Added fix Fixed perf Changed refactor Changed docs (usually omitted or Changed) BREAKING CHANGE Highlight in Changed/Removed revert Removed or Fixed Security fixes Security Automated Changelog Generation
Tools like conventional-changelog, semantic-release, or release-please can:
Parse commit messages Generate CHANGELOG.md entries Determine next version number Create releases automatically
See changelog skill for CHANGELOG.md format.
Common Patterns Feature Development git commit -m "feat(users): add profile page" git commit -m "feat(users): add avatar upload" git commit -m "test(users): add profile page tests" git commit -m "docs(users): document profile API"
Bug Fix with Reference git commit -m "fix(auth): resolve session timeout (#142)"
Breaking Change Flow
Deprecate first
git commit -m "feat(api): add v2 endpoint
DEPRECATED: /api/v1/users will be removed in next major version"
Later, remove
git commit -m "feat(api)!: remove v1 endpoints
BREAKING CHANGE: /api/v1/ endpoints have been removed. Use /api/v2/ instead."
FAQ What if commit fits multiple types?
Split into multiple commits when possible. This makes history more organized.
What if I used wrong type?
Before merge: git rebase -i to edit history. After release: not critical — commit will be missed by automated tools.
Do all contributors need to use this?
No. Use squash merging and maintainers can write proper message for the merge.
How to handle reverts?
revert:
Refs:
Git Configuration Commit Template
Set up git to use template:
git config commit.template .gitmessage
See assets/commit-msg.template for template file.
Pre-commit Validation
Use assets/validate-commit-msg.sh with git hooks or CI.
Tools Tool Purpose commitlint Lint commit messages commitizen Interactive commit helper conventional-changelog Generate changelogs semantic-release Automated releases release-please GitHub release automation Critical Prohibitions Do not use vague messages ("fix stuff", "update", "wip") Do not mix unrelated changes in single commit Do not omit breaking change indicators Do not use non-standard types without team agreement Do not forget blank line between description and body Agent Workflow for Commit Messages
MANDATORY: Before proposing branch name, commit message, or PR description, the agent MUST:
Check all changed files using git status or git diff --name-only Review actual changes using git diff (staged and unstaged) Analyze ALL modifications — not just the files mentioned in conversation Base proposals on complete changeset — include all affected files, not partial list Workflow Steps
Step 1: Get list of all changed files
git status --short
Step 2: Review actual changes (for unstaged)
git diff
Step 3: Review staged changes
git diff --staged
Step 4: Use the complete changeset to propose:
- Branch name
- Commit message
- PR description
Output Format
When user asks for commit message, provide:
Branch name options (3 variants using conventional prefixes) Commit message variants (short/medium/detailed) PR description (summarized, not duplicating full changelog)
All proposals MUST be based on the actual git diff output, not assumptions.
Links Official specification: https://www.conventionalcommits.org/en/v1.0.0/ Semantic Versioning: https://semver.org/spec/v2.0.0.html Related: changelog skill — CHANGELOG.md format Templates commit-msg.template — Git commit message template validate-commit-msg.sh — Validation script