HenryZhang-ZHY Conventional Git Commit
Use this skill to make commit history explicit and machine-readable. The message should communicate the intent of the change, support changelog generation, and map naturally to semantic versioning when feat, fix, or BREAKING CHANGE is used.
For exact wording, examples, and edge cases from the source specification, read references/conventional-commits-1.0.0.md. Use the reference when the user asks about compliance details, SemVer implications, breaking changes, or ambiguous commit types.
Commit message format
<type>[optional scope][optional !]: <description>
[optional body]
[optional footer]
Type selection
Choose the most specific type that describes the primary intent of the commit:
| Change | Type |
|---|---|
| Adds a new capability | feat |
| Patches a bug | fix |
| Improves an existing implementation without adding a feature or fixing a bug | improvement |
| Improves performance | perf |
| Refactors code without changing behavior | refactor |
| Adds or changes tests only | test |
| Changes documentation only | docs |
| Changes formatting only | style |
| Changes dependencies, packaging, or build configuration | build |
| Changes CI workflows | ci |
| Performs maintenance that does not fit another type | chore |
Process
- Inspect the changes being committed, preferably from the staged diff when available.
- Identify the primary intent. If the commit mixes unrelated intents, suggest splitting it before writing the final message.
- Choose the commit type from the table.
- Add a scope only when it gives useful context, such as
parser,auth,docs, ordeps. - Write a concise imperative description after
:. The description should complete the phrase "This commit will..." - Add a body only when the reason, tradeoff, migration note, or behavioral detail would help future readers.
- Add footers for issue links, breaking changes, pull requests, reviewers, or required trailers.
- Verify the final message matches the format before running
git commit.
Breaking changes
Use ! in the type/scope prefix, a BREAKING CHANGE: <description> footer, or both when the commit introduces a breaking API or user-facing compatibility change.
- Put
!immediately before the colon, such asfeat(api)!: change the response format. - When using a footer, put
BREAKING CHANGE: <description>in the footer section. - Keep
BREAKING CHANGEuppercase exactly. - If
!is present, theBREAKING CHANGE:footer may be omitted and the subject description describes the breaking change.
Footer and trailer handling
- Start each footer with a token followed by
:or#; replace whitespace in tokens with-, except thatBREAKING CHANGEis also valid. - Footer values may span multiple lines and end when the next valid footer token begins.
- Preserve required trailers such as
Co-authored-by. - If there is both a body and footers, separate them with one blank line.
- If there is no body, place footers one blank line after the subject.
Examples
Feature with breaking change:
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Breaking maintenance change with !:
chore!: drop Node 6 from testing matrix
BREAKING CHANGE: dropping Node 6 which hits end of life in April
Documentation-only change:
docs: correct spelling of CHANGELOG
Scoped feature:
feat(lang): add polish language
Fix with issue footer:
fix: correct minor typos in code
See the issue for details on the typos fixed.
Closes #12