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:
16
CLAUDE.md
16
CLAUDE.md
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user