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

Following an upstream is chosen on a fork's settings as three plain options, each saying what it does #13703

Merged opened this

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

Merged

scout/forge:scout/13681-following-an-upstream-is-chosen-on-a-for → main 9 commits fork 4 threads · 4 unresolved

  • Merged. scout/13681-following-an-upstream-is-chosen-on-a-for was merged into main as 91b259c.

Review

Sign in to review this change.
9 files changed +201 −9
docs/features/README.md +1
@@ -438,6 +438,7 @@ Read with the guide page [Backups and moving](../guide-backups-moving.md).
438438 - [Connecting an origin read-only](origin-read-only.md)
439439 - [Forge-to-forge compatibility, measured](forge-origin-compat.md)
440440 - [How a fork follows its upstream](follow-mode.md)
441 - [Choosing how a fork follows, in three named choices](follow-choice.md)
441442 - [Read an update before you take it](following-incoming.md)
442443 - [An upstream update that conflicts is one issue](upstream-conflict-issue.md)
443444 - [Moving a forge out of this forge's process into its own sandbox](sandbox-move.md)
docs/features/follow-choice.md added +19
@@ -0,0 +1,19 @@
1 # How a fork follows its upstream: three choices
2
3 A fork says how it follows its upstream with three named choices, each with one sentence. The words live once, in `FOLLOW_CHOICES` (`src/actions/follow_words.ts`); the page and the terminal both read them.
4
5 | Choice | Stored mode | What it does |
6 | --- | --- | --- |
7 | Follow and merge | `take-updates` | New code from the upstream is merged in as it lands; a conflict goes to the crew. |
8 | Follow and ask | `tell-me` | You are told when the upstream has something new, and nothing is merged until you take it. |
9 | Stay as is | `dont-follow` | Nothing from the upstream is merged or announced here; you can still offer changes up. |
10
11 ## On the web
12
13 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.
14
15 ## In the terminal
16
17 Open the forks screen. The line under "follows <parent>" names the current choice and the next line is its sentence. Press `m` to step through the three (Follow and merge, Follow and ask, Stay as is); the toast says the new choice and its sentence.
18
19 No new modes were added: the stored values are unchanged.
src/actions/follow_words.ts +22
@@ -64,6 +64,28 @@ export function followModeWords(
6464 };
6565 }
6666
67 /**

Both doors: these labels and sentences should also appear on the terminal forks screen in src/tui/, so both doors use the same words. Add docs/features/<name>.md for the how-to.

68 * The settings page's three choices (#13681): a name people read, and one sentence on what it does.
69 * The values are the stored modes; no new names.
70 */
71 export const FOLLOW_CHOICES: Record<ForkFollowMode, { readonly label: string; readonly sentence: string }> = {
72 "take-updates": {
73 label: "Follow and merge",
74 sentence: "New code from the upstream is merged in as it lands; a conflict goes to the crew.",
75 },
76 "tell-me": {
77 label: "Follow and ask",
78 sentence: "You are told when the upstream has something new, and nothing is merged until you take it.",
79 },
80 "dont-follow": {
81 label: "Stay as is",
82 sentence: "Nothing from the upstream is merged or announced here; you can still offer changes up.",
83 },
84 };
85
86 /** A choice as one line, as the page's option reads and the terminal says it. */
87 export const followChoiceLine = (mode: ForkFollowMode): string => `${FOLLOW_CHOICES[mode].label}. ${FOLLOW_CHOICES[mode].sentence}`;
88
6789 /** What switching to `mode` changes, for the confirm step. */
6890 export function followSwitchPreview(mode: ForkFollowMode, upstream: string): string {
6991 if (mode === "take-updates")
src/tui/screens/forks.ts +5 −4
@@ -21,8 +21,8 @@ import {
2121 type ForkRanking,
2222 type ForkRelation,
2323 } from "../../actions/forks.ts";
24 import { FOLLOW_PHRASE, FOLLOW_WORD, FOLLOWS_NOTHING, followModeWords, proposeRefusalWords } from "../../actions/follow_words.ts";
25 import { FOLLOW_MODE_REFUSALS, convergeWords, followModeOf, followStanding, followModeSaid, setFollowMode, takeOrTell, takeWords } from "../../actions/follow.ts";
24 import { FOLLOW_CHOICES, FOLLOW_PHRASE, FOLLOW_WORD, FOLLOWS_NOTHING, followChoiceLine, proposeRefusalWords } from "../../actions/follow_words.ts";
25 import { FOLLOW_MODE_REFUSALS, convergeWords, followModeOf, followStanding, setFollowMode, takeOrTell, takeWords } from "../../actions/follow.ts";
2626 import { incomingOf, type Incoming } from "../../actions/follow_incoming.ts";
2727 import { convergeFollowed, followedAs, followedOf } from "../../actions/upstream_sync.ts";
2828 import { forkOffers } from "../../core/fork_offers.ts";
@@ -112,9 +112,10 @@ export function followingRows(
112112 {
113113 repo: parent,
114114 name: `follows ${name}`,
115 words: mode === undefined ? words : `${words} · ${followModeWords(mode, name).line}`,
115 words: mode === undefined ? words : `${words} · ${FOLLOW_CHOICES[mode].label}`,
116116 heading: "",
117117 },
118 ...(mode === undefined ? [] : [{ repo: parent, name: ` ${FOLLOW_CHOICES[mode].sentence}`, words: "", heading: "" }]),
118119 ...(converge === undefined
119120 ? []
120121 : [
@@ -403,7 +404,7 @@ export function forksScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
403404 const set = await setFollowMode(f.app, f.user, repo, next);
404405 if (!set.ok) return ctx.toast(FOLLOW_MODE_REFUSALS[set.error].message, "danger");
405406 await read();
406 ctx.toast(followModeSaid(relation?.parent, set.value), "success");
407 ctx.toast(followChoiceLine(set.value), "success");
407408 });
408409 return true;
409410 }
src/web/pages/settings.ts +2 −2
@@ -126,7 +126,7 @@ import { outsideAgentsJs } from "./outside-agents-live.ts";
126126 import { proposalTokensSection } from "./proposal-tokens.ts";
127127 import { secretsSection } from "./secrets.ts";
128128 import { checkMemoryAt } from "../../apps/check-memory.ts";
129 import { followSourcesCard, followUpstreamCard } from "./upstream-follow.ts";
129 import { followChoiceForm, followSourcesCard, followUpstreamCard } from "./upstream-follow.ts";
130130 import { crewHereSaid, setCrewHere } from "../../actions/crew_switch.ts";
131131 import { CREW_OFF_LINE, crewBuildsHere } from "../../core/crew_switch.ts";
132132
@@ -339,7 +339,7 @@ export async function settingsPage(
339339 </form>
340340 </section>`;
341341 const secrets = secretsSection(ctx, "repo", `${repo.ownerName}/${repo.name}`);
342 const upstream = followUpstreamCard(ctx, repo);
342 const upstream = followUpstreamCard(ctx, repo, await followChoiceForm(ctx, repo));
343343 const sources = followSourcesCard(ctx, repo);
344344 const wave = html`<section class="settings-block">
345345 <h2>Cut a wave</h2>
src/web/pages/upstream-follow.ts +26 −1
@@ -32,6 +32,9 @@ import {
3232 sourceStanding,
3333 } from "../../actions/follow_sources.ts";
3434 import { listSources, stampOf, type FollowSource } from "../../core/follow_sources.ts";
35 import { FORK_FOLLOW_MODES } from "../../core/fork_follow.ts";
36 import { FOLLOW_CHOICES } from "../../actions/follow_words.ts";
37 import { followModeOf } from "../../actions/follow.ts";
3538 import { canAdmin, type Repo } from "../../core/repos.ts";
3639 import { getProvenance } from "../../core/provenance.ts";
3740 import { getFollow, listChecks } from "../../core/upstream_follow.ts";
@@ -154,12 +157,13 @@ function historyList(ctx: Ctx, repo: Repo): Html | null {
154157 }
155158
156159 /** The settings card: on or off, the URL and branch, and "Check upstream now". */
157 export function followUpstreamCard(ctx: Ctx, repo: Repo): Html | null {
160 export function followUpstreamCard(ctx: Ctx, repo: Repo, choice: Html | null = null): Html | null {
158161 if (!canAdmin(ctx.app.db, repo, ctx.auth.user)) return null;
159162 const follow = getFollow(ctx.app.db, repo.id);
160163 const base = repoBase(repo);
161164 return html`<section class="settings-block" id="upstream">
162165 <h2>Follow upstream</h2>
166 ${choice}
163167 <form method="post" action="${base}/settings/upstream">
164168 <p class="muted">
165169 New upstream commits arrive as a pull; never a push to
@@ -392,3 +396,24 @@ export async function followSourcesCheck(ctx: Ctx): Promise<Response> {
392396 );
393397 return flashTo(ctx, `${repoBase(repo)}/settings#sources`, { message: lines.join(" ") || "No sources to check." });
394398 }
399
400 /**
401 * A fork's three plain options, each with one sentence, saved by the mode route; drawn inside the
402 * Follow upstream card, so following is chosen in one place.
403 */
outdated

Principle 1/7: a second card that sets the same follow mode as the existing Follow upstream card and the following card. Fold the three options into one place rather than a third card.

404 export async function followChoiceForm(ctx: Ctx, repo: Repo): Promise<Html | null> {
405 if (repo.forkParentId === null || !canAdmin(ctx.app.db, repo, ctx.auth.user)) return null;
406 const current = await followModeOf(ctx.app, repo);
407 return html`<form method="post" action="${repoBase(repo)}/following/mode" id="follow-choice">
408 <fieldset class="form-field">
409 <legend>How this fork follows its upstream</legend>
outdated

Principle 1: the heading already says what this is for, so the Choose one legend explains it a second time. Drop the legend text, or use the heading as the legend.

410 ${FORK_FOLLOW_MODES.map(
411 (m) => html`<label class="row" data-follow-choice="${m}"
412 ><input type="radio" name="mode" value="${m}" ${m === current ? html`checked` : null} />
413 <span><strong>${FOLLOW_CHOICES[m].label}.</strong> ${FOLLOW_CHOICES[m].sentence}</span></label
414 >`,
415 )}
416 </fieldset>
417 <div class="form-actions">${btn("Save")}</div>
418 </form>`;
419 }
test/follow-choice.test.ts added +115
@@ -0,0 +1,115 @@
1 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
2 import { mkdtemp, rm } from "node:fs/promises";
3 import { tmpdir } from "node:os";
4 import { join } from "node:path";
5 import { createApp, type App } from "../src/app.ts";
6 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
7 import { forkFollowMode } from "../src/core/fork_follow.ts";
8 import { getRepo } from "../src/core/repos.ts";
9 import { createUser } from "../src/core/users.ts";
10 import { promote } from "./helpers/members.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12
13 let dataDir = "";
14 let app: App;
15 let servers: Servers;
16 let base = "";
17 let bea = "";
18 let cal = "";
19 let forkId = "";
20
21 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
22 if (!r.ok) throw new Error(JSON.stringify(r.error));
23 return r.value;
24 };
25 const signIn = async (username: string): Promise<string> =>
26 (
27 (await fetch(`${base}/signin`, { method: "POST", body: new URLSearchParams({ username, password: "a-good-passphrase" }), redirect: "manual" }))
28 .headers.get("set-cookie") ?? ""
29 ).split(";")[0]!;
30 const save = (cookie: string, mode: string) =>
31 fetch(`${base}/bea/yard/following/mode`, {
32 method: "POST",
33 headers: { cookie, origin: base },
34 body: new URLSearchParams({ mode }),
35 redirect: "manual",
36 });
37 const settings = async (cookie: string, path = "bea/yard") =>
38 (await fetch(`${base}/${path}/settings`, { headers: { cookie } })).text();
39
40 beforeAll(async () => {
41 dataDir = await mkdtemp(join(tmpdir(), "forge-follow-choice-"));
42 app = createApp({ dataDir, port: 0 });
43 const users: Record<string, Awaited<ReturnType<typeof createUser>> extends infer R ? (R extends { ok: true; value: infer V } ? V : never) : never> = {};
44 for (const name of ["ann", "bea", "cal"])
45 users[name] = must(
46 await createUser(app.db, { origin: "seed", trusted: true, username: name, email: `${name}@f.dev`, password: "a-good-passphrase", adminIfFirst: name === "ann" }),
47 );
48 for (const u of Object.values(users)) promote(app.db, u);
49 const original = must(await createRepo(app, users["ann"]!, { name: "yard", visibility: "public" }));
50 must(await commitToBranch(app, users["ann"]!, original, { message: "start", files: [{ path: "a.txt", content: "a\n" }] }));
51 const fork = must(await forkRepo(app, users["bea"]!, original));
52 forkId = getRepo(app.db, "bea", "yard")?.id ?? fork.id;
53 servers = await serve(app);
54 base = servers.url;
55 bea = await signIn("bea");
56 cal = await signIn("cal");
57 }, 30_000);
58
59 afterAll(async () => {
60 servers?.stop();
61 app?.close();
62 await rm(dataDir, { recursive: true, force: true });
63 });
64
65 describe("the fork's settings offer three choices", () => {
66 test("each with a name and one sentence, the current one checked", async () => {
67 const page = await settings(bea);
68 for (const label of ["Follow and merge", "Follow and ask", "Stay as is"]) expect(page).toContain(label);
69 for (const v of ["take-updates", "tell-me", "dont-follow"]) expect(page).toContain(`value="${v}"`);
70 expect(page).toMatch(/value="tell-me"\s+checked/);
71 });
72
73 test.each(["take-updates", "dont-follow", "tell-me"])("%s is saved and shown on the fork's page", async (mode) => {
74 const res = await save(bea, mode);
75 expect(res.status).toBeLessThan(400);
76 expect(forkFollowMode(app.db, forkId)).toBe(mode);
77 expect(await settings(bea)).toMatch(new RegExp(`value="${mode}"\\s+checked`));
78 expect(await (await fetch(`${base}/bea/yard`, { headers: { cookie: bea } })).text()).toContain(`data-follow-mode="${mode}"`);
79 });
80
81 test("a value outside the three is refused and nothing changes", async () => {
82 await save(bea, "dont-follow");
83 const res = await save(bea, "rebase");
84 expect(res.status).toBe(303);

The refused-value test only checks the stored mode. Also assert the flash message says why, and add a cross-origin post case (same-origin check on a mutation).

85 expect(forkFollowMode(app.db, forkId)).toBe("dont-follow");
86 const shown = decodeURIComponent(res.headers.getSetCookie().join(";")).replace(/\+/g, " ");
87 expect(shown).toContain("mode is one of: tell-me, take-updates, dont-follow");
88 });
89
90 test("a post from another origin is refused and nothing changes", async () => {
91 await save(bea, "dont-follow");
92 const res = await fetch(`${base}/bea/yard/following/mode`, {
93 method: "POST",
94 headers: { cookie: bea, origin: "https://evil.example" },
95 body: new URLSearchParams({ mode: "take-updates" }),
96 redirect: "manual",
97 });
98 expect(res.status).toBeGreaterThanOrEqual(400);
99 expect(forkFollowMode(app.db, forkId)).toBe("dont-follow");
100 });
101
102 test("the settings page chooses in the Follow upstream card, not a third one", async () => {
103 const page = await settings(bea);
104 expect(page.match(/data-follow-choice="/g)?.length).toBe(3);
105 expect(page).not.toContain("Choose one");
106 expect(page.indexOf('id="follow-choice"')).toBeGreaterThan(page.indexOf('id="upstream"'));
107 expect(page.indexOf('id="follow-choice"')).toBeLessThan(page.indexOf("Upstream git URL"));
108 });
109
110 test("a stranger cannot save; the original has no choice card", async () => {
111 await save(cal, "take-updates");
112 expect(forkFollowMode(app.db, forkId)).toBe("dont-follow");
113 expect(await settings(cal, "ann/yard")).not.toContain("data-follow-choice");
114 });
115 });
test/fork-follow-mode.test.ts +2 −2
@@ -168,10 +168,10 @@ describe("the terminal", () => {
168168 test("the owner sees the mode and flips it with m", async () => {
169169 must(await setFollowMode(app, users["bea"]!, fork, "tell-me"));
170170 const before = await open("bea", "");
171 expect(before).toContain("Proposes updates from");
171 expect(before).toContain("Follow and ask");
172172 expect(before).toContain("follow mode");
173173 const after = await open("bea", "m");
174 expect(after).toContain("Follows ann/yard automatically");
174 expect(after).toContain("Follow and merge");
175175 expect(forkFollowMode(app.db, fork.id)).toBe("take-updates");
176176 });
177177
test/tui-following.test.ts +9
@@ -12,6 +12,7 @@ import { createIssue, type Issue } from "../src/core/issues.ts";
1212 import type { Pull } from "../src/core/pulls.ts";
1313 import { createApp, type App } from "../src/app.ts";
1414 import { createForgeApp } from "../src/tui/forge.ts";
15 import { FOLLOW_CHOICES } from "../src/actions/follow_words.ts";
1516 import { followingRows, forksScreen } from "../src/tui/screens/forks.ts";
1617 import { headlessTerminal } from "../src/tui/term/terminal.ts";
1718 import { settleApp } from "./helpers/tui.ts";
@@ -51,6 +52,14 @@ describe("followingRows", () => {
5152 });
5253
5354
55 test("a mode is said in the settings page's words: its name, then its sentence", () => {
56 for (const m of ["take-updates", "tell-me", "dont-follow"] as const) {
57 const rows = followingRows(at("synced", 0, 0), undefined, m);
58 expect(rows[0]!.words).toBe(`in step · ${FOLLOW_CHOICES[m].label}`);
59 expect(rows[1]!.name.trim()).toBe(FOLLOW_CHOICES[m].sentence);
60 }
61 });
62
5463 test("following nothing shows nothing", () => {
5564 expect(followingRows(undefined, undefined)).toEqual([]);
5665 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs