Skip to main content

Pre-commit policy

Normative pre-commit expectations for A2C-governed software repositories. Recorded as ADR-0001.

Model​

ModeScopeWho initiates
Day-to-dayChanged or staged filesLocal hooks on commit; CI on MR/commit diff
Deliberate cleanupEntire repositoryDevelopment team, manually (pre-commit run --all-files)

After a deliberate full-tree cleanup and its resulting commit, resume normal changed-file enforcement.

Requirements​

1. Shared configuration​

  • Every A2C-governed software repository must version .pre-commit-config.yaml appropriate to its language or stack.
  • Treat the configuration as standard engineering rails — install hooks during project bootstrap.
  • Must include shared A2C pre-commit hooks (check-changelog minimum) — ADR-0003.
  • Prefer reusing A2C templates and stack-profile examples over one-off hook sets.

2. Changed files by default​

Local: installed hooks run on staged files at commit time. Before push, verify the files you changed (for example pre-commit run on staged paths).

CI: run pre-commit on the changed-file set for the pipeline context — merge-request diff or commit range — not --all-files by default.

Intent: enforce standards on new and modified work without punishing untouched legacy files.

3. Manual --all-files only​

pre-commit run --all-files is allowed and sometimes necessary. Use it when the team explicitly chooses repository-wide cleanup.

Consider a manual full-tree run when:

  • adding pre-commit to a repository that previously had none
  • introducing new hooks or materially tightening existing rules
  • onboarding legacy code onto A2C rails after adoption
  • recovering from hook configuration changes that affect the whole tree

Do not use --all-files as default CI behavior.

4. Fast feedback​

Keep hooks fast enough for frequent commits. Prefer:

  • formatting and file hygiene
  • linting and simple static checks
  • secret detection
  • very fast tests only when appropriate

Keep heavy or slow test suites in CI jobs or manual workflows outside the commit path unless the project explicitly decides otherwise.

Project checklist​

See templates/pre-commit/policy-checklist.md.

This repository​

a2c-workflow dogfoods this policy: .pre-commit-config.yaml includes a2c-pre-commit-hooks (check-changelog), local hooks run on staged files, and GitLab CI runs pre-commit on changed files. See development-workflow.md.