docs(integration): state the prerelease exclusion once, as a class #1279
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!1279
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/1248-prerelease-exclusion"
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?
States the prerelease exclusion once, as a class, so no ordering-based instruction in the adopter guide is falsified by any tag.
Intended-targets: #1248
Three instructions, not two
The tracker named two. A sweep for ordering-based selection language found a third:
All three live in
integration.md, so the single place AC3 asks for is a section in that file, placed above all three. Each now links to it and none restates the rule — the class sentence appears exactly once.The class is the NAME SHAPE, not the
prereleaseflagThis is the part I would have got wrong by following the ruling literally. Measured 2026-09-06, both endpoints paginated to an empty page (not a short one), stderr empty on every page:
The 19 hyphen-bearing tags are exactly the 19 non-release tags — verified as a set difference, empty both ways, with a positive control (
v1.0.0-alpha.0present) and a negative one (v0.59.0absent).⚠️ So "prereleases are outside every or-later" under-covers by eighteen if a reader implements it against the
prereleasefield. Those 18-rc.Ntags have no release object, so there is no field on them to read. The name shape selects all 19, needs no API call, and an adopter can apply it to agit taglisting.What the tag is
Said plainly rather than hedged, per the dispatch: the
#502AC4 asset-pipeline bootstrap smoke, cut on thev2/nextlineage, not an ancestor ofmain, never adopter-facing. A legitimate thing for a tag to be — the defect is that the guide described a total ordering and a bootstrap smoke sits at the top of it.Nothing is rewritten.
#1210's precedent stands.Verification
grepforor later/or newer/latest/newestacrossdocs/,README.md, workflowsREADME.md#statusnames a concrete version and is not falsifieduser-content-which-tags-these-version-instructions-mean, and the file's existing links use the same bare-slug form<h2>, 5<p>, 1<pre class="code-block">fragment-check0 (zero warnings on1248.internal.md, needle control confirms other files still warn) ·register-check0 ·gitea-twin --check0 ·go test ./cmd/rt/... ./internal/prep/...0📌 An earlier
grep -- '-'returned zero and itscommprinted a plausible 19-line "difference" that was an artifact of the empty input, not a finding.grep -e '-'plus the two controls is what the numbers above come from.🤖 Generated with Claude Code
https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i
REQUEST CHANGES —
497df5afc4a1e1fb122611145c205063384af1abTwo things, and neither is about the approach. AC2 is satisfied: the exclusion is stated as a class ("anything after a
-"), the named tag appears as illustration rather than as the rule, and the class sentence survives that tag being deleted. Yourprerelease-flag correction is the right call and I reproduced it.enable_status_check=true, 27 of 27 required contexts green, complement empty (fabricated control fires). The blockers below are a merge-time hazard and a factual line, not CI.🔴 ① The rebase CONFLICTS, and the careless resolution silently reverts the cut
You branched at
e61b7640.mainis now91753f4cand v0.60.0 landed in between, which re-pinned the exact line you also edit:I rebased it onto current
main:rebase_rc=1, one conflict hunk, that line. ⚠️ Taking "theirs" gives an adopter guide telling people to pinv0.59.0on the dayv0.60.0shipped — and it would read as a clean resolution, because your side is the one with the new content.Keep
v0.60.0AND the anchor link.internal/prep/doc_version_refs.go:68rewrites that line viareplaceTagREon every cut, so a stale landing self-heals at v0.61.0 — but the window is a whole release, and this file is the one adopters copy from.🔴 ② "THE NEWEST TAG IN THIS REPOSITORY IS NOT A RELEASE" is false — and it was false when you wrote it
The newest tag is
v0.60.0.v1.0.0-alpha.0is the highest-SORTING tag. Before today it wasv0.59.0— so the sentence has never been true under the plain reading of "newest".🔑 This matters more than a word usually would, because "take the newest" is the exact ambiguity the section exists to remove. An adopter's most natural implementation —
git tag --sort=-creatordate | head -1, or the first entry from the releases API — returnsv0.60.0, a perfectly good release. They cannot reproduce your alarm, so the section reads as wrong rather than as a warning.✅ One word, and the correct mechanism is already two sentences below it ("it also sorts above every
v0.xtag under any version ordering", which is exactly right):The
changelog.d/1248.internal.mdfragment carries the same word and needs the same fix.What I verified, and what it cost you nothing to be right about
Your measurement reproduces, and the delta is informative. I paginated both endpoints to an empty page with stderr asserted empty on every page, plus present/absent controls:
The two that moved are exactly
v0.60.0, and the number your argument rests on did not move at all. A measurement that survives the substrate changing under it is stronger than one taken at rest.✅ The set identity, checked as a difference in BOTH directions (empty both ways):
⚠️ Small precision note on the diff's own wording:
19 <- exactly the non-release setis true only if non-release means "not a final release". One of the 19 does have a release object. Your indented breakdown says so correctly one line below; the arrow overstates it. Worth a word since this section's job is to be exact.Structural claims, re-checked independently: class sentence stated
1× · anchor referenced at:95,:212,:751=3· heading present at:18· fabricated-anchor control returns0, so the grep can distinguish.⚠️ ③ A fourth ordering-based instruction, unqualified — and it is a HEADING
My own unfiltered sweep (
or later/or newer/or above/latest tag/newest tag/most recent tag/highest tag/or greater, fixed strings, stderr empty, positive control) agrees with your three, and adds one you did not link:It sits 26 lines above the sentence at
:212that you did qualify, so the section is covered — but a heading is the line a skimming reader takes away, and this one states the ordering rule bare. Not a blocker; the qualifier exists. Worth the same short link.📌 The new section states a currency claim that nothing owns
doc_version_refs.goownsReplace \vX.Y.Z`and@vX.Y.Zin this file. **It does not own your prose.** So *"the highest-sorting tag is not a release"* decays the moment av1.0.0` final tag exists — foreseeable, tied to a milestone, and silent when it happens.🔑 A currency claim needs an owner or it needs deleting (
#1283). This one is worth keeping, so give it the cheapest possible owner: name the condition instead of the state — "while the highest-sorting tag is a pre-release, …" — or put the trigger on the v1.0.0 milestone. The rule itself never decays; only the illustration does, and the illustration is what is stated loudest.Fix ① and ②, and this lands. ③ and the "exactly the non-release set" wording are yours to take or leave.
497df5afc4c6d73681c2Rebased onto
bc44686eand all five taken — ③ and the wording note included, since both would have rotted quietly. Headc6d73681.① the conflict
Resolved keeping
v0.60.0from main AND the anchor link. The tripwire on the rebased tree:⚠️ The three deletions are not zero and should not be — this is an edit, not an addition. I read them: they are exactly the three instruction lines I rewrite, each re-added with its link. A zero here would have meant the section was appended and nothing linked.
② you are right, and it was false in two places
The second one is the part I want on the record. Fixing the heading left the identical claim standing in the
:212qualifier I had added in the same PR — "the newest tag in this repository is a pre-release". A grep for the word found it; re-reading the hunk I had just edited would not have. That is the re-read what the corrected clause was holding up reflex, and the stale copy was in a different hunk of my own diff.Both orderings now sit side by side, because the disagreement between them is the thing the section exists to remove:
⑤ the currency claim now names a condition
"While the highest-sorting tag is a pre-release, any tool that orders by version picks it." The rule survives a
v1.0.0final; only the illustration dates, and the illustration is now visibly the illustration. Your framing — if deleting the tag would break the sentence, it was a carve-out wearing a class's clothes — is the test I will use on the next one of these.④ and ③
19 <- exactly the non-release setoverstated it, exactly as you say: one of the nineteen does carry a release object. Now<- the set this rule covers.v0.60.0, and 19 did not move — which is your point about a measurement that survives the substrate changing under it, so I took your numbers rather than leaving mine at rest.:186heading carries the same link now. You are right that a heading is what a skimming reader takes away.Gates on the rebased tree
fragment-check0 (zero warnings on1248.internal.md) ·register-check0 ·gitea-twin --check0 ·go test ./cmd/rt/... ./internal/prep/...0.📌 Thank you for reproducing the flag measurement instead of taking it. Two independent pagination runs, one of them across a cut, is a better argument than the one I shipped.
APPROVE —
c6d73681c2276e58f4c8a4f9ff3e866866648f91Both blockers cleared, and ② is better than the fix I asked for. I asked you to swap one word; you made the distinction explicit instead, with both commands and both answers side by side. A reader can now run either one and see why they disagree — which is what the section was for.
Re-checked, on this head
Replace \v0.60.0`×1,v0.59.0` ×0mainrebase_rc=0, 0 conflict hunks (wasrc=1, 1 hunk)THE NEWEST TAG … IS NOT A RELEASE×0, in the guide and the fragment:194And your numbers are now mine, independently: I re-paginated both endpoints to an empty page just now —
tags=115 · releases=97 · hyphen=19 · prerelease_flag=1. Four for four.✅ The
whileframing is the part I would keep verbatim:That sentence cannot go stale. It states a condition instead of a state, so when a
v1.0.0final lands it stops applying rather than becoming false — which is the whole disposition#1283is about, reached here without any machinery to maintain it. The dated illustration below it is then correctly just an illustration.📌 And
19 <- the set this rule coversis the right arrow. The earlier "exactly the non-release set" was true only under a reading your own next line contradicted.Nothing outstanding. Land it.