git-conventions

Commit Message Format

Follow Conventional Commits:

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

[optional body]

[optional footer(s)]

Types

| Type | When to use | |------------|----------------------------------------------------| | feat | A new feature visible to users | | fix | A bug fix | | docs | Documentation-only changes | | style | Formatting, whitespace — no logic change | | refactor | Code restructuring without behavior change | | test | Adding or updating tests | | chore | Build scripts, CI, tooling — no production code | | perf | Performance improvement | | ci | CI/CD pipeline changes | | build | Build system or dependency changes | | revert | Reverting a previous commit |

Rules

• Use imperative mood: "add" not "added" or "adds"
• Subject line: max 72 characters, no period at end
• Body: wrap at 80 characters, explain why not what
• Footer: reference issues (Closes #123, Fixes #456)
• Breaking changes: add ! after type/scope and BREAKING CHANGE: in footer

Examples

feat(auth): add OAuth2 login with Google

Implement Google OAuth2 flow using passport-google-oauth20.
Session tokens are stored in Redis with a 24h TTL.

Closes #42

fix(api): prevent duplicate webhook deliveries

The webhook dispatcher was not checking for in-flight requests
before retrying, causing duplicate deliveries under load.

Fixes #187

refactor(db)!: migrate from callbacks to async/await

BREAKING CHANGE: All database functions now return Promises
instead of accepting callbacks.

Branching Strategy

main (or master)
  └── develop (optional integration branch)
        ├── feature/short-description
        ├── fix/issue-number-description
        ├── docs/what-is-being-documented
        └── chore/what-maintenance-task

Branch Naming

• Use lowercase with hyphens: feature/add-user-search
• Include issue number when applicable: fix/123-null-pointer
• Keep names short but descriptive
• Delete branches after merging

Pull Requests

• Title follows the same format as commit messages
• Description includes: what changed, why, how to test
• Link to related issues
• Keep PRs focused — one logical change per PR
• Request review from at least one team member
• Resolve all comments before merging

When to Use

Load this skill when:

• Writing commit messages
• Creating branches
• Preparing pull requests
• Establishing git workflows for a new project