conventional-commits

name conventional-commits description Use when creating git commits, writing commit messages, or following version control workflows Conventional Commits Structured commit message format for version control that provides clear, readable project history. Overview The Conventional Commits specification provides: Automated changelog generation - Tools can parse commits to generate CHANGELOG.md Semantic versioning - Commit types map to version bumps (feat → minor, breaking → major) Clear project history - Standardized format makes git log readable Automated releases - CI/CD can trigger releases based on commit types Quick Reference Type Use For Version Bump feat New feature MINOR fix Bug fix PATCH docs Documentation only PATCH style Formatting, no logic change PATCH refactor Code restructuring, no behavior change PATCH perf Performance improvement PATCH test Adding or updating tests PATCH build Build system or dependencies PATCH ci CI/CD configuration PATCH chore Maintenance, no user-facing change PATCH revert Revert a previous commit PATCH Format <type>[optional scope]: <description> [optional body] [optional footer(s)] Rules: Type is required Scope is optional - use parenthesized section affected: (api) , auth) , parser) Description is required Keep description concise, imperative mood, lowercase, no trailing period Body and footer are optional Separate subject from body with blank line Wrap body at 72 characters Examples feat: add user authentication Implement JWT-based authentication with login/logout endpoints. Includes password hashing and session management. Closes: #123 fix(api): handle null response from server Previous implementation crashed when server returned null. Now returns empty result set. Assisted-by: GLM 4.6 via Claude Code feat(storage)!: change bucket listing API BREAKING CHANGE: bucket list now returns async iterator instead of array. Update all callers to use for-await. refactor(core): simplify error handling Consolidate duplicate error handlers into single utility. No behavior changes - internal cleanup only. revert: feat(auth): add OAuth support This reverts commit 8b5a1c2. OAuth provider changed their API and we need to redesign integration. Breaking Changes Indicate breaking changes in two ways: Option 1 : Add ! after type/scope feat(api)!: remove deprecated endpoint Option 2 : Add BREAKING CHANGE: footer feat(api): remove deprecated endpoint BREAKING CHANGE: endpoint no longer exists. Use newEndpoint instead. AI Attribution AI agents must disclose their assistance in the commit footer: Assisted-by: [Model Name] via [Tool Name] Examples: Assisted-by: GLM 4.6 via Claude Code Assisted-by: Claude Opus 4.5 via claude.ai Common Mistakes Mistake Why Wrong Correct Added login feature Past tense, capitalized feat: add login feature fix bug. Trailing period fix: resolve login error update Missing type chore: update dependencies feature:add-auth Missing space after colon feat: add authentication FEAT: big change Uppercase type feat: add authentication Multi-line description no blank line No separation Add blank line after subject Body Guidelines What : Motivation for the change (vs. code comments describe HOW) Contrast : Explain the WHY and WHAT, not code details Wrap at 72 characters for readability in git log feat(summarization): add support for nested bullet points Previous implementation only flattened all content. Now preserves hierarchy by respecting indentation levels. Users can now create structured summaries with parent-child relationships. Closes: #456 Footer Guidelines Use footers for: Breaking changes : BREAKING CHANGE: detailed explanation Issue references : Closes: #123 , Fixes: #456 , Refs: #789 AI attribution : Assisted-by: Model via Tool Multiple footers separated by blank lines: feat: add batch upload Implements multipart upload for large files. BREAKING CHANGE: upload() signature changed - now requires options object Closes: #123 Assisted-by: GLM 4.6 via Claude Code Git Commit Flags Required flag: Always use --signoff when committing: git commit --signoff -m "feat: add user authentication" The --signoff flag adds a Signed-off-by trailer to the commit message, indicating the committer has certified the commit follows developer certificate of origin (DCO). Testing Your Commit Before committing, verify: Type is from allowed list Description is imperative mood (add, fix, update) Description is lowercase No trailing period on description Breaking changes marked with ! or footer AI attribution included (if applicable) Body explains WHY not HOW Using --signoff flag