Conventional Commits — Team Guidelines with Lots of Examples

 

The format (one line)

type(scope)!: subject

• type: one of feat, fix, perf, refactor, chore, docs, test, build, ci, style, revert
• scope (optional): focus area like frontend, backend, api, db, billing, search, auth, infra
• !: indicates a breaking change (also add a BREAKING CHANGE: footer in the body)

---

Rules we enforce (team policy)

• Header
  • Max 100 characters
  • No trailing period
• Body (optional but recommended)
  • Leave one blank line between header and body
  • Explain what and why; wrap lines around ~72–100 chars
• Breaking changes
  • Either: feat(scope)!: ...
  • Or add a footer line:
    BREAKING CHANGE: describe impact and migration

---

SemVer mapping (cheat-sheet)

• fix: → PATCH
• feat: → MINOR
• BREAKING CHANGE or ! → MAJOR

---

Copy-paste templates

Simple one-liner

type(scope): short imperative summary

With body, references, and breaking footer

type(scope)!: short imperative summary

Longer body explaining what changed and why. Include context and alternatives
considered if helpful.

BREAKING CHANGE: describe the impact and how to migrate.
Refs: #123, #124

Revert

revert: type(scope): original summary

This reverts commit <sha>.

---

Quick examples (expanded)

Features

• feat(frontend): add dropzone upload with progress
• feat(api): support cursor-based pagination
• feat(auth): refresh-token rotation with inactivity timeout
• feat(search): enable fuzzy matching with trigram index
• feat(billing): add SEPA Direct Debit
• feat(notifications): email templates with MJML
• feat(settings): dark mode toggle and persistence
• feat(reports): export to CSV and XLSX
• feat(files): resumable uploads with chunk retry

Fixes

• fix(backend): parse CSV with semicolon delimiter
• fix(api): return 400 for invalid cursor
• fix(auth): handle expired refresh token gracefully
• fix(db): correct uuid default in migration
• fix(frontend): guard against undefined organization
• fix(logging): redact secrets from error payloads
• fix(cli): ensure --help exits with code 0
• fix(i18n): escape placeholders in translation strings

Performance

• perf(db): batch inserts using COPY
• perf(cache): pipeline Redis writes to reduce RTT
• perf(api): reuse HTTP client to cut TLS handshakes
• perf(images): lazy-load thumbnails on listing page

Refactors

• refactor(api): extract pagination utils
• refactor(auth): isolate token validation middleware
• refactor(db): rename column quantities -> items_json
• refactor(ui): co-locate hooks with feature modules
• refactor(router): flatten nested controllers

Documentation

• docs: update README with versioning instructions
• docs(contributing): add commit message guide
• docs(api): examples for /licenses endpoints
• docs(runbook): add on-call escalation steps

Tests

• test: add unit tests for version endpoint
• test(e2e): onboarding happy-path scenario
• test(api): contract tests for /auth/token
• test(fixtures): generate sample invoices

Build / CI / Chore / Style

• build(docker): switch to multi-stage build
• build(makefile): add target db.reset
• build(nix): pin flake inputs for reproducible builds
• ci(github): cache pnpm installs
• ci(pipeline): run migrations before smoke tests
• chore(deps): bump fastapi from 0.111 to 0.115
• chore(release): 2.0.0
• style(css): normalize heading sizes and spacing
• style: apply Prettier/Black formatting
• chore(lint): enable import order checks

Reverts & Breaking changes

• revert: feat(api): support cursor-based pagination
• feat!: drop Node 16 support
• refactor(api)!: remove deprecated v1 upload endpoints

Example breaking footer

feat(auth)!: enforce PKCE for public clients

BREAKING CHANGE: public clients must use PKCE. Add code_challenge and
code_verifier to the authorization code flow to migrate.

Detailed bug fix

fix(db): prevent transaction deadlock on concurrent updates

Use SELECT ... FOR UPDATE SKIP LOCKED to avoid blocking high-traffic updates
on the same organization row. This reduces average latency by ~35% under load.

---

Scopes: how to pick good ones

Use stable, short labels that match product areas or subsystems:

• Subsystems: api, frontend, backend, db, auth, telemetry
• Feature areas: upload, billing, org, search, alerts, reports
• Tooling/infra: docker, nix, github, pipeline, helm, infra

Avoid one-off misc scopes; favor consistent names across repos.

---

Git tips (handy oneliners)

Commit with a body

git commit -m "feat(api): support cursor-based pagination"            -m "Adds stable cursor encode/decode and validates limit."            -m "Refs: #123"

Amend the last commit message

git commit --amend

Revert a commit

git revert <sha>

---

Recommended tooling

• Linting: @commitlint/cli + @commitlint/config-conventional
• Hooks: Husky or native Git hooks to enforce on commit/push
• Releases: semantic-release (or similar) to tag & generate changelogs