Git Commits

Git / Commits Skill

Core Philosophy

"Commits tell a story; changelogs tell users what changed."

Write clear, consistent commit messages and changelogs so history is readable and releases are understandable.

Protocol

1. Commit Message Format

Follow Conventional Commits when the project does not specify otherwise:

<type>(<scope>): <short summary>

[optional body]

[optional footer(s)]

Format Rules:

• <type>: Required, lowercase type from list below
• (<scope>): Required, noun describing section of codebase (e.g., api, auth, ui, db)
• <short summary>: Required, imperative mood, lowercase, no period, ~72 chars max
• Breaking changes: Add ! after scope: feat(api)!: drop support for Node 12

Scope Naming:

• Use lowercase nouns (e.g., api, not API)
• Be specific but not too granular (e.g., auth not login-form-button)
• Common scopes: api, auth, ui, db, cli, docs, config, deps, tests, ci, build
• For components: user-service, payment-flow, dashboard
• For features: oauth, search, notifications
• Be consistent across the project (check git log --oneline for existing patterns)

Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert.

• feat: New feature for the user (triggers MINOR bump)
• fix: Bug fix for the user (triggers PATCH bump)
• docs: Documentation only changes
• style: Code style changes (formatting, whitespace, no logic change)
• refactor: Code change that neither fixes a bug nor adds a feature
• test: Adding or updating tests
• chore: Maintenance tasks (deps, tooling, config)
• perf: Performance improvement
• ci: CI/CD configuration and scripts
• build: Build system or external dependencies
• revert: Reverts a previous commit

Breaking Changes:

• Option 1: Add ! after scope: refactor(api)!: drop deprecated endpoints
• Option 2: Footer: BREAKING CHANGE: description of what broke
• Both trigger MAJOR version bump

Body: Use when you need to explain "why", context, or side effects. Leave blank line after summary.

Footers: BREAKING CHANGE: <description>, Fixes #123, Closes #456, Refs #789

Examples:

feat(auth): add OAuth2 social login
fix(api): prevent race condition in user creation
docs(readme): update installation instructions
refactor(db)!: migrate from MySQL to PostgreSQL

BREAKING CHANGE: Database schema incompatible with v1.x
chore(deps): upgrade TypeScript to v5
test(api): add integration tests for user endpoints
perf(search): optimize query with database index

2. Changelog

• Group by type (Added, Changed, Fixed, Removed, Security).
• One line per item; link to PR/commit when possible.
• Put newest entries at the top (or follow existing CHANGELOG style).

3. Release Notes

• User-facing summary of the release.
• Highlights and breaking changes first; then full list or link to changelog.
• Version and date in title or header.

4. Versioning (Semantic Versioning)

Use SemVer (MAJOR.MINOR.PATCH): MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes.

For complete versioning guide: See reference/VERSIONING.md, which covers:

• SemVer format and version bump rules
• Pre-release versions (alpha, beta, rc)
• Determining version from Conventional Commits
• Examples and best practices

5. Tagging and Release Management

Create annotated tags (git tag -a v1.2.3 -m "Release v1.2.3") with v prefix. Use automated tools (semantic-release, release-please) or manual workflow (update version, CHANGELOG, commit, tag, push).

For complete release guide: See reference/RELEASES.md, which covers:

• Tagging releases (annotated tags, naming conventions)
• Automated release workflow (semantic-release, release-please, standard-version)
• Manual release workflow (step-by-step)
• Commands reference (git tag, gh release, npm version)
• Troubleshooting and best practices

Project Conventions:

• Always respect existing project conventions if they differ from this standard
• Check project's CONTRIBUTING.md or git history for established patterns
• If project requires Jira ticket prefixes (e.g., feat(api): PROJ-123 add endpoint), include them
• Scope is required by this standard; if project allows scope-less commits, follow project rules

Reference: Conventional Commits

Checklist

• Type is lowercase and valid (feat, fix, docs, etc.)
• Scope is present and describes codebase section (api, auth, ui, db, etc.)
• Summary is imperative mood, lowercase, no period, ~72 chars max
• Breaking changes use ! after scope or BREAKING CHANGE: footer
• Body explains "why" when needed (leave blank line after summary)
• Footers follow format: BREAKING CHANGE:, Fixes #123, Closes #456
• Changelog/release notes match what actually changed
• Version bump follows SemVer based on change type
• Tag created and pushed for releases (annotated tag with git tag -a)
• GitHub Release created with release notes (if applicable)

Cross-Skill Integration

See also: ci-cd skill for automating releases in CI/CD pipelines.