Skip to content

git-commits.md

Latest commit

 

History

History
113 lines (86 loc) · 4.35 KB

git-commits.md

File metadata and controls

113 lines (86 loc) · 4.35 KB

ITK Git Commit Guidelines

Required Format

Enforced by the kw-commit-msg.py pre-commit hook. Commits that violate the format will be rejected.

PREFIX: Brief description (≤78 chars on subject line)

Longer explanation if needed. Describe *what* changed and *why*,
not just that a tool made the change.

The 78-character subject-line limit is a hard constraint, not a guideline. The kw-commit-msg.py hook rejects commits that exceed it, and CI will reject PRs containing such commits. Count characters before committing. The prefix (e.g., DOC: ) counts toward the 78. When a descriptive subject would exceed the limit, move detail to the commit body — the subject should be scannable in git log --oneline.

Prefixes

Prefix Use for
ENH: New feature or enhancement
BUG: Bug fix
COMP: Compilation fix (warnings, errors)
DOC: Documentation only
STYLE: Formatting, naming, no logic change
PERF: Performance improvement
WIP: Transient commits for development testing only

WIP: on commit subjects is a two-layer opt-in — use it deliberately. The local kw-commit-msg.py hook intentionally accepts WIP: so developers can commit probe tests, A/B experiments, and other work they know is not suitable for main — without renaming the prefix on every iteration. ghostflow-check-main (the GitHub App gating PR merge) then rejects any commit whose subject begins with WIP:, which is the intended safety net: WIP: commits cannot accidentally land on main. Before marking the PR ready for review, remove, reword, fixup, or squash WIP: commits into standard-prefix commits.

To mark an entire PR (rather than individual commits) as work-in-progress, add [WIP] to the PR title — the GitHub "WIP" app gates merging on that string; remove it when the PR is ready.

Commit Message Length

Keep commit messages concise. A 1-line subject plus a short body (≤ ~10 lines) describing what and why is the norm. Long, essay-style commit messages have been explicitly objected to in code review — put expanded rationale in the PR description, not the commit body. The commit should be readable in git log --oneline + a quick git show.

Hook Behavior

The pre-commit hook runs clang-format on staged C++ files and modifies them in place if formatting changes are needed. When this happens:

  1. The hook modifies the file(s)
  2. The original commit is aborted
  3. You must re-stage the modified files and recommit

Do not use --no-verify to bypass hooks — the format check exists to keep CI green.

All pre-commit hooks must pass before submitting or updating a PR. This is non-negotiable. If a hook fails, fix the underlying issue — do not disable, skip, or work around the hook. A PR with commits that were not validated by the local hooks will fail CI and waste reviewer time. If the hook environment is broken (e.g., a stale pixi environment), fix the environment first: pixi install or ./Utilities/SetupForDevelopment.sh.

First-Time Setup

Run once after cloning:

./Utilities/SetupForDevelopment.sh

This installs the commit-msg and pre-commit hooks. Without it, commits will not be validated locally.

Commit Attribution

Commit messages describe what changed and why — not how it was produced. AI tool names, model IDs, and tool-specific trailers do not belong in commit messages. Disclose substantive AI assistance in the PR description instead (inside a <details> block).

Full attribution rules (Co-Authored-By, AI disclosure, external context, PR body format) are in attribution.md.

Pre-Commit Checklist for C++ Changes

Before committing any C++ code, an AI agent must complete all three steps:

  1. Review compiler cautions — Read compiler-cautions.md and verify the changed code does not introduce any of the documented pitfalls. Use the Quick-Reference Checklist in that file.

  2. Compile the changed code — Build the affected module(s) locally. See building.md for build instructions. A commit must not introduce a compilation error.

  3. Run relevant tests — Execute the tests that exercise the changed code. See testing.md for how to run a targeted subset with ctest -R <pattern>.