Document the site-holds-many-tickets model, and correct the guide pages that predate it

[juanmaguitar]

Warning

Do not merge this before the ticket-branches stack (#168 #185 #198 #205 #218 #238 #241 #242 #243). It documents features that are not on trunk yet. Merged first, the published guide describes an app nobody can download.

Why

The user guide describes a site as one working tree and one implicit patch, because that is what the app was when the guide was written. The ticket-branches stack makes a ticket a branch on the site, which leaves several pages not merely incomplete but wrong: what a patch contains, what Unlink costs you, what a trunk update does to work in progress, whether the applied-patch banner describes the ticket you are looking at.

The stack also adds surface nothing documents at all — the tickets card, the question asked about edits made before a ticket was picked, the note about unsubmitted work, the switch progress line, coloured pull request states.

What changes

Docs only. The diff is docs/ — guide pages, docs/.vitepress/config.mjs for the sidebar, and screenshots. No src/, no scripts/.

New page: guide/ticket-branches.md, "Working on several tickets". The model (a site is the expensive substrate, a ticket is a cheap branch), starting a second ticket, the tickets card in both its states, what a switch says while it runs and what to do when one fails part-way, deleting one ticket's work, the four-choice question about loose trunk edits, the unsubmitted-work note, and what a ticket's patch does and does not contain. Added to the sidebar under "Contributing changes", after "Working on a Trac ticket".

Corrections to pages that describe the old model:

Page	What was wrong
trac-tickets.md	Unlink described as only forgetting an association; no mention that a site holds many tickets, that linking asks about loose edits, or that PR states are now coloured pills with a third value
submitting-changes.md	"everything this site has that its copy of trunk does not" — the diff is now the ticket's own work, measured from its branch point. Also gained what a patch can and cannot carry: deletions now travel, binaries and unreadable files are named above the diff rather than dropped
trunk-updates.md	Said nothing about being on a ticket — that the update parks and returns, and that the branch point deliberately does not move
applying-patches.md	Applied-patch state is per ticket now; and "use Update to latest trunk to reset the checkout" does not hold on a ticket branch, where the update puts you back exactly where you were
creating-a-site.md	Implied a site per piece of work
managing-sites.md	Delete this site takes every ticket's work with it; and its dirty-tree dialog is about loose edits only, never parked ticket work
troubleshooting.md	New entry for the refused-switch message, which is what someone will search for
getting-started.md, setup-wizard.md, submit-*.md, running-the-site.md	The button is Review & submit changes; the guide still quoted Submit changes everywhere

Deliberately not in this PR: new entries in scripts/screenshots/shots.cjs for the panels the stack adds. A shot definition belongs with the code that draws the panel, and one added here would fail on trunk where the panel does not exist — see Risks.

How to test this

Platforms: any. This is a static site; nothing here touches the app.

Starting state: this branch checked out.

1. npm run docs:build → completes. This is the real check: ignoreDeadLinks: false, so a broken link or a missing image fails it.
2. npm run docs:dev and open /guide/ticket-branches → the page renders, the six screenshots load, and "Working on several tickets" is in the sidebar under Contributing changes, between "Working on a Trac ticket" and "Applying patches and PRs".
3. Follow the internal links out of that page — #what-a-patch-contains, #edits-you-made-before-picking-a-ticket, #deleting-a-ticket-s-work, trunk-updates#updating-while-you-are-on-a-ticket, submitting-changes#what-a-patch-can-and-cannot-carry → each lands on the heading it names, not at the top of the page.
4. npm run lint → clean.

And the part a build cannot check — drive the stack (the Buildkite artifact for juanmaguitar/pr-state-colours exercises all nine PRs) with the new page open, and check the prose against the app:

5. On a site with two tickets, read "Starting a second ticket" and follow it literally. → Unlink, then type the second number. The page should not describe a control that is not on screen.
6. Read the switch progress sentences in the page against the ones the panel actually shows.
7. Compare the six screenshots against the panels as they render for you.

What must not have happened:

• No src/ or scripts/ file in the diff. git diff --stat origin/trunk...HEAD must list only docs/. If a screenshot-harness change slipped in, it will fail on trunk.
• No invented UI string. Every label quoted in these pages was read out of the stack's source or seen in the app. A plausible-sounding button that does not exist is worse than no documentation.
• No page left describing the old model. The table above is the list; if another page still says a site carries one ticket, it was missed.

Risks and limitations

This PR must merge after the stack. It is the only real risk here and it is not defended by anything automated: nothing in CI knows the difference. The Pages deploy runs on trunk, so merging early publishes it immediately.

• scripts/screenshots/shots.cjs has no entries for the new panels, so the six new images are not reproducible with npm run shots as things stand. They were taken by driving the stack through the same Playwright harness in a throwaway worktree, with fixture and shot definitions that were not committed anywhere. Follow-up, and it belongs on a branch that has the panels: the fixtures need real repositories with ticket branches, where the current ones are empty directories. Follow-up issue not yet filed — happy to file it.
• site-view.png is re-shot and is the only existing image replaced. Its button still read Submit changes, which was already stale on trunk after Say on the card when there are unsubmitted changes, and give them a way out #235 renamed it — so that image and the text corrections around it are true of trunk today, stack or no stack.
• The MERGED pill is documented but not screenshotted. A repository-wide search returns no merged pull requests on wordpress-develop; the state is real in the API and unit-tested, and Colour a linked pull request by its state, in GitHub's own colours #243 says the same.
• The screenshots name a real ticket and its real pull requests (#29798), pulled live from GitHub when the images were taken. They will age the way any screenshot of live data ages.
• Review outcome: 5 [fix here] · 1 [follow-up] — all 6 addressed. Every one was a factual claim about the app, not prose. Details in the collapsed block.

Related

Documents #168, #185, #198, #205, #218, #238, #241, #242, #243 — the ticket-branches stack, tip branch juanmaguitar/pr-state-colours. Part of the contribution-flow tracker #110. Follows the docs site (#230), its screenshot harness (#231) and the guide itself (#232).

---

Design decisions and alternatives considered

A new page rather than growing trac-tickets.md. That page is about one ticket: linking it, and reading the work that already exists on it. Several tickets is a different subject with its own vocabulary — parking, switching, deleting a branch — and folding it in would have doubled the length of a page a first-time contributor reads on their first ticket, to describe something they do not do yet. trac-tickets.md gains pointers instead.

Corrections before additions. A page that is wrong costs more than a page that is missing: someone acts on it. So the pass over the existing guide came first, and the new page was written to fill what was left.

Screenshots taken by hand rather than by adding shot definitions. The harness lives on trunk and the panels live on the stack, so a shot definition committed here would fail every npm run shots on trunk until the stack lands. The images were taken by assembling the two in a scratch worktree — stack tip, plus trunk's scripts/screenshots/ and the TOOLKIT_USER_DATA_DIR hook, plus fixtures that build real repositories with ticket branches — and only the resulting PNGs were copied here. That worktree is gone; nothing of it is in this diff.

Quoting the app rather than paraphrasing it. Where a sentence in the app is the thing being explained — the question about loose edits, the switch stages, the confirm before a delete — the page quotes it verbatim, so someone reading with the app open can match what they see. Every quote was read out of the stack's source.

Review outcome (5 [fix here] · 1 [follow-up] — all addressed)

Run per .github/instructions/code-review.instructions.md. Deterministic layer inline and clean — npm run lint clean, npm test 638/638, npm run docs:build clean. The judgement pass went to a subagent with the diff, the instructions file and the stack's source, and nothing from the session that wrote the pages; it was asked to check every quoted string and every behavioural claim against the code rather than to read the prose.

Every finding was an accuracy finding — the guide asserting something the app does not do. All five were verified against the source before being fixed.

#	What was wrong
1 🔴	The new page's central how-to. "Type the number into the Trac ticket panel" — the panel holds no input while a ticket is linked; the field is in the unlinked branch only. The route is Unlink, then link the new number. Unfollowable as written.
2 🟡	The mid-switch advice described a recovery that does not exist: the marker is written only when a checkout throws inside a running app, so a force-quit leaves nothing behind, and midSwitchBlock refuses the retry along with everything else. The one action it allows is Unlink, which is now what the page and troubleshooting.md say.
3 🟡	applying-patches.md's "use Update to latest trunk to reset the checkout" escape hatch. On a ticket the update parks, resets trunk and checks the branch back out — applied patch included — so it leaves you where you started.
4 🟡	"Nothing is rebuilt" was true and misleading: a switch does not rebuild, so a running dev server keeps serving the previous ticket's assets. The page now says to run npm run build after a switch, which is what the site view itself says.
5 🔵	"If the note says two changes, the patch has two files." The note counts everything the patch speaks about, binaries included, and those are named above the diff rather than carried — so one text file and one image is two in the note and one in the diff. It also contradicted this PR's own submitting-changes.md.
6 🔵	The by-hand replay recipe skipped the trunk update that gives the new branch a newer base, and offered Delete this ticket's work for the ticket you are on, which the card never lists.

[follow-up], both taken here rather than deferred because they were two sentences each: managing-sites.md and trunk-updates.md described the same dirty-tree dialog differently, and troubleshooting.md had no entry for the refused-switch message.

Style notes, also applied: the tickets card is additionally gated on the setup checklist being finished or skipped, and the loose-edits question can be raised from the Attach to Trac card's link field too.

The pass also confirmed what was most likely to be wrong and was not: every other quoted label and message is verbatim, all six screenshots match their alt text, #deleting-a-ticket-s-work resolves under VitePress's slugifier, and the new page is in the sidebar.

Implementation notes

How the screenshots were taken. git worktree add from the stack tip, then git checkout <trunk> -- scripts/screenshots docs/…, playwright-core installed, and the TOOLKIT_USER_DATA_DIR hook from src/main.js re-applied — the stack predates all of it, so npm run shots does not exist on that branch. Two throwaway fixture variants were added, both building real repositories through the app's own src/ticket-branches.js (startTicketBranch, parkCurrentWork, switchToBranch) so the state is the state the app makes: one site on ticket/29798 with parked work and a second branch, one parked back on trunk with a loose edit. Same 1200×800 window and --force-device-scale-factor=1 as capture.cjs, so the new images sit beside the existing ones without a size jump. The worktree has been removed.

The new slugs, none of which shots.cjs knows about: ticket-list-card, ticket-list-unlinked, trunk-work-question, carried-work-notice, linked-pull-requests, site-with-tickets.

linked-pull-requests.png is one image doing three jobs — the coloured state pills (#243), the unsubmitted-changes note (#241), and the reorganised ticket card with the tickets list no longer inside it (#242).

docs/ is its own npm package, so npm run docs:build needs npm --prefix docs ci first on a fresh checkout.

Screenshots or recording

Six new images, and one replaced.

The tickets card, linked — ticket-list-card.png:

The tickets card, unlinked — ticket-list-unlinked.png:

The question about loose trunk edits — trunk-work-question.png:

After choosing to carry them — carried-work-notice.png:

The ticket card with coloured pull request states and the unsubmitted-work note — linked-pull-requests.png:

The three cards in their new order — site-with-tickets.png:

Replaced: site-view.png, whose action bar read Submit changes. No stack behaviour is visible in it — it is a straight re-take of a stale image.