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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13681-following-an-upstream-is-chosen-on-a-for → main 9 commits fork 4 threads · 4 unresolved
docs/features/README.md +1
| @@ -438,6 +438,7 @@ Read with the guide page [Backups and moving](../guide-backups-moving.md). | ||
| 438 | 438 | - [](origin-read-only.md) |
| 439 | 439 | - [](forge-origin-compat.md) |
| 440 | 440 | - [](follow-mode.md) |
| 441 | - [](follow-choice.md) | |
| 441 | 442 | - [](following-incoming.md) |
| 442 | 443 | - [](upstream-conflict-issue.md) |
| 443 | 444 | - [](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( | ||
| 64 | 64 | }; |
| 65 | 65 | } |
| 66 | 66 | |
| 67 | /** | |
| 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 | ||
| 67 | 89 | /** What switching to `mode` changes, for the confirm step. */ |
| 68 | 90 | export function followSwitchPreview(mode: ForkFollowMode, upstream: string): string { |
| 69 | 91 | if (mode === "take-updates") |
src/tui/screens/forks.ts +5 −4
| @@ -21,8 +21,8 @@ import { | ||
| 21 | 21 | type ForkRanking, |
| 22 | 22 | type ForkRelation, |
| 23 | 23 | } 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"; | |
| 26 | 26 | import { incomingOf, type Incoming } from "../../actions/follow_incoming.ts"; |
| 27 | 27 | import { convergeFollowed, followedAs, followedOf } from "../../actions/upstream_sync.ts"; |
| 28 | 28 | import { forkOffers } from "../../core/fork_offers.ts"; |
| @@ -112,9 +112,10 @@ export function followingRows( | ||
| 112 | 112 | { |
| 113 | 113 | repo: parent, |
| 114 | 114 | name: `follows ${name}`, |
| 115 | words: mode === undefined ? words : `${words} · ${followModeWords(mode, name).line}`, | |
| 115 | words: mode === undefined ? words : `${words} · ${FOLLOW_CHOICES[mode].label}`, | |
| 116 | 116 | heading: "", |
| 117 | 117 | }, |
| 118 | ...(mode === undefined ? [] : [{ repo: parent, name: ` ${FOLLOW_CHOICES[mode].sentence}`, words: "", heading: "" }]), | |
| 118 | 119 | ...(converge === undefined |
| 119 | 120 | ? [] |
| 120 | 121 | : [ |
| @@ -403,7 +404,7 @@ export function forksScreen(f: Session, ctx: Ctx, repo: Repo): Screen { | ||
| 403 | 404 | const set = await setFollowMode(f.app, f.user, repo, next); |
| 404 | 405 | if (!set.ok) return ctx.toast(FOLLOW_MODE_REFUSALS[set.error].message, "danger"); |
| 405 | 406 | await read(); |
| 406 | ctx.toast(followModeSaid(relation?.parent, set.value), "success"); | |
| 407 | ctx.toast(followChoiceLine(set.value), "success"); | |
| 407 | 408 | }); |
| 408 | 409 | return true; |
| 409 | 410 | } |
src/web/pages/settings.ts +2 −2
| @@ -126,7 +126,7 @@ import { outsideAgentsJs } from "./outside-agents-live.ts"; | ||
| 126 | 126 | import { proposalTokensSection } from "./proposal-tokens.ts"; |
| 127 | 127 | import { secretsSection } from "./secrets.ts"; |
| 128 | 128 | import { checkMemoryAt } from "../../apps/check-memory.ts"; |
| 129 | import { followSourcesCard, followUpstreamCard } from "./upstream-follow.ts"; | |
| 129 | import { followChoiceForm, followSourcesCard, followUpstreamCard } from "./upstream-follow.ts"; | |
| 130 | 130 | import { crewHereSaid, setCrewHere } from "../../actions/crew_switch.ts"; |
| 131 | 131 | import { CREW_OFF_LINE, crewBuildsHere } from "../../core/crew_switch.ts"; |
| 132 | 132 | |
| @@ -339,7 +339,7 @@ export async function settingsPage( | ||
| 339 | 339 | </form> |
| 340 | 340 | </section>`; |
| 341 | 341 | 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)); | |
| 343 | 343 | const sources = followSourcesCard(ctx, repo); |
| 344 | 344 | const wave = html`<section class="settings-block"> |
| 345 | 345 | <h2>Cut a wave</h2> |
src/web/pages/upstream-follow.ts +26 −1
| @@ -32,6 +32,9 @@ import { | ||
| 32 | 32 | sourceStanding, |
| 33 | 33 | } from "../../actions/follow_sources.ts"; |
| 34 | 34 | 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"; | |
| 35 | 38 | import { canAdmin, type Repo } from "../../core/repos.ts"; |
| 36 | 39 | import { getProvenance } from "../../core/provenance.ts"; |
| 37 | 40 | import { getFollow, listChecks } from "../../core/upstream_follow.ts"; |
| @@ -154,12 +157,13 @@ function historyList(ctx: Ctx, repo: Repo): Html | null { | ||
| 154 | 157 | } |
| 155 | 158 | |
| 156 | 159 | /** 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 { | |
| 158 | 161 | if (!canAdmin(ctx.app.db, repo, ctx.auth.user)) return null; |
| 159 | 162 | const follow = getFollow(ctx.app.db, repo.id); |
| 160 | 163 | const base = repoBase(repo); |
| 161 | 164 | return html`<section class="settings-block" id="upstream"> |
| 162 | 165 | <h2>Follow upstream</h2> |
| 166 | ${choice} | |
| 163 | 167 | <form method="post" action="${base}/settings/upstream"> |
| 164 | 168 | <p class="muted"> |
| 165 | 169 | New upstream commits arrive as a pull; never a push to |
| @@ -392,3 +396,24 @@ export async function followSourcesCheck(ctx: Ctx): Promise<Response> { | ||
| 392 | 396 | ); |
| 393 | 397 | return flashTo(ctx, `${repoBase(repo)}/settings#sources`, { message: lines.join(" ") || "No sources to check." }); |
| 394 | 398 | } |
| 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", () => { | ||
| 168 | 168 | test("the owner sees the mode and flips it with m", async () => { |
| 169 | 169 | must(await setFollowMode(app, users["bea"]!, fork, "tell-me")); |
| 170 | 170 | const before = await open("bea", ""); |
| 171 | expect(before).toContain("Proposes updates from"); | |
| 171 | expect(before).toContain("Follow and ask"); | |
| 172 | 172 | expect(before).toContain("follow mode"); |
| 173 | 173 | const after = await open("bea", "m"); |
| 174 | expect(after).toContain("Follows ann/yard automatically"); | |
| 174 | expect(after).toContain("Follow and merge"); | |
| 175 | 175 | expect(forkFollowMode(app.db, fork.id)).toBe("take-updates"); |
| 176 | 176 | }); |
| 177 | 177 |
test/tui-following.test.ts +9
| @@ -12,6 +12,7 @@ import { createIssue, type Issue } from "../src/core/issues.ts"; | ||
| 12 | 12 | import type { Pull } from "../src/core/pulls.ts"; |
| 13 | 13 | import { createApp, type App } from "../src/app.ts"; |
| 14 | 14 | import { createForgeApp } from "../src/tui/forge.ts"; |
| 15 | import { FOLLOW_CHOICES } from "../src/actions/follow_words.ts"; | |
| 15 | 16 | import { followingRows, forksScreen } from "../src/tui/screens/forks.ts"; |
| 16 | 17 | import { headlessTerminal } from "../src/tui/term/terminal.ts"; |
| 17 | 18 | import { settleApp } from "./helpers/tui.ts"; |
| @@ -51,6 +52,14 @@ describe("followingRows", () => { | ||
| 51 | 52 | }); |
| 52 | 53 | |
| 53 | 54 | |
| 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 | ||
| 54 | 63 | test("following nothing shows nothing", () => { |
| 55 | 64 | expect(followingRows(undefined, undefined)).toEqual([]); |
| 56 | 65 | }); |
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.