dsh-recall/AGENTS.md

Working in this repository

master releases itself. Every push runs .gitea/workflows/release.yml, which reads the commit subjects since the last tag, bumps package.json, prepends CHANGELOG.md, tags vX.Y.Z, and publishes the Gitea release with those subjects as the body.

Commit subjects are release input

The subject is both the version decision and the sentence a user reads in the release notes. Write it for that reader:

• feat: … — the change adds a capability. Minor bump: 0.1.0 → 0.2.0.
• feat!: … or fix(x)!: … — the change breaks an existing install. Major bump: 0.1.0 → 1.0.0, and the note lands under Breaking. [major] anywhere in the subject does the same when a ! will not fit.
• fix: …, docs: …, or a plain sentence — everything else. Patch bump: 0.1.0 → 0.1.1.
• [skip release] — this push publishes nothing.

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 from the commits. Pushing to master is the whole trigger — the tag and the release come with it.

Checking before pushing

npm run release:plan     # would this HEAD release? (yes/no)
npm run release:notes    # the exact notes it would publish
npm run test:release     # the checks behind the bump and the notes

The rules in full — the marker table, first-release behaviour, how prose commits are handled — are in the README under Releases.