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

A fork's page names how it follows upstream (automatic or propose only) in one plain line with the one action to change it #14741

Merged opened this

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

Merged

mason/forge:mason/14706-a-fork-s-page-names-how-it-follows-upstr → main 6 commits fork 4 threads · 4 unresolved

  • Merged. mason/14706-a-fork-s-page-names-how-it-follows-upstr was merged into main as 08ee03a.

Review

Sign in to review this change.
10 files changed +188 −27
docs/features/follow-choice.md +4
@@ -12,6 +12,10 @@ A fork says how it follows its upstream with three named choices, each with one
1212 | Follow and ask | `tell-me` | You are told when the upstream has something new, and nothing is merged until you take it. |
1313 | Stay as is | `dont-follow` | Nothing from the upstream is merged or announced here; you can still offer changes up. |
1414
15 ## Where the line is
16
17 A fork's header says how it follows in one plain sentence, inside the lineage line (`forked from alice/lib · Follows upstream automatically · 3 behind`): "Follows upstream automatically", "Proposes upstream changes for you to take" or "Does not follow upstream". The fork's admin sees it as a link to `/settings#follow-choice`, where the choice changes; everyone else reads it as text. The MCP `fork_tree` read carries the same sentence as `line` (null for a repository that is no fork), and the terminal's fork tree opens with it. The words live once, in `FOLLOW_LINE` (`src/actions/follow_words.ts`).
18
1519 ## On the web
1620
1721 Open a fork's `/settings`. The choice is the first thing in the Follow upstream card; pick one and Save. It posts to `/:owner/:name/following/mode`, which checks the origin and the value.
docs/features/fork-tree.md +7 −6
@@ -18,12 +18,13 @@ A repository you may not read answers "not found", as everywhere else.
1818
1919 ## A fork's header
2020
21 Under the title of a fork the line "forked from alice/lib" ends in the same one word, `follows`, `proposes` or
22 `severed`, linked to the setting that changes it (`/owner/name/forks#following`), then how far behind it is:
23 "forked from alice/lib · proposes · 2 behind". It is on every tab of the repository, not only the code tab, and a
24 repository with no parent (or one whose parent you may not read) has no word. The count is the one the fork's
25 relation last read at these two tips (the code page, the Following card, the terminal and the MCP all read it);
26 when either branch has moved since, the header says no number rather than an old one, and never runs git to
21 Under the title of a fork the line "forked from alice/lib" ends in one plain sentence (`Follows upstream automatically`,
22 `Proposes upstream changes for you to take` or `Does not follow upstream`), a link to the setting that changes it
23 (`/owner/name/settings#follow-choice`) for the fork's admin and plain text for everyone else, then how far behind it is:
24 "forked from alice/lib · Proposes upstream changes for you to take · 2 behind". It is on every tab of the repository,
25 not only the code tab, and a repository with no parent (or one whose parent you may not read) has no word. The count is
26 the one the fork's relation last read at these two tips (the code page, the Following card, the terminal and the MCP all
27 read it); when either branch has moved since, the header says no number rather than an old one, and never runs git to
2728 find out. The code page still says the plain standing ("Sends offers to alice/lib · last took 2 hours ago")
2829 where no behind line speaks. In the terminal the Forks screen's first line reads
2930 `proposes · Sends offers to alice/lib · 1 behind`.
src/actions/follow.ts +9 −1
@@ -14,7 +14,7 @@ import type { User } from "../core/users.ts";
1414 import { err, ok, type Result } from "../kernel/result.ts";
1515 import { chainOfRepo, forgeLinkOf, FOLLOW_MODES, isFollowMode, setChainMode, severChain } from "../spawn/chain.ts";
1616 import { FAMILY_WORDS } from "./family_words.ts";
17 import { FOLLOWS_NOTHING, agoWords, driftWords, followModeWords, followStandingLine } from "./follow_words.ts";
17 import { FOLLOWS_NOTHING, FOLLOW_LINE, agoWords, driftWords, followModeWords, followStandingLine } from "./follow_words.ts";
1818 import { FORK_FOLLOW_MODES, forkFollowMode, lastTookAt, isForkFollowMode, setForkFollowMode, type ForkFollowMode } from "../core/fork_follow.ts";
1919 import { requireUser } from "./access.ts";
2020 import { getFollow, setFollowTaking } from "../core/upstream_follow.ts";
@@ -133,6 +133,14 @@ export async function followModeOf(app: App, repo: Repo): Promise<ForkFollowMode
133133 return upstream !== undefined && upstream.severedAt === null ? upstream.mode : forkFollowMode(app.db, repo.id);
134134 }
135135
136 /**
137 * The one plain sentence on how a fork follows its upstream (#14706), read from the same mode the
138 * tree rows word; null for a repository that is no fork.
139 */
140 export async function followLine(app: App, repo: Repo): Promise<string | null> {
141 return repo.forkParentId === null ? null : FOLLOW_LINE[await followModeOf(app, repo)];
142 }
143
136144 /**
137145 * The line a fork's page and the MCP say: its choice and its last movement;
138146 * undefined for a repository that is no fork. A parent the viewer cannot
src/actions/follow_words.ts +10
@@ -108,6 +108,16 @@ export function agoWords(iso: string, now: number = Date.now()): string {
108108 return unit(Math.floor(seconds / (86_400 * 365)), "year");
109109 }
110110
111 /**
112 * The plain line a fork's header and the MCP tree read say of how it follows (#14706): no names,
113 * so a person and an agent get one sentence.
114 */
115 export const FOLLOW_LINE: Readonly<Record<ForkFollowMode, string>> = {
116 "take-updates": "Follows upstream automatically",
117 "tell-me": "Proposes upstream changes for you to take",
118 "dont-follow": "Does not follow upstream",
119 };
120
111121 /** The words that name a fork's choice, by mode, before the upstream. */
112122 const STANDING_LEADS: Record<ForkFollowMode, string> = {
113123 "take-updates": "Takes updates from",
src/actions/fork_tree_rows.ts +5 −2
@@ -10,7 +10,7 @@
1010 import type { App } from "../app.ts";
1111 import { canRead, listAncestors, visibleForks, type Repo } from "../core/repos.ts";
1212 import type { User } from "../core/users.ts";
13 import { followModeOf } from "./follow.ts";
13 import { followLine, followModeOf } from "./follow.ts";
1414 import { FOLLOWS_NOTHING, followModeWords } from "./follow_words.ts";
1515 import { driftOfForks, driftWords, MAX_RANKED_FORKS } from "./forks.ts";
1616
@@ -28,6 +28,8 @@ export interface TreeRow {
2828 }
2929
3030 export interface TreeRows {
31 /** How the repo follows, the sentence the header says too (#14706); null for no fork. */
32 readonly line: string | null;
3133 readonly app: TreeRow;
3234 readonly upstream: TreeRow[];
3335 readonly forks: TreeRow[];
@@ -62,5 +64,6 @@ export async function forkTreeRows(app: App, repo: Repo, user: User | undefined)
6264 Promise.all(chain.map((r, i) => rowOf(app, r, chain[i + 1]))),
6365 Promise.all(shown.map((f) => rowOf(app, f, repo))),
6466 ]);
65 return { app: self, upstream, forks, truncated: all.length > shown.length };
67 const line = await followLine(app, repo);
68 return { line, app: self, upstream, forks, truncated: all.length > shown.length };
outdated

