Skip to main content

Commit messages

Commit messages are read more often than they're written. Aim for clarity over completeness.

Drafted from planning · v0.1

Subject line​

  • 50 chars or less
  • Imperative ("Add audit chain verification", not "Added" or "Adds")
  • No trailing period
  • Optionally prefixed with the slice or area:
    • slice-1: Add audit chain verifier
    • customers: Block delete when bikes attached
    • migrations: Add service_categories table
    • bible: Fix C4 component diagram

Body​

Optional, separated by a blank line. Explain why if the subject doesn't make it obvious. Don't repeat the diff.

slice-4: Tighten ticket delete blocker

Previously only blocked picked_up state. A ticket in in_progress
with line items and transactions can be a real ongoing record that
shouldn't be deletable. New blocker covers:
- Any line items
- Any linked transaction
- Status != dropped_off

Fixes the case where ticket #2506 was deletable in error.

Co-authorship attribution​

When pair-programming with Claude Code:

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add as a trailer at the end of the body.

When to split a commit​

A commit should be one logical change. Splits make sense when:

  • A refactor and a feature land together — split them
  • Two unrelated bug fixes — split them
  • Schema migration + the endpoint that uses it — keep together (they don't make sense apart)

Goal: each commit is independently revertable without breaking the build.

When to amend​

  • Last commit, not pushed yet, tiny fix (typo, missed line) — git commit --amend
  • Already pushed — never amend; new commit

Don't amend to hide a mistake from history. The whole point of git is the history.

When to rebase​

  • Local feature branch keeping up with main — git rebase main
  • Cleaning up local history before PR — git rebase -i HEAD~N (but never use -i in interactive mode for this tool; do it manually)

Never rebase a shared branch.

Examples from this repo​

Good:

  • slice-1: Initial PIN hashing + sign-in overlay
  • service-tickets: Fix discount_cents NOT NULL violation
  • bible: Add ADR-0014 per-staff permission overrides

Bad:

  • Fix bug (which bug?)
  • WIP (squash before pushing)
  • Update files (which files? why?)
  • Final fix for the thing we talked about (no context for future-you)

See also​