--- title: Commit Message Standards description: Standard commit message format and quality expectations tags: [git, commits, standards, conventions, conventional-commits] --- # Commit Message Standards ## Metadata **Purpose**: Define Standard commit message format and quality expectations **Applies to**: All Git commits in projects **Version**: 1.0.0 --- ## Instructions ### Conventional Commits Format All commits must follow the **Conventional Commits** specification: ``` (): [optional body] [optional footer(s)] ``` ### Required Elements **Type** (required): Indicates the kind of change - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation changes - `refactor`: Code refactoring (no functional changes) - `test`: Adding or updating tests - `chore`: Maintenance tasks (dependencies, tooling) - `perf`: Performance improvements - `style`: Code style changes (formatting, whitespace) - `ci`: CI/CD configuration changes **Scope** (optional but recommended): Component or module affected - Examples: `auth`, `api`, `ui`, `database`, `config` - Keep lowercase and concise **Subject** (required): Clear, concise description - Use imperative mood ("add" not "added" or "adds") - Start with lowercase letter - No period at the end - Maximum 50 characters - Be specific about what changed ### Quality Criteria **✅ Good commit messages**: - Clearly communicate intent and context - Answer: "What does this commit do and why?" - Use specific, descriptive language - Focus on the "why" not just the "what" **❌ Prohibited patterns**: - Vague messages: "fix bug", "update code", "changes" - WIP commits: "wip", "work in progress", "temp" - Generic messages: "fixes", "updates", "misc" - All caps: "FIX BUG IN LOGIN" - Emoji without clear text (text is primary, emoji optional) ### Character Limits - **Subject line**: ≤50 characters (ideal), ≤72 characters (hard limit) - **Body lines**: Wrap at 72 characters - **Blank line**: Always separate subject from body ### Issue Linking Policy **When issue references are required**: - `feat` - New features (REQUIRED) - `fix` - Bug fixes (REQUIRED) - Breaking changes (REQUIRED) - `refactor` - Large refactorings (RECOMMENDED) - `perf` - Performance improvements (RECOMMENDED) **When issue references are optional**: - `docs` - Documentation-only changes - `chore` - Dependency updates, tooling - `test` - Test-only changes - `style` - Formatting-only changes **Format in footer**: - `Closes #123` - Closes an issue (for features, completed work) - `Fixes #456` - Fixes a bug (for bug fixes) - `Relates to #789` - Related but doesn't close (for partial work) - `Refs #101, #102` - References multiple issues **If no issue exists**: - Create one first for features/bugs - OR provide detailed context in commit body explaining why no issue **Examples**: ``` feat(api): add customer export endpoint Closes #234 ``` ``` fix(auth): resolve session timeout on mobile Multiple users reported session timeouts after 5 minutes of inactivity on mobile devices. Root cause was aggressive token expiration settings. Fixes #456 ``` ### Examples **Good examples**: ``` feat(auth): add two-factor authentication support Implements TOTP-based 2FA for user accounts to enhance security. Users can enable 2FA in account settings and must verify with authenticator app on subsequent logins. Closes #123 ``` ``` fix(api): resolve race condition in order processing Multiple concurrent requests were creating duplicate orders due to non-atomic transaction handling. Added database-level locking to ensure order creation is properly serialized. Fixes #456 ``` ``` docs(readme): update installation instructions for Python 3.11 ``` **Bad examples**: ``` ❌ "fixed stuff" Problem: Too vague, no context ❌ "update code" Problem: Not specific, doesn't explain what or why ❌ "WIP: working on feature" Problem: WIP commits should be rebased before merging ❌ "Added new feature and fixed several bugs and updated docs" Problem: Multiple unrelated changes, should be separate commits ``` --- ## Resources ### Detailed Type Guidelines **feat** - New features or capabilities - Adding a new API endpoint - Implementing a new user-facing feature - Adding support for a new data format - Example: `feat(api): add bulk import endpoint for customer data` **fix** - Bug fixes - Resolving incorrect behavior - Fixing crashes or errors - Correcting data issues - Example: `fix(validation): prevent negative values in quantity field` **docs** - Documentation only - README updates - Code comments - API documentation - User guides - Example: `docs(api): add examples for authentication endpoints` **refactor** - Code restructuring - Extracting functions or classes - Renaming for clarity - Reorganizing file structure - No behavior changes - Example: `refactor(services): extract common validation logic to utilities` **test** - Test additions or updates - Adding missing test coverage - Updating tests for refactored code - Fixing broken tests - Example: `test(auth): add integration tests for 2FA flow` **chore** - Maintenance tasks - Dependency updates - Build configuration - Tooling changes - Example: `chore(deps): update pandas to 2.0.0` **perf** - Performance improvements - Optimization changes - Reducing memory usage - Improving query performance - Example: `perf(database): add index on user_id for faster lookups` ### Edge Cases **Breaking changes**: Use `!` after type or `BREAKING CHANGE:` in footer ``` feat(api)!: change authentication endpoint to use OAuth2 BREAKING CHANGE: The /auth endpoint now requires OAuth2 tokens instead of API keys. Update all clients to use the new flow. ``` **Merge commits**: Auto-generated, acceptable as-is ``` Merge pull request #123 from feature/new-auth ``` **Reverts**: Use `revert:` prefix ``` revert: feat(auth): add two-factor authentication support This reverts commit abc123def456 due to production issues. ``` **Co-authors**: Add in footer ``` feat(analytics): add user behavior tracking Co-authored-by: Jane Doe Co-authored-by: John Smith ``` ### Integration with Tooling **Git hooks**: Use pre-commit hooks to validate format ```bash # .git/hooks/commit-msg #!/bin/sh commit_msg=$(cat "$1") pattern="^(feat|fix|docs|refactor|test|chore|perf|style|ci)(\(.+\))?: .+" if ! echo "$commit_msg" | grep -qE "$pattern"; then echo "Error: Commit message must follow Conventional Commits format" echo "Format: (): " exit 1 fi ``` **Commit templates**: Configure Git to use a template ```bash git config commit.template .gitmessage ``` `.gitmessage`: ``` # (): (max 50 chars) # |<---- Using a Maximum Of 50 Characters ---->| # Explain why this change is being made # |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->| # Provide links or keys to any relevant tickets, articles or resources # Example: Closes #23 # --- COMMIT END --- # Type can be: # feat (new feature) # fix (bug fix) # refactor (code change without feature/fix) # docs (documentation changes) # test (adding/updating tests) # chore (maintenance) # perf (performance improvement) # style (formatting, missing semicolons) # ci (CI/CD changes) # -------------------- # Remember: # - Use imperative mood ("add" not "added") # - Subject starts with lowercase # - No period at end of subject # - Separate subject from body with blank line # - Wrap body at 72 characters # -------------------- ``` ### Personal Patterns **Multi-repo changes**: Reference related commits ``` feat(shared): update data models for new customer schema Related changes: - api-service: abc123 - web-app: def456 ``` **Research experiments**: Use `experiment` scope ``` feat(experiment): implement XGBoost model variant for A/B test ``` **Data pipeline changes**: Be specific about data impact ``` fix(pipeline): correct date parsing in customer import job Previous logic incorrectly parsed ISO dates with timezone offsets, causing records from 11pm-midnight UTC to be assigned wrong dates. Affects ~500 records from 2024-01-15 to 2024-01-20. ```