59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```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*.
|