gh-bradleyboehmke-brads-marketplace-git-workflow/skills/commit-message-standards.md

title, description, tags

title	description	tags
Commit Message Standards	Standard commit message format and quality expectations	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:

<type>(<scope>): <subject>

[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 <jane@example.com>
Co-authored-by: John Smith <john@example.com>

Integration with Tooling

Git hooks: Use pre-commit hooks to validate format

# .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: <type>(<scope>): <subject>"
  exit 1
fi

Commit templates: Configure Git to use a template

git config commit.template .gitmessage

.gitmessage:

# <type>(<scope>): <subject> (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.