Mode comes from forkFollowMode, but the rows' own 'follows' text uses followModeOf; the two can disagree (forge link / severed upstream follow). Use one source so MCP and page say one sentence.

6669 }
src/tui/screens/fork_tree.ts +7
@@ -6,6 +6,7 @@
66
77 import { HIDDEN_FORK_WORD, treeFollowPhrase } from "../../actions/follow_words.ts";
88 import { forkTree, type ForkTree } from "../../actions/fork_tree.ts";
9 import { followLine } from "../../actions/follow.ts";
910 import type { Repo } from "../../core/repos.ts";
1011 import type { Ctx, Screen } from "../app/app.ts";
1112 import { binding } from "../app/keys.ts";
@@ -34,12 +35,18 @@ export function treeLines(tree: ForkTree | undefined, asked: string, width = 80,
3435 export function forkTreeScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
3536 const scroll = new Scroll();
3637 let lines: string[] = [];
38 let head: string | null = null;
3739 return {
40 async load() {
41 head = await followLine(f.app, repo);
42 },
3843 title: `Fork tree · ${repo.ownerName}/${repo.name}`,
3944 keys: [binding(["j", "k"], "scroll"), binding(["esc"], "back")],
4045 render(area, s) {
outdated

New terminal behaviour with no test that would fail without it; add one.

4146 const c = ctx.theme.c;
4247 lines = treeLines(forkTree(f.db, repo, f.user, f.app), `${repo.ownerName}/${repo.name}`, area.w - 4, f.user?.username);
48 // The same plain sentence the fork's header and the MCP tree read say (#14706).
49 if (head !== null) lines = [head, "", ...lines];
4350 const from = scroll.window(area.h, lines.length);
4451 for (let i = 0; i < area.h; i++) {
4552 const line = lines[from + i];
src/web/chrome.ts +17 −10
@@ -13,6 +13,7 @@ import { MACHINE_PREFIX, typedMiss } from "../http/asset_miss.ts";
1313 import { audienceFacts, audienceOf } from "../core/audience.ts";
1414 import { activeEdgeToken, edgeLoginUrl, edgeStrangerLogin } from "../http/edge.ts";
1515 import {
16 canAdmin,
1617 canRead,
1718 forkParentFor,
1819 getRepo,
@@ -23,7 +24,7 @@ import { parentUrl, shownTrail, sourceLabel } from "../core/provenance.ts";
2324 import type { App } from "../app.ts";
2425 import type { Ctx } from "../http/context.ts";
2526 import { apiError, prefersJson } from "../http/respond.ts";
26 import { FOLLOW_WORD } from "../actions/follow_words.ts";
27 import { FOLLOW_LINE } from "../actions/follow_words.ts";
2728 import { forkFollowMode } from "../core/fork_follow.ts";
2829 import { keptBehind, MINE_ANCHOR, ownsInTree } from "../core/following.ts";
2930 import { html, raw, when, type Html } from "./html.ts";
@@ -329,7 +330,7 @@ export function scopeHeader(
329330 !options.compact && facts.description !== "",
330331 () => html`<p class="muted small">${facts.description}</p>`,
331332 )}
332 ${repo === undefined ? null : lineageLine(ctx.app, repo, parent, family)}
333 ${repo === undefined ? null : lineageLine(ctx.app, repo, parent, family, parent !== undefined && canAdmin(ctx.app.db, repo, ctx.auth.user) ? `${base}/settings#follow-choice` : undefined)}
333334 ${when(
outdated

Principle 1: a third line under the lineage line about the same relationship; nothing should explain itself twice. Merge into lineageLine or the existing followingLine.

334335 scope.upstream !== undefined && upstreamHref(scope) === undefined,
335336 // The where strip carries "fork of octo/widgets" and links it, which
@@ -378,6 +379,8 @@ export function lineageLine(
378379 parent: Repo | undefined,
379380 /** The other forks of `parent` (`familyOf`); absent says none. */
380381 family?: Family,
382 /** Where the viewer changes how the fork follows; absent for anyone who may not, so no link. */
383 followHref?: string,
381384 ): Html | null {
382385 const db = app.db;
383386 const shown = shownTrail(db, repo, parent);
@@ -397,7 +400,7 @@ export function lineageLine(
397400 html`forked from
398401 <a href="/${parent.ownerName}/${parent.name}"
399402 >${parent.ownerName}/${parent.name}</a
400 > · ${followWord(app, repo, parent)}${others}`,
403 > · ${followWord(app, repo, parent, followHref)}${others}`,
401404 );
402405 if (shown !== undefined) {
403406 segments.push(
@@ -413,15 +416,19 @@ export function lineageLine(
413416 }
414417
415418 /**
416 * How a fork follows its parent, in one word that links to the setting, then how far behind it
417 * is when the relation cache counted it at these tips (#12683). One indexed read and two ref
418 * files; no git. Only ever drawn beside a parent, so a repository that is no fork pays nothing.
419 * How a fork follows its parent, in the one plain sentence every door says (`FOLLOW_LINE`, #14706),
420 * linked to the setting for whoever may change it, then how far behind it is when the relation
421 * cache counted it at these tips (#12683). One indexed read and two ref files; no git. Only ever
422 * drawn beside a parent, so a repository that is no fork pays nothing.
419423 */
420 function followWord(app: Pick<App, "db" | "reposRoot">, repo: Repo, parent: Repo): Html {
424 function followWord(app: Pick<App, "db" | "reposRoot">, repo: Repo, parent: Repo, href?: string): Html {
421425 const behind = keptBehind(app, repo, parent);
422 return html`<a href="${repoBase(repo)}/forks#following" data-follow-word
423 >${FOLLOW_WORD[forkFollowMode(app.db, repo.id)]}</a
424 >${behind === undefined ? null : html` · <span data-follow-behind>${behind} behind</span>`}`;
426 const said = FOLLOW_LINE[forkFollowMode(app.db, repo.id)];
427 return html`${
428 href === undefined
429 ? html`<span data-follow-word>${said}</span>`
430 : html`<a href="${href}" data-follow-word>${said}</a>`
431 }${behind === undefined ? null : html` · <span data-follow-behind>${behind} behind</span>`}`;
425432 }
426433
427434 /**
test/fork-follow-line.test.ts added +121
@@ -0,0 +1,121 @@
1 /**
outdated

Add a TUI case here, and a docs/features how-to for the line (README is not the place; docs/features/follow-choice.md is).

2 * A fork's lineage line, the MCP tree read and the terminal's fork tree say how it follows upstream
3 * in one plain sentence (#14706).
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
10 import { forkTreeRows } from "../src/actions/fork_tree_rows.ts";
11 import { createApp, type App } from "../src/app.ts";
12 import { setForkFollowMode } from "../src/core/fork_follow.ts";
13 import { getRepo } from "../src/core/repos.ts";
14 import { createUser } from "../src/core/users.ts";
15 import { createForgeApp } from "../src/tui/forge.ts";
16 import { forkTreeScreen } from "../src/tui/screens/fork_tree.ts";
17 import { headlessTerminal } from "../src/tui/term/terminal.ts";
18 import { settleApp } from "./helpers/tui.ts";
19 import { serve, type Servers } from "../src/http/server.ts";
20 import { promote } from "./helpers/members.ts";
21
22 let dataDir = "";
23 let app: App;
24 let servers: Servers;
25 let forkId = "";
26 const users: Record<string, any> = {};
27 const cookies: Record<string, string> = {};
28
29 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
30 if (!r.ok) throw new Error(JSON.stringify(r.error));
31 return r.value;
32 };
33 const page = async (path: string, who?: string): Promise<string> =>
34 (await fetch(`${servers.url}${path}`, { headers: who ? { cookie: cookies[who]! } : {} })).text();
35 const line = (html: string): string => /<(?:a|span)[^>]*data-follow-word[^>]*>([\s\S]*?)<\/(?:a|span)>/.exec(html)?.[0] ?? "";
36
37 beforeAll(async () => {
38 dataDir = await mkdtemp(join(tmpdir(), "forge-fline-"));
39 app = createApp({ dataDir, port: 0 });
40 for (const name of ["ann", "bea", "cal"]) {
41 users[name] = must(await createUser(app.db, { origin: "seed", trusted: true, username: name, email: `${name}@f.dev`, password: "a-good-passphrase", adminIfFirst: name === "ann" }));
42 promote(app.db, users[name]);
43 }
44 const lib = must(await createRepo(app, users["ann"], { name: "lib", visibility: "public" }));
45 must(await commitToBranch(app, users["ann"], lib, { message: "start", files: [{ path: "a.txt", content: "a\n" }] }));
46 const fork = must(await forkRepo(app, users["bea"], lib));
47 forkId = getRepo(app.db, "bea", "lib")?.id ?? fork.id;
48 servers = await serve(app);
49 for (const name of ["bea", "cal"]) {
50 const res = await fetch(`${servers.url}/signin`, { method: "POST", body: new URLSearchParams({ username: name, password: "a-good-passphrase" }), redirect: "manual" });
51 cookies[name] = (res.headers.get("set-cookie") ?? "").split(";")[0]!;
52 }
53 }, 30_000);
54
55 afterAll(async () => {
56 servers?.stop();
57 app?.close();
58 await rm(dataDir, { recursive: true, force: true });
59 });
60
61 test("both modes are worded plainly, and the owner's line links to the setting", async () => {
62 setForkFollowMode(app.db, forkId, "take-updates");
63 const auto = line(await page("/bea/lib", "bea"));
64 expect(auto).toContain("Follows upstream automatically");
65 expect(auto).toContain('href="/bea/lib/settings#follow-choice"');
66 setForkFollowMode(app.db, forkId, "tell-me");
67 expect(line(await page("/bea/lib", "bea"))).toContain("Proposes upstream changes for you to take");
68 });
69
70 test("a non-owner and a stranger see the line without the link", async () => {
71 setForkFollowMode(app.db, forkId, "tell-me");
72 for (const who of ["cal", undefined]) {
73 const said = line(await page("/bea/lib", who));
74 expect(said).toContain("Proposes upstream changes for you to take");
75 expect(said).not.toContain("<a");
76 }
77 });
78
79 test("an unrelated repository shows no line", async () => {
80 expect(await page("/ann/lib", "bea")).not.toContain("data-follow-word");
81 });
82
83 test("the MCP tree read says the same sentence, and nothing for a non-fork", async () => {
84 setForkFollowMode(app.db, forkId, "take-updates");
85 const fork = getRepo(app.db, "bea", "lib")!;
86 expect((await forkTreeRows(app, fork, undefined)).line).toBe("Follows upstream automatically");
87 setForkFollowMode(app.db, forkId, "tell-me");
88 expect((await forkTreeRows(app, fork, undefined)).line).toBe("Proposes upstream changes for you to take");
89 expect((await forkTreeRows(app, getRepo(app.db, "ann", "lib")!, undefined)).line).toBeNull();
90 });
91
92 test("the line is folded into the lineage line, not a second line", async () => {
93 const html = await page("/bea/lib", "bea");
94 expect(html.match(/data-follow-word/g)?.length).toBe(1);
95 expect(html).not.toContain("data-follow-line");
96 });
97
98 const treeText = async (owner: string): Promise<string> => {
99 const terminal = headlessTerminal(120, 30);
100 const { app: tui, session } = createForgeApp(
101 app,
102 { sshUsername: "bea", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user: users["bea"]! },
103 { terminal, exitHooks: false },
104 );
105 tui.start();
106 tui.ctx.push(forkTreeScreen(session, tui.ctx, getRepo(app.db, owner, "lib")!));
107 await settleApp(tui);
108 const text = tui.screen.toText();
109 tui.stop?.();
110 return text;
111 };
112
113 test("the terminal's fork tree opens with the sentence for a fork, and not for a non-fork", async () => {
114 setForkFollowMode(app.db, forkId, "tell-me");
115 expect(await treeText("bea")).toContain("Proposes upstream changes for you to take");
116 setForkFollowMode(app.db, forkId, "take-updates");
117 expect(await treeText("bea")).toContain("Follows upstream automatically");
118 const root = await treeText("ann");
119 expect(root).not.toContain("upstream automatically");
120 expect(root).not.toContain("Proposes upstream");
121 });
test/fork-follow-word.test.ts +7 −7
@@ -63,23 +63,23 @@ afterAll(async () => {
6363
6464 const wordOf = async (path: string): Promise<{ href: string; word: string } | null> => {
6565 const page = await (await fetch(`${servers.url}${path}`)).text();
66 const m = page.match(/<a href="([^"]*)" data-follow-word\s*>([^<]*)</);
67 return m === null ? null : { href: m[1]!, word: m[2]! };
66 const m = page.match(/<(?:a href="([^"]*)"|span) data-follow-word\s*>([^<]*)</);
67 return m === null ? null : { href: m[1] ?? "", word: m[2]! };
6868 };
6969
70 test("each mode is one word linking to the setting, on the code tab and on the others", async () => {
70 test("each mode is one plain sentence in the lineage line, on the code tab and on the others", async () => {
7171 const fork = getRepo(app.db, "bob", "lib")!;
7272 const want: [Parameters<typeof setForkFollowMode>[2], string][] = [
73 ["tell-me", "proposes"],
74 ["take-updates", "follows"],
75 ["dont-follow", "severed"],
73 ["tell-me", "Proposes upstream changes for you to take"],
74 ["take-updates", "Follows upstream automatically"],
75 ["dont-follow", "Does not follow upstream"],
7676 ];
7777 for (const [mode, word] of want) {
7878 setForkFollowMode(app.db, fork.id, mode);
7979 for (const path of ["/bob/lib", "/bob/lib/issues", "/bob/lib/pulls"]) {
8080 const got = await wordOf(path);
8181 expect(got?.word, path).toBe(word);
82 expect(got?.href).toBe("/bob/lib/forks#following");
82 expect(got?.href).toBe(""); // a stranger gets the sentence, no link
8383 }
8484 }
8585 });
test/provenance.test.ts +1 −1
@@ -175,7 +175,7 @@ describe("the record and the line", () => {
175175 });
176176 const fork = { ...source, id: "not-recorded", ownerName: "someone" };
177177 const line = lineageLine(app, fork, source)!.text.replace(/\s+/g, " ");
178 expect(line).toMatch(/forked from <a href="\/trevato\/arm" ?>trevato\/arm<\/a ?> · <a href="\/someone\/arm\/forks#following" data-follow-word ?>proposes<\/a ?> · migrated/);
178 expect(line).toMatch(/forked from <a href="\/trevato\/arm" ?>trevato\/arm<\/a ?> · <span data-follow-word ?>Proposes upstream changes for you to take<\/span ?> · migrated/);
179179 expect(line).toContain(
180180 'migrated from <a href="https://github.com/Trevato/SO-ARM100" rel="noopener noreferrer">github.com/Trevato/SO-ARM100</a>',
181181 );

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs