Changelogs
A release's notes are written before it is released: every change adds its own line as it merges, so when the version goes out there is nothing left to write.
A module's
Each module keeps a CHANGELOG.md. Its top section is the version its main
carries — the next one to be released — and every pull request adds a line to
it, linking the pull request:
## 1.7.0
- Sign-in links expire after 15 minutes ([#42](https://github.com/fairgarden/id/pull/42))
- Passkeys can be renamed ([#45](https://github.com/fairgarden/id/pull/45))
## 1.6.0
- ...
A check on every pull request refuses one without its line, under the top
section — see changelog check. It checks that the line
is there and links the pull request, not what it says: the words are written by
whoever made the change, for the people who will use it, and reviewed with it. A pull request that
changes nothing anyone would read about, a lockfile bump say, is labelled
skip changelog. Make the check required on main, or it only advises.
When the version is published, the section is already there, and committed: the
publish workflow makes it the GitHub release's notes. next-version
then opens the next version's section as it moves main on.
Between a release and the next version
A pull request merged after a version is released, but before main moves on, would put its line under a version already out. So the check refuses any branch at a version already released — whatever it contains, label or not — and the release job, once it has tagged, runs every open pull request's check again, so each of them is refused too. Nothing merges until the pull request that starts the next version does; that one needs no line of its own, and passes.
After it merges, each held pull request brings its branch up to date — required, in main's branch rules — and runs the check against the new version. One whose line is still under the old version fails until it is moved up.
The link is only known once the pull request is open, so the line usually
follows in a second commit. contribute prints it, the
link filled in, for you to finish.
A distribution's
A distribution's changelog is mostly written for it. fg-dist notes what changes in what it ships as it makes the change:
## 26.09.01-alpha.1
- `@fairgarden/id` 1.6.0 → 1.7.0 ([release notes](https://github.com/fairgarden/id/releases/tag/v1.7.0))
- `@fairgarden/design` 2.1.0 → 2.3.0 (release notes: [2.2.0](https://github.com/fairgarden/design/releases/tag/v2.2.0), [2.3.0](https://github.com/fairgarden/design/releases/tag/v2.3.0))
- `@fairgarden/members` forked to [acme/members](https://github.com/acme/members), from [fairgarden/members](https://github.com/fairgarden/members)
- `@fairgarden/members` ahead of its next release: Referral links expire after 30 days ([fairgarden/members#12](https://github.com/fairgarden/members/pull/12))
- Members need a referral to join ([#8](https://github.com/acme/core/pull/8))
| Command | Notes |
|---|---|
bump | each module moved, linking the notes of every release it takes in — each has only its own changes — a fork's, merged in or taken whole |
add-module, inherit | each module added, and where from |
fork | the fork, and what it was forked from |
contribute | a change shipped ahead of a release, by its pull request's title, linking it |
unfork | the release it went back to upstream at, and anything left behind |
The one thing people change in a distribution by hand is the organization's
policy, in policies/. A pull request that changes it needs its own line,
checked like a module's; any other pull request into the distribution needs
none. The section is the distribution's version, and
next-version opens the next one — or, for a
release never published when the month turns, renames it.