Version Control & Commits
Version control is treated as a boundary, not an afterthought: each commit is a small, traceable unit of work, and the act of publishing that work is always a deliberate human step. This chapter defines how commits are shaped, how they connect to tracked work, the strict separation between committing and pushing, and the clean-authorship stance that keeps the history honest.
Commit Granularity & Subjects
Section titled “Commit Granularity & Subjects”A commit captures one coherent change. Splitting work into small, self-describing commits keeps the history readable and makes review, bisection, and reverts cheap.
| Rule | Level |
|---|---|
| A commit MUST represent a single coherent change | MUST |
| The commit subject line MUST be at most 50 characters | MUST |
| The subject SHOULD use the imperative mood and describe the change, not the process | SHOULD |
| Further detail MAY be placed in the commit body, separated from the subject by a blank line | MAY |
Subjects that exceed the limit MUST be shortened rather than truncated by tooling, so the meaning survives.
Traceability to Tracked Work
Section titled “Traceability to Tracked Work”Every commit on a public repository MUST reference a tracked issue, so each change can be traced back to a recorded reason. The reference connects the change to its rationale and to any related discussion.
| Rule | Level |
|---|---|
| Each commit on a public repository MUST reference a tracked issue | MUST |
| The reference SHOULD appear in the commit subject or body using the repository’s issue syntax | SHOULD |
| Work without a corresponding tracked item SHOULD have one opened before the commit lands | SHOULD |
Commit Is Not Push
Section titled “Commit Is Not Push”Committing and publishing are two different acts with two different audiences. A commit is local orientation — a checkpoint that records progress and gives future work a stable reference point. Publishing exposes that work to others and to deployment, and it is always a human decision.
| Rule | Level |
|---|---|
| Committing MUST be treated as local orientation only | MUST |
| Push and deploy MUST always be an explicit human decision | MUST |
| Push and deploy MUST NEVER happen automatically as a side effect of committing or of any automated step | MUST NOT |
| An automated process MAY prepare a push-ready state, but MUST stop and hand the decision to a human | MAY |
This separation guarantees that no change reaches a shared branch or a live environment without someone choosing to send it.
Clean Authorship
Section titled “Clean Authorship”The commit history records who authored a change. It MUST NOT be polluted with machine-generated attribution noise, and pull requests MUST NOT carry promotional footers about the tools used to create them.
| Rule | Level |
|---|---|
| Commits MUST NOT carry AI-attribution trailers | MUST NOT |
| Pull requests MUST NOT carry “generated with”-style footers | MUST NOT |
| Authorship metadata SHOULD reflect the human accountable for the change | SHOULD |
The intent is a history that reads as deliberate human work, free of automated boilerplate.