A changelog for each service: ipx, the page, the directory

CHANGELOG.md moves to crates/ipx/CHANGELOG.md with its history, which until 0.12.0 was all of
ipx's; web/CHANGELOG.md and crates/directory/CHANGELOG.md start with this release's lines for the
page and the directory. The dashboard's lines go: monitoring is not a service anyone uses.
CLAUDE.md says which file a change goes in, and that a release covers each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-12 16:29:10 +00:00
parent 4eab53bf5d
commit fa949f467d
5 changed files with 63 additions and 19 deletions

View File

@@ -254,21 +254,27 @@ Comments explain **why**, not what. If a line looks odd, the comment says what w
it. No emoji, no exclamation marks, no "obviously". Prose in the UI and docs is plain English and
addressed to the person using it.
Every change gets one line under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md), in its
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) group: Added, Changed, Deprecated,
Removed, Fixed or Security. Say it the way someone using ipx would notice it. When there is more to
Every change gets one line under `## [Unreleased]` in the changelog of the service it changes, in
its [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) group: Added, Changed, Deprecated,
Removed, Fixed or Security. One changelog a service: [crates/ipx/CHANGELOG.md](crates/ipx/CHANGELOG.md)
(the daemon and its API; until 0.12.0 everything), [web/CHANGELOG.md](web/CHANGELOG.md) (the page
and ipx-web) and [crates/directory/CHANGELOG.md](crates/directory/CHANGELOG.md) (ipx-directory). A
change to more than one gets a line in each, each saying what that service does differently. The
monitoring (the Grafana dashboard, the prod-check skill) and the repository's own tooling are not
a service anyone uses and get no line. Say it the way someone using ipx would notice it. When there is more to
say, such as what was wrong before or what it cost to find out, it goes in the commit message's
body, where `git log` and `git blame` find it beside the change. (There was a long-form
`docs/history.md` until 0.7.0; it grew too large to be useful and was removed. It is in git.)
Cutting a release: first read `[Unreleased]` against the last release, not line by line, and rewrite
Cutting a release, of the three together while they share one version: in each changelog, first read `[Unreleased]` against the last release, not line by line, and rewrite
it as what changed between the two. Lines go in as the work happens, so they record the way there:
a feature added and then reworked in the same release is one line saying what it is now, under
Added; something added and taken out again before the release, or a fix for a bug no release ever
had, is not there at all; and "instead of" and "no longer" compare with the last release, not with
last week. Issue numbers stay, all of them, on the line that survives. Then rename `[Unreleased]` to
`## [X.Y.Z] - YYYY-MM-DD` and open a new empty `[Unreleased]` above it, set `version` in the root `Cargo.toml` (`[workspace.package]`) to `X.Y.Z` (dropping `-dev`), tag the commit
`vX.Y.Z`, and update the compare links at the bottom of the changelog. Then, in the next commit,
`vX.Y.Z`, and update the compare links at the bottom of each changelog. A service with nothing
under `[Unreleased]` gets no entry for that release. Then, in the next commit,
set `version` to the next patch with `-dev` (after 0.9.0, `0.9.1-dev`), so a build between releases says so
in the logo's tooltip instead of claiming to be the last release. The release that follows can
still be a minor or major one; `-dev` only says the work comes after `X.Y.Z`.