stack: Changelog-Eintrag geschichtet - Impact-Gruppierung, version regrade, Zusammenfassungspflicht (schliesst #95)
Files changed: - CHANGES.md - DEVELOPMENT.md - VERSION - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/run_budget.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_run_budget.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/version.py
This commit is contained in:
@@ -107,9 +107,14 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
version and a changelog entry:
|
||||
|
||||
```bash
|
||||
tools/wikitool version bump --patch --title "<what changed>"
|
||||
tools/wikitool version bump --patch --title "<what changed>" --impact medium
|
||||
```
|
||||
|
||||
`--impact high|medium|low` (default `medium`) grades this bump in the changelog entry's own
|
||||
list - `tools/wikitool version regrade` corrects it later if the candidate's overall shape
|
||||
changes the read on an earlier one; see
|
||||
[instructions/dev/version-parts.md](../version-parts.md) § The candidate model.
|
||||
|
||||
Never edit `VERSION` or the entry's heading by hand - `bump` writes both, and `docs verify`
|
||||
fails a tree where they disagree. Pick the part by whether the new version is a **drop-in
|
||||
replacement** for the old one - not by whether content has to be migrated:
|
||||
|
||||
@@ -55,10 +55,32 @@ a new one, and only `version release` turns it into something the release workfl
|
||||
its parser never has to know the suffix exists.
|
||||
- **One `CHANGES.md` entry per candidate**, not per bump. The first bump of a candidate opens it
|
||||
(heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list seeded with that
|
||||
bump's `--title`); every later bump of the *same* candidate updates that entry in place -
|
||||
heading, date and the bumps list all move, but the entry's own prose (written below the
|
||||
skeleton, by hand) is left alone. `version notes` therefore still prints exactly one entry per
|
||||
release, whatever a candidate's history of bumps looked like.
|
||||
bump's `--title`, graded by `--impact`); every later bump of the *same* candidate updates that
|
||||
entry in place - heading, date and the bumps list all move, but the entry's own prose is left
|
||||
alone. `version notes` therefore still prints exactly one entry per release, whatever a
|
||||
candidate's history of bumps looked like.
|
||||
- **The entry is layered, not one undifferentiated block.** A long-running candidate can collect
|
||||
dozens of bumps, chronological and equally weighted, which is unreadable as a release
|
||||
announcement - `5.0.0` did this at ~1440 lines for one entry. So the entry reads, top to bottom,
|
||||
as four layers with different authors and different lifetimes:
|
||||
|
||||
1. **Heading, author, breaking/migration lines** - written by `version bump`, anchored right
|
||||
above the bump list so the line an operator most needs to act on never sits beneath a list
|
||||
that can run long.
|
||||
2. **The bump list**, grouped `**High/Medium/Low impact**` (empty groups omitted) - rendered by
|
||||
`version bump`'s `--impact` (default `medium`), corrected after the fact by `version regrade`.
|
||||
Flat and ungrouped, exactly as before this layering existed, when every bump is `medium` - the
|
||||
common case, and the shape every pre-existing region still is.
|
||||
3. **The release summary** - a short paragraph, written once, by hand, when the candidate is
|
||||
ready to ship. `version release` refuses to close an entry with two or more bumps and no
|
||||
summary here; a one-bump entry is exempt, since there the bump's own changeset already reads
|
||||
as the summary.
|
||||
4. **The changesets**, one `### <bump title>` heading per bump, in chronological order - the
|
||||
detail a reader follows into from the graded list above. A changeset is a few sentences,
|
||||
not the full rationale; what needs more than that belongs in the issue tracker, not here.
|
||||
|
||||
The list is the index into the changesets, which is why the bump list's title text and a
|
||||
changeset's `###` heading are the same string.
|
||||
- **`version bump` opens or continues a candidate; `version release` fixes one.** Only `release`
|
||||
strips the suffix and turns the entry into a real, closed release - see its own row in
|
||||
`tools/CONTRACT.md`. Nothing else does, and nothing auto-fixes a candidate on its own.
|
||||
@@ -126,9 +148,12 @@ the three-line test below is usually enough.
|
||||
|
||||
Then wait for an explicit go-ahead. Do not bump across the boundary on your own initiative.
|
||||
|
||||
5. **Record the break in the escalation bump itself.** The bump that first crosses the boundary
|
||||
requires `--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the
|
||||
entry:
|
||||
5. **Grade the bump while you are making it, with `--impact high|medium|low`** (default
|
||||
`medium`) - the judgment is easiest right after you did the work, not weeks later staring at a
|
||||
chronological list. It is not final: `version regrade` corrects it before release if the
|
||||
candidate's overall shape changes the read on an earlier bump. Then record the break in the
|
||||
escalation bump itself. The bump that first crosses the boundary requires
|
||||
`--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the entry:
|
||||
|
||||
```bash
|
||||
tools/wikitool version bump --major \
|
||||
@@ -168,16 +193,27 @@ the three-line test below is usually enough.
|
||||
never reported by anything. The 5.0.0 candidate is the case: it declared `--no-migration` for
|
||||
a TOC-verification change, then absorbed a schema removal that migrates 152 pages.
|
||||
|
||||
7. **Fix the candidate once it is ready to ship.** `version bump` only ever opens or escalates
|
||||
one; nothing turns it into a release except `tools/wikitool version release`, which strips the
|
||||
`-beta.N` suffix and closes the entry - see its row in `tools/CONTRACT.md`. That is also the
|
||||
point to pass a summarising `--title` if the candidate collected several bump titles along the
|
||||
way; without one, the heading simply keeps whichever bump last set it.
|
||||
7. **Review the graded list before fixing the candidate, and regrade what reads wrong.** Run
|
||||
`tools/wikitool version regrade` with no arguments - it lists every bump at its current grade,
|
||||
numbered in rendered order. A candidate that grew over several sessions often has a bump graded
|
||||
in isolation that reads differently once the whole shape is visible; `version regrade 3 7
|
||||
--impact high` corrects one or several positions against a single read of that list, put the
|
||||
result in front of the user, and re-list to confirm. Only then run
|
||||
`tools/wikitool version release`, which strips the `-beta.N` suffix and closes the entry - see
|
||||
its row in `tools/CONTRACT.md`. That is also the point to pass a summarising `--title` if the
|
||||
candidate collected several bump titles along the way; without one, the heading simply keeps
|
||||
whichever bump last set it.
|
||||
|
||||
8. **Write the entry's body.** `bump` leaves it empty on purpose. A boundary-crossing entry
|
||||
earns a paragraph that says *why this is breaking* - it is the one thing a future reader
|
||||
cannot reconstruct from the diff, and it is what the next session in this position will read
|
||||
instead of guessing.
|
||||
8. **Write the entry's prose - the summary, and each bump's own changeset.** `bump` leaves both
|
||||
empty on purpose. The **summary** is a short paragraph (a few sentences) written once, at
|
||||
release time, right below the graded bump list: what this release is about, and why, for a
|
||||
reader who will not read the changesets underneath. `version release` refuses to close an
|
||||
entry that collected two or more bumps and has no summary - a one-bump entry is exempt, since
|
||||
there the bump's changeset already reads as one. Each **changeset**, under its own
|
||||
`### <bump title>` heading, is a few sentences on what changed and why - it is the one thing a
|
||||
future reader cannot reconstruct from the diff, but it is not the place for the full rationale
|
||||
of a decision; that belongs in the issue tracker or the commit history, and a changeset that
|
||||
is growing past a paragraph or two is a sign it belongs there instead.
|
||||
|
||||
## Decision points
|
||||
|
||||
|
||||
Reference in New Issue
Block a user