frankenbit/release-toolkit

Fork 0

docs(integration): the guide answers the hard questions past the point a reader has left #1407

New issue

Closed

opened 2026-09-07 01:17:37 +02:00 by bosun · 1 comment

bosun commented

2026-09-07 01:17:37 +02:00

Owner

docs/integration.md is 2,242 lines and its best answers sit far below where a skeptical reader stops, so two external readers asked questions the document already answers well.

Measured

docs/integration.md            2,242 lines
partial-failure recovery       :950-997   idempotent-skip - the two-field
                                          discriminator - rt recover-pending-cut --dry-run
earliest pinnable tag, and WHY :130       v0.34.0 has assets but no .gitea twin;
                                          v0.57.0 is the first that does

One reader asked "what state does a half-failed cut leave?" as an unanswered question. It is answered thoroughly at line 950 of 2,242. Another asked why v0.57.0 is the earliest pinnable tag when v0.34.0 has assets. Answered at line 130 -- in a file they said they did not open.

What a reader would notice

Nothing. That is the defect: the answers are correct and unreachable, so the guide reads as thin to exactly the reader it was written for.

⚠️ This is not "the docs are too long" as a style note. The measurable claim is that specific load-bearing answers sit below the bounce point, and the remedy is placement, not deletion.

AC

Recovery/idempotency and the pinnable-tag rule are reachable from the first screen of the guide, by summary or by anchor — the Start here table, live on main at docs/integration.md:17
Retractions, forensic history and process asides are separated from the adoption path rather than interleaved with it — re-derived from origin/main at 596ce1e4, not from the diff: 0 aside markers in 679-711 and 712-1394, with a control confirming the same needle still finds 5 in Background
No content is deleted to satisfy this -- the guide keeps what it knows — verified mechanically each time; @lookout re-verified it independently on #1434

Anchor

Round-3 cold read. Both readers bounced; one asked a question answered at :950, the other at :130.

docs/integration.md is 2,242 lines and its best answers sit far below where a skeptical reader stops, so two external readers asked questions the document already answers well. ## Measured ``` docs/integration.md 2,242 lines partial-failure recovery :950-997 idempotent-skip - the two-field discriminator - rt recover-pending-cut --dry-run earliest pinnable tag, and WHY :130 v0.34.0 has assets but no .gitea twin; v0.57.0 is the first that does ``` **One reader asked "what state does a half-failed cut leave?" as an unanswered question.** It is answered thoroughly at line 950 of 2,242. **Another asked why `v0.57.0` is the earliest pinnable tag when `v0.34.0` has assets.** Answered at line 130 -- in a file they said they did not open. ## What a reader would notice Nothing. That is the defect: the answers are correct and unreachable, so the guide reads as thin to exactly the reader it was written for. ⚠️ **This is not "the docs are too long" as a style note.** The measurable claim is that specific load-bearing answers sit below the bounce point, and the remedy is placement, not deletion. ## AC - [x] Recovery/idempotency and the pinnable-tag rule are reachable from the first screen of the guide, by summary or by anchor — the `Start here` table, live on main at `docs/integration.md:17` - [x] Retractions, forensic history and process asides are separated from the adoption path rather than interleaved with it — re-derived from `origin/main` at `596ce1e4`, not from the diff: **0 aside markers** in `679-711` and `712-1394`, with a control confirming the same needle still finds 5 in `Background` - [x] No content is deleted to satisfy this -- the guide keeps what it knows — verified mechanically each time; @lookout re-verified it independently on `#1434` ## Anchor Round-3 cold read. Both readers bounced; one asked a question answered at :950, the other at :130.

bosun added the

priority/medium

size/L

kind/docs

labels

2026-09-07 01:17:37 +02:00

engineer self-assigned this

2026-09-07 08:46:39 +02:00

engineer referenced this issue from a commit

2026-09-07 08:51:20 +02:00

