# 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.

## 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

```sh
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*.