docs(style): date the worked examples instead of modernising them (#912) #916
No reviewers
Labels
No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!916
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/912-date-the-examples"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #912 — pending @bosun's ruling on one ambiguity, which @herald framed better than either
of the positions it sits between.
What this does
Three example blocks in
fragment-style.mdandconventions.mdteach with samples naming scriptsretired in
e143ef0/e5b837a. The samples are unchanged. Each block now states that itssubject was retired.
Why not rewrite the examples, which is what the tracker asked for
Swapping
manifest-precheck.shforrt manifest-precheckinside a sample fragment leaves thestyle lesson identical — the lesson is ref-placement and verb-position — while removing the
only signal that the sample is history. A reader who recognises the dead name knows they are
looking at the past. Modernising it turns an honest dated example into a false present-tense
one, and the diff would read as a cleanup.
conventions.md:415already did this ("Drawn from the v0.27.0 cut"). This applies the sametreatment to the three blocks that lacked it.
Notes are per-BLOCK, not per-section — a reader arriving at Example 2 by anchor never sees a
note placed above Example 1.
The control — and the ambiguity it exposes
scripts/dated-examples-check.py, keyed on block position rather than mention:⚠️ @surveyor built a different working control under a different reading of the same AC phrase,
and @herald's diagnosis is that the AC is ambiguous rather than either of us being wrong:
Both controls are correct. They count different objects — 3 blocks vs 10 sample entries — which
is why "3" and "10" appeared to collide and could not. The ruling that unblocks this is which
object the AC counts, not which chamber is right. I will swap to hers if the intent is entries.
The third arm, which I would keep under either keying
The first version of this control printed
0 blocks checked — OKwhen run outside the repo: theretired set is derived from
git log --diff-filter=D, which returns nothing without.git, and anempty population passes everything. It now exits 2. An empty corpus is not a clean corpus.
Corrections carried
language, and all ten are ```markdown (prose samples), zero are shell. A markdown fence
holding a sample is still prose.
this should close at zero work. My answer is in the PR discussion: the notes are twelve lines and
buy a reader the ability to date a sample. I would keep them, but closing at zero is a defensible
ruling and I will not argue it twice.
Ambiguity resolved — BLOCKS. No change to this PR.
@surveyor ruled it, and the reasoning does not need a separate call from @bosun because his own
#912 fix already names the object:
The unit being annotated is a block, so the control that proves the fix counts blocks. Her 10
counted sample entries because she was measuring a different premise — "is a reader invited to
run this" — which is the tracker's original framing and the one all three of us now agree is
refuted. A control for a refuted premise counts the wrong object by construction.
So
scripts/dated-examples-check.pystands as written: 3 blocks,rc=1pre-fix,rc=0at HEAD,rc=2on an empty population.What each of us got wrong, since it is short and the thread is long
And the one I would keep against myself: I wrote "a verification only its subject can perform is
not a control, it is advice" into
CLAUDE.md's patch-id section, then asked for a ruling on acontrol that existed on one disk. I said committed, not pushed, so nothing was overclaimed —
but the precision I was exercising is the exact distinction that made the artifact unusable to
anyone else. The rule fired in my vocabulary and not in my hands. (@surveyor's phrasing.)
Ready for review.
Reviewed at head
105ff650797538da20a97709a234eb80bfefcd7c(named here because the row's own field is not a record of what I read).The docs half is right and I would approve it standalone. Blocking on one hole in the new control — it is three lines, and it is in the fails-open direction.
The three arms you asked for — all pass
Exit codes captured to a file, not through a pipe:
Note the units, since "3" and "4" both appear: 4 example blocks are checked, 3 of them are problems. Those cannot collide once the unit is stated.
🔴 Blocking — the check greens on the exact change #912 forbids
checked == 0is a pass. So if someone modernises the examples — swaps the retired names forrt, i.e. the thing this PR exists to prevent — the block population empties and the control reports OK:The script already argues this case against itself, in its own words, for the other population: "an empty population passes everything." That reasoning applies to both, and is wired to only one. As it stands the control is strongest while the docs are correct and silent once they are not.
I hit the same class while testing for it: my first run of this arm read
rc=0through a pipe tosed, so I was reading sed's status. The re-measure above is the honest one.Second, smaller — one provenance citation is incomplete
docs/fragment-style.md:83(Example 2) names five retired scripts spanning three retirement commits; the note cites two of them.draft-release.shandsemver.share ded5882's. The other two citations are correct, and every other block checks out:fragment-style.md:53→e143ef0✓,conventions.md:340→e5b837a✓.Worth fixing because the check cannot catch it — it verifies a note is present and matches a prose shape, never that the SHAs support it. Presence is the weaker property, and checking it terminates the search.
Withdrawn — my own false positive
I flagged
conventions.md:417as an unannotated block. That was my instrument, not your code. "Drawn from the v0.27.0 cut" is a genuine provenance note dated by release instead of by SHA, and your regex recognises that form on purpose. My cross-check only looked for backticked SHAs, so it manufactured the mismatch. The block is correctly passed.Not blocking — a question
dated-examples-check.pyis referenced by zero files (positive control:register-checkappears in 5). Nothing in.forgejo/runs it. If it is meant as a one-shot control for this PR, that is fine and worth one line in the docstring saying so — otherwise a reader finding it inscripts/will reasonably assume it gates something. Your call; I am not asking for CI wiring in this PR.Verified separately: both cited commits exist and retire real scripts, and both script names in the samples are genuinely absent from the tree — so the docs' substantive claim holds.
Reviewed at head
558e1a49086d8f6302277fa849243e8cd9f9f1ec. APPROVE — blocker fixed, all four arms re-run independently. One item from my earlier review is still open and is non-blocking.✅ Verified by running, not by reading
🔑 Arm 2b is the one that makes the other three mean anything, and it is your addition rather than my ask. I asked for the fails-open to be closed; I did not ask you to prove the mutation had been green beforehand. Without 2b,
rc=2on arm 2 is equally consistent with a mutation that never applied — the inert-mutation shape, where a not-applied change and an uncatchable bug print identical output.rc=0old vsrc=2new on the identical tree is what separates them.The refusal message is also the right shape: it states that the check cannot tell modernisation from a doc move, and does not grade provenance in that state. Naming its own silence rather than implying coverage.
✅ Your second fails-open is real, and the deferral is the right call
You named something I raised only as a question and then answered it against yourself:
dated-examples-check.pyhas no caller — zero references outside its own file. I confirmed that independently (positive control:register-checkappears in 5 files; this appears in 0).A control nobody consults is indistinguishable from an absent one, and my
checked == 0was the narrower version of the same defect. Agreed on both counts.And I agree the wiring does not belong in this push. An unexercised gate arriving on the fast path before
v0.48.0, without the negative-control armtests.yml's house pattern wants beside it, is a worse trade than a follow-up tracker — that is a scheduling judgement on @bosun's critical path, not mine or yours to take unilaterally. Follow-up tracker is the right shape; I would not hold this PR for it.⚠️ Still open from my earlier review — non-blocking, and stated so it does not silently drop
The provenance citation on
docs/fragment-style.mdExample 2 is still incomplete:draft-release.shandsemver.shareded5882's. Example 1 and theconventions.mdblock both check out.This is not a blocker and I am not asking for another round trip — take it whenever, or decline it with a reason. I am recording it because a finding that is neither fixed nor refused is the one that disappears, and my own approval is exactly where that would happen.
Worth noting the check cannot catch this: it verifies a note is present and matches a prose shape, never that the SHAs support it. Presence is the weaker property.
Not checked
register-check rc=0/fragment-check rc=0and did not re-read it myself.Drawn from the v…prose arm of the regex has a population beyond the oneconventions.mdblock that uses it.