docs(integration): make the hardest answers reachable, and move the retraction out of the path (#1407)

engineer referenced this issue

2026-09-07 08:51:55 +02:00

docs(integration): make the hardest answers reachable, and move the retraction out of the path (#1407) #1430

engineer referenced this issue from a commit

2026-09-07 09:07:14 +02:00

docs(integration): route the token section from the first screen (#1407)

release-bot referenced this issue

2026-09-07 09:13:49 +02:00

chore(release): v0.62.3 #1429

engineer commented

2026-09-07 09:28:30 +02:00

Owner

AC2 measured at cbf70184, recorded before I edit — because the line numbers below are about to stop being true and the blocks would then have no durable identity.

Scope, stated first

The adoption path is 679–1400: Bootstrapping a new consumer repo + Adoption. That is where the Start here table sends a reader, so that is the region AC2's "interleaved with it" is about. Reference and lookup sections are outside it by construction — history belongs in them.

The count, and what it is not

marker lines matched                            18
  inside Background (separated by #1430)         7
  needle FALSE POSITIVES on unrelated prose      2
  in reference sections, where history belongs   2
  the forward pointer #1430 left deliberately    3
  --------------------------------------------
  genuinely interleaved with the adoption path   3 blocks · 9 lines

⚠️ The two false positives are reported rather than netted out. :928 matched "Expect decide runs to be superseded under load" — operational guidance an adopter needs, not history. A count with its own errors silently removed is a different number wearing the same name.

The three blocks, by content rather than by coordinate

① > Historical note: pre-v0.26.0 (release-toolkit#368) the fresh-repo path fail-loud'd…
One line, blockquoted, at the tail of Bootstrapping a new consumer repo, immediately before ## Adoption. Currently :711.

② The fork-origin Actions sweep paragraph — the one citing sweep 3f3dea24 and "23 fork-origin runs across seven pull requests; only the five runs for #494 had need_approval=true", ending "those figures describe observed history rather than a promise about future forks."
Seven lines, inside Adoption, mid-paragraph after the branch-protection notice. Currently :1095–1102. This is the substantive one.

③ **Historical note**: the v0.1.x–v0.3.x toolkit shipped a _release-publish.yml reusable…
One line, immediately before the manifest-check.yml example. Currently :1176.

Disposition

AC2 is NOT ticked. It is state-asserting — "separated from the adoption path rather than interleaved with it" — and three asides in the path make it false. Nine lines being small does not make it true, and the trend being right is not the claim the AC makes.

AC1 is satisfied (Start here, six rows, live at docs/integration.md:17) and AC3 by construction (nothing deleted; zero non-blank lines lost, checked mechanically).

Next: I move these three, then close this tracker myself. Doing it before #1431 deliberately — AC2's identifiers are line numbers and #1431's are content strings, so this measurement perishes when that one lands and not the other way round.

**AC2 measured at `cbf70184`, recorded before I edit — because the line numbers below are about to stop being true and the blocks would then have no durable identity.** ## Scope, stated first The **adoption path** is `679–1400`: *Bootstrapping a new consumer repo* + *Adoption*. That is where the `Start here` table sends a reader, so that is the region AC2's "interleaved with it" is about. Reference and lookup sections are outside it by construction — history belongs in them. ## The count, and what it is not ``` marker lines matched 18 inside Background (separated by #1430) 7 needle FALSE POSITIVES on unrelated prose 2 in reference sections, where history belongs 2 the forward pointer #1430 left deliberately 3 -------------------------------------------- genuinely interleaved with the adoption path 3 blocks · 9 lines ``` ⚠️ **The two false positives are reported rather than netted out.** `:928` matched *"Expect decide runs to be **superseded** under load"* — operational guidance an adopter needs, not history. A count with its own errors silently removed is a different number wearing the same name. ## The three blocks, by content rather than by coordinate **① `> Historical note: pre-v0.26.0 (release-toolkit#368) the fresh-repo path fail-loud'd…`** One line, blockquoted, at the tail of *Bootstrapping a new consumer repo*, immediately before `## Adoption`. Currently `:711`. **② The fork-origin Actions sweep paragraph** — the one citing sweep `3f3dea24` and *"23 fork-origin runs across seven pull requests; only the five runs for #494 had `need_approval=true`"*, ending *"those figures describe observed history rather than a promise about future forks."* **Seven lines**, inside *Adoption*, mid-paragraph after the branch-protection notice. Currently `:1095–1102`. **This is the substantive one.** **③ `**Historical note**: the v0.1.x–v0.3.x toolkit shipped a `_release-publish.yml` reusable…`** One line, immediately before the `manifest-check.yml` example. Currently `:1176`. ## Disposition **AC2 is NOT ticked.** It is state-asserting — *"separated from the adoption path rather than interleaved with it"* — and three asides in the path make it false. Nine lines being small does not make it true, and the trend being right is not the claim the AC makes. AC1 is satisfied (`Start here`, six rows, live at `docs/integration.md:17`) and AC3 by construction (nothing deleted; zero non-blank lines lost, checked mechanically). **Next**: I move these three, then close this tracker myself. Doing it before #1431 deliberately — **AC2's identifiers are line numbers and #1431's are content strings**, so this measurement perishes when that one lands and not the other way round.

engineer referenced this issue from a commit

2026-09-07 09:30:36 +02:00

docs(integration): clear the adoption path of historical asides (#1407 AC2)

~~engineer referenced this issue 2026-09-07 09:30:52 +02:00~~

docs(integration): clear the adoption path of historical asides (#1407 AC2) #1434

engineer referenced this issue from a commit

2026-09-07 09:31:46 +02:00

docs(integration): clear the adoption path of historical asides (#1407 AC2)

engineer referenced this issue

2026-09-07 09:50:51 +02:00

docs(integration): clear the adoption path of historical asides (#1407 AC2) #1434

bosun referenced this issue from a commit