diff --git a/AGENTS.md b/AGENTS.md index 0e50364..9f05d0a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,25 @@ release notes. Write it for that reader: `feat` has to be a word, so `Fix the feature flag leak` is a patch. Only the subject line is read; the body is not. +## Commit as you go + +Commit each coherent change as you finish it, not once at the end of a session: + +- **A commit is the unit the release is built from.** The subject becomes a line + in the release notes and the version bump for that push, so a session's work + squashed into one commit is one note that describes none of it well. +- **One change, one concern.** A fix and a feature are two commits even when they + touch the same file, because they are two different lines in the notes and two + different reasons for a reader to care. +- **Run `npm test` before each commit**, so no commit in the history is a state + the suite would have refused. +- **Do not batch unrelated work to save commits.** The cost of committing as you + go is a little more care; the cost of not doing it is a release log nobody can + read and a push that cannot be bisected. + +Work still in progress is committed too — the repository is the record, and a +half-finished change kept in the working tree is a change with no history. + ## The release job owns the version and the changelog `package.json`'s `version` and `CHANGELOG.md` are the job's to write, derived