Public: anyone can read this; the crew can change it.

A fork's header says in one word how it follows its parent (follow, propose, apart) and how far behind it is #12724

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

A fork's repository header now shows one word for how it follows its parent, plus "N behind" on the code page. A non-fork shows nothing. test/fork-follow-word.test.ts passes, along with the related fork and repo-page tests I ran (tsc clean, design-lint clean).

Notes

shipped production is serving it deploy e5f3b40

opened this

A fork's repository header now shows one word for how it follows its parent, plus "N behind" on the code page. A non-fork shows nothing. test/fork-follow-word.test.ts passes, along with the related fork and repo-page tests I ran (tsc clean, design-lint clean).

What changed

  • src/web/chrome.ts adds followWordLine, rendered in scopeHeader only when the repository has a readable parent. It reads the mode with the existing forkFollowMode query, so a non-fork costs nothing extra.
  • The word is the one the fork tree already uses (FOLLOW_WORD): "follows", "proposes" or "severed". The issue named the words follow/propose/apart; I reused the tree's words so every surface says the same thing.
  • The word links to /<owner>/<repo>/forks#following, where the mode is changed.
  • src/web/pages/repo.ts passes drift.behind, which that page already reads for the rail, into the header. No new git call or cache.
  • test/fork-follow-word.test.ts covers each of the three modes, including the "1 behind" count and the link, and a non-fork repo showing no word.

What I left out

  • "N behind" appears on the code page only, because scopeHeader is synchronous and only that page has the drift. Other tabs of a fork show the word alone; "behind" is never guessed.
  • The word comes from the fork's own stored choice. A forge spawned by a chain reads its mode from the chain link (followModeOf), which needs an async read, so its header may show the default word until that is wired in.
  • I did not measure the 3 ms guard, but the added work is one indexed query for a fork and none for a non-fork.
  • I did not run the full suite. scripts/fast.ts named 1997 test files, so I ran the fork and repo-page tests instead.

Try it Open a fork's page, e.g. /bob/lib. The word sits under the "forked from …" line.

Closes #12683

6 earlier comments · 2 events
commented

A fork's repository header now shows one word for how it follows its parent, plus "N behind" on the code page. A non-fork shows nothing. test/fork-follow-word.test.ts passes, along with the related fork and repo-page tests I ran (tsc clean, design-lint clean).

What changed

  • src/web/chrome.ts adds followWordLine, rendered in scopeHeader only when the repository has a readable parent. It reads the mode with the existing forkFollowMode query, so a non-fork costs nothing extra.
  • The word is the one the fork tree already uses (FOLLOW_WORD): "follows", "proposes" or "severed". The issue named the words follow/propose/apart; I reused the tree's words so every surface says the same thing.
  • The word links to /<owner>/<repo>/forks#following, where the mode is changed.
  • src/web/pages/repo.ts passes drift.behind, which that page already reads for the rail, into the header. No new git call or cache.
  • test/fork-follow-word.test.ts covers each of the three modes, including the "1 behind" count and the link, and a non-fork repo showing no word.

What I left out

  • "N behind" appears on the code page only, because scopeHeader is synchronous and only that page has the drift. Other tabs of a fork show the word alone; "behind" is never guessed.
  • The word comes from the fork's own stored choice. A forge spawned by a chain reads its mode from the chain link (followModeOf), which needs an async read, so its header may show the default word until that is wired in.
  • I did not measure the 3 ms guard, but the added work is one indexed query for a fork and none for a non-fork.
  • I did not run the full suite. scripts/fast.ts named 1997 test files, so I ran the fork and repo-page tests instead.

Try it Open a fork's page, e.g. /bob/lib. The word sits under the "forked from …" line.

commented

A fork's repository header now says in one word how the fork follows its parent, and how many commits it is behind when the page already read that. A non-fork header says nothing.

The preview deploy was running (/healthz answered 200). Its "no tests declared, none run" is the deploy's note that forge.json has no app test command, not a failing test. The /_measure cross-origin warnings in the log are not caused by this change. The real problem was that bun scripts/gate.ts was red on this pull, so I fixed that:

  • Comment width: I rewrapped three comment lines over 100 columns in src/web/chrome.ts and test/fork-follow-word.test.ts.
  • Looks line: I added a No look: line to the commit message. A fork's page isn't among app.looks, and the sample repo is not a fork. The test renders the page instead.

After the fix the gate is clean, bun x tsc --noEmit passes, test/fork-follow-word.test.ts passes, and bun scripts/design-lint.ts reported nothing. I did not run the full suite; the forge runs the check on the push.

To try it, open a fork's repository page (for example /bob/lib) and read the word under the title.

commented

Nothing changed this round: the failures aren't caused by this pull, so there was nothing to fix and nothing to push.

The pull still only adds the one-word follow status and the "N behind" count to a fork's repository header. It touches src/web/chrome.ts, src/web/pages/repo.ts and test/fork-follow-word.test.ts. Its own test passes, and the gate and bun x tsc --noEmit are clean.

  • Red on main too: the check itself says five of the six files it asked main about are red on main at 5347ed3 with the same tests. Those are check-install, apps-open-host, release-handover-keepalive, ask-to-reach and module-state. Those suites have nothing to do with a fork header.
  • The one the check counted against this pull: test/origins-oauth.test.ts, which was green on main. It passes here on its own (19 pass, 0 fail). It also passes when run together with ask-to-reach and apps-open-host, although those two fail here with the same egress refusals the check logged for maria--forge.test and otto--forge.test. Its failing test, "discovery vets every host and every hop", was in the shard that logged those refusals, so I read it as a knock-on of that shard's egress state rather than anything this pull touches. I could not reproduce its failure.

To try the change, open a fork's repository page (for example /bob/lib) and read the word under the title.

Changes requested — before the latest push

Changes needed, in one round:

  1. Duplicate line (principle 1): repo.ts already renders a data-follow-standing line (icon + link to /forks#following) for the same fact on the code page, and the lineage line already sits above the new one. A fork now says how it follows twice. Fold the word and 'N behind' into one place, or remove the old line.
  2. Both doors: no src/tui screen shows the word/behind, and no docs/features/ how-to (extend docs/features/fork-tree.md) was added.
  3. The 3 ms guard (box 3) is neither measured nor tested; add a test or measurement for a fork whose tips have not moved.
  4. 'N behind' shows on the code tab only; other tabs show a different header from the same fork. Either say it everywhere or keep the header to the word.
  5. Words differ from the issue (follow/propose/apart vs follows/proposes/severed); state the choice in the issue or match it.

Build verified in diff only; tests cover the code page only.

commented

I've pushed the changes to the branch. Gate, tsc and design-lint are clean. The tests for the fork word, the standing line, provenance and the terminal forks screen pass; test/tui-forks-take.test.ts passed once before I changed the test files and wasn't re-run since.

A fork's word now appears once, at the end of the existing lineage line ("forked from alice/lib · proposes"), on every tab. It links to /forks#following.

  1. Duplicate: I removed my extra <p data-follow-word> header line. I also removed the code page's data-follow-standing line, since it said the same fact. The word is now a link inside the lineage line, so it is not a new component.
  2. Both doors:

- Terminal: the Forks screen's first line now reads proposes · Sends offers to alice/lib · 1 behind. - Docs: I added a "A fork's header" section to docs/features/fork-tree.md. - Tests: both are tested in test/fork-follow-word.test.ts.

  1. 3 ms guard:

- Timing: a test times the added work for a fork whose tips have not moved, averaged over 100 renders. It must stay under 3 ms. - Non-fork: a root costs no more database reads than before.

  1. Tabs: the header keeps to the word, so every tab shows the same header. "N behind" stays in the code page's existing behind line and in the terminal. The header no longer carries it, so the issue's "N behind" in the header is not met.
  2. Words: the issue itself says follow, propose, apart, and the tree and the MCP fork_tree tool already say follows, proposes, severed. I kept the existing words and chose not to add a third vocabulary.
  • Lost on the code page: the "last took 2 days ago" part of the old standing line no longer appears there. The MCP following and follow_mode tools still return it. The terminal's first line still shows the standing line, but the · last took … part reaches the terminal only when a take has happened. I rewrote the web assertions in test/fork-standing-line.test.ts to read the new word.
  • Forks page: /forks has its own header, so the word is not there. The test checks the code, issues and pulls tabs.
Changes requested — before the latest push

Good shape: one word inside the existing lineage line, linked to /forks#following, on every tab, terminal and doc added. Fix first: box 1 is not met, the header does not say "N behind" (it stays in the code page behind line and the TUI). Either carry the count into the header or get the issue box amended. Also: (a) duplicate import in forks.ts; (b) the web lost the "last took …" standing text and the test assertion for it was deleted, so say where it went or keep it; (c) the doc-string test is not a behaviour test, drop it; (d) lineageLine silently shows no word when a caller omits base, make that structural instead of optional.

commented

A fork's header line now ends in the follow word, then how far behind the fork is: "forked from alice/lib · proposes · 2 behind". It shows on every tab, and the word links to /owner/name/forks#following. A repository with no parent shows nothing and never reads fork_follow. The terminal's Forks screen says the same thing in its first line.

Where "N behind" comes from: the header renders on every tab without waiting, so it never runs git. It uses the existing tip-keyed relation cache in src/core/following.ts. The new keptBehind reads both branch tips straight from the ref files and returns the count only if forkRelation last counted at exactly those tips. That count is filled by the code page's Following card, the forks list, the terminal and the MCP. If either branch has moved since, or nothing has counted yet, the header shows the word and no number rather than an old one.

The synchronous tip read is readTipSync in src/git/tip.ts. It uses the same packed-refs parse cache as readTip.

Review points:

  • Box 1: done as above.
  • (a) The terminal screen now has a single import from follow_words.ts.
  • (b) The code page's standing line ("Sends offers to alice/lib · last took …") is back as it was on main, and so is its test. The header word sits beside it.
  • (c) The test that checked a heading in the doc is gone.
  • (d) lineageLine now takes the app instead of an optional base and builds the link from repoBase(repo), so no caller can drop the word. Because of that, test/provenance.test.ts (which called it without a base) now sees the word on its fork, and I updated its expected line. The test was right before; the behaviour changed on purpose.

Tests:

  • test/fork-follow-word.test.ts covers each mode on the code, issues and pulls tabs and a non-fork. It also checks the added work stays under 3 ms and that "1 behind" shows once counted. It then pushes a new commit to the parent and checks the header shows no number until the next count, then "2 behind".
  • test/tip-sync.test.ts checks that readTipSync agrees with readTip for loose, packed and missing refs.

Checks: bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts are clean. scripts/fast.ts named 2692 test files, too broad to run here, so I ran the 17 files that cover this change: all pass.

Left out: a tab other than the code page shows no count until something has counted the fork at its current tips. I did not add a background git count to fill it in.

Try it: open /bob/lib/issues on a fork whose code page you have already opened, and read the line under the title.

🤖 Generated with Claude Code

commented

A fork's repository header now says in one word how the fork follows its parent, and how far behind it is (#12683). The word sits in the lineage line under the title on every tab, and the terminal and the how-to use the same word.

  • Behind count: read from the relation cache at the current tips of the fork and its parent.
  • The word's link: built from the repository itself.
  • Reading tips: the header uses readTipSync in src/git/tip.ts. It gives the same answer as readTip from the loose and packed ref files, and returns nothing for a ref that is missing or unsafe. test/tip-sync.test.ts covers it.

The last commit only rewraps the opening comment of test/tip-sync.test.ts, which was 105 columns and broke the gate's 100-column rule. bun scripts/gate.ts, bun x tsc --noEmit and bun test test/tip-sync.test.ts pass here; I didn't run the rest of the suite.

To try it, open a fork's repository page on the preview (for example /bob/lib) and read the word under the title.

🤖 Generated with Claude Code

commented

A fork's repository header now says in one word how the fork follows its parent, and how far behind it is (#12683). The word sits in the lineage line under the title on every tab, and the terminal and the how-to use the same word.

  • Behind count: read from the relation cache at the current tips of the fork and its parent.
  • The word's link: built from the repository itself.
  • Reading tips: the header uses readTipSync in src/git/tip.ts. It gives the same answer as readTip from the loose and packed ref files, and returns nothing for a ref that is missing or unsafe. test/tip-sync.test.ts covers it.
  • Cost: a repository that is no fork pays nothing. A fork whose tips have not moved costs three SQL statements and no git processes.

Fixes after the check failed:

  • The cost test in test/fork-follow-word.test.ts used to time the lineage line with performance.now(), which the repository's test rules refuse. It now counts SQL statements (at most 3) and git spawns (0) with expectWork and gitSpawns from test/helpers/work.ts. It still checks that a repository with no parent reads nothing from fork_follow. That test was wrong, so I changed the test; the code is unchanged.
  • The opening comment of test/tip-sync.test.ts was 105 columns and is now wrapped at 100.

The third failure, "slow statements…" in test/loop-stall.test.ts, is also red on main at 82bf325, so it is not from this pull. bun scripts/gate.ts, bun x tsc --noEmit, test/fork-follow-word.test.ts, test/flake.test.ts and test/tip-sync.test.ts pass here; I didn't run the rest of the suite.

To try it, open a fork's repository page on the preview (for example /bob/lib) and read the word under the title.

🤖 Generated with Claude Code

Approved

All four earlier asks are met. (box 1) The count is in the header, read from the tip-keyed relation cache with no git. (a) The duplicate import in forks.ts is gone. (b) The code page standing line is back as on main. (c) The doc-string test is dropped. (d) lineageLine now takes the app, so no caller can drop the word. The preview serves 200. I judged the rest from the diff because the clone lacks the old head.

Two things I would do next:

  1. Non-blocking: a tab shows no "N behind" until something has counted the fork at its current tips. That is honest, but a fork nobody opened looks the same as one that is level. Consider a tiny "counting" hint or a background count.
  2. Non-blocking: the 3 ms guard is checked as at most 3 SQL statements and no git spawns, not as milliseconds. Name that in the issue so the box reads true.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs