Skip to content

Commit 41cdced

Browse files
SanHsienclaude
andcommitted
feat(fork): 上游 issue 分流水位,PR 與分支寫明不追
一次盤點上游(43 個 open PR、56 個 open issue、71 個分支,main 自 baseline 後 0 個新 commit),結論寫進 docs/fork/UPSTREAM.md 與 DECISIONS.md,之後不必重做: - PR 全部 base 在 dev,合併後隨 release 進 main,由 commit 審查處理。事前逐筆看 等於把同一份改動看兩次,而且看的是還會變的版本。本次 43 個沒有一個動到本 fork 改過的 workflow/文件/測試。 - 分支多是那些 PR 的 head,沒有獨立資訊量,不追。 - issue 只追 platform 標籤:那是唯一會改變「本 fork 要在 Windows 上驗什麼」的類別。 把 50 幾個 issue 每週報一次只會變成固定紅燈。 機制:baseline 新增 reviewed_issue_through(本次 lidge-jun#2379), check-upstream-updates.ts 只報水位之後的新 platform issue,同一個 issue 不會被問 第二次;gh 不可用時報「未檢查」,不會假裝成「沒有待審」,新 issue 與新 commit 一樣 會讓 --strict 失敗。 順帶釐清一個會被重推的現象:ci.yml 的 windows <shard>/4 只有 workflow_dispatch 會跑,所以 Cross-platform CI 的綠燈不含那套 shard(上游 lidge-jun#2152 記錄了它既有的六個 失敗);本 fork 的 Windows 覆蓋來自 keyring windows、npm-global windows-latest 與 fork gate (windows-latest)。 驗證:fork-hygiene 18 pass / 0 fail(新增 4 個案例)、typecheck 乾淨、 dev_check.ps1 全綠、實跑 checker 兩種水位各驗一次。 Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent 7406130 commit 41cdced

5 files changed

Lines changed: 219 additions & 5 deletions

File tree

‎docs/fork/DECISIONS.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,23 @@
11
# 維護決策
22

3+
## 2026-08-22:上游的 PR 與分支不是本 fork 的審查單位,issue 只追 platform
4+
5+
**決定**:不逐筆評估上游的 open PR(43 個,全部 base 在 `dev`)與分支(71 個,多為那些 PR 的
6+
head)。審查單位是 `main` 上的 release commit。issue 只追 `platform` 標籤,並在
7+
`tools/upstream_baseline.json` 記 `reviewed_issue_through` 水位;`check-upstream-updates.ts`
8+
只報水位之後的新 issue,`gh` 不可用時報「未檢查」而不是「沒有待審」。本次分流到 `#2379`。
9+
10+
**理由**:上游 PR 合併後本來就會隨 release 進 `main`,事前逐筆看等於把同一份改動看兩次,
11+
而且看的是還會變動的版本。反過來,把 40 幾個 PR 與 50 幾個 issue 每週報一次,會讓這支檢查
12+
變成固定紅燈——喊狼來了的檢查沒有人看。`platform` 是唯一會改變「本 fork 要在 Windows 上驗
13+
什麼」的類別,值得每週問一次。
14+
15+
**已知結論**(避免下次重推):`ci.yml` 的 `windows <shard>/4` job 只有 `workflow_dispatch`
16+
會跑,所以 Cross-platform CI 的綠燈不包含那套 shard;上游 `#2152` 記錄了那套 shard 既有的
17+
六個失敗。本 fork 的 Windows 覆蓋來自 `keyring windows`、`npm-global windows-latest` 與
18+
`fork gate (windows-latest)`。逐項證據見 [`UPSTREAM.md`](UPSTREAM.md)。
19+
20+
321
## 2026-08-22:文件與語系只留繁中、英文
422

523
**決定**:`README.md` 以繁體中文為主,英文另存 `README.en.md`。GUI 與 docs-site 只保留英文與繁體中文,刪除法文、日文、韓文、俄文、土耳其文、簡體中文。簡體中文瀏覽器對應到繁中。

‎docs/fork/UPSTREAM.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,54 @@ Baseline 代表「已審查」,不代表「全部已合併」。
3636
本 fork 自上游 `main` `6ae83b1f189c353935d4977bb01227484fbdb52b`
3737
(`release: v2.31.0`)建立。此 SHA 設為第一個 `reviewed_through`。
3838
之後的上游 commit 才需要進入審查清冊。
39+
40+
## 上游的 PR、issue、分支:一次評估,之後只看增量
41+
42+
2026-08-22 對 `lidge-jun/opencodex` 做過一次整體盤點(**43 個 open PR、56 個 open issue、
43+
71 個分支**,`main` 自本 fork 的 baseline 之後 0 個新 commit)。結論如下,之後不必重做。
44+
45+
### PR:不逐筆評估
46+
47+
43 個 open PR **全部** base 在 `dev`,那是上游的整合線;合併後會隨 release 進 `main`,
48+
再由 commit 審查處理。逐筆看 PR 等於把同一份改動看兩次,而且看的是還會變的版本。
49+
50+
- 本 fork 的審查單位是 **`main` 上的 release commit**,不是 PR。
51+
- 例外只有一種:某個 PR 動到本 fork 已改過的檔案(workflow guard、fork 文件、
52+
`tests/fork-guard.ts` 涵蓋的測試),那要在合併衝突時處理,不需要事前追。
53+
本次盤點的 43 個 PR 全部落在 `src/`、`gui/`、`docs-site/`,沒有一個動到上述檔案。
54+
55+
### 分支:不追
56+
57+
71 個分支幾乎都是 `codex/*` 功能分支,也就是那些 PR 的 head。fork 只 fetch `main`
58+
(需要時才 fetch `dev`),分支清單沒有獨立的資訊量。
59+
60+
### Issue:只追 `platform` 標籤,並記水位
61+
62+
56 個 open issue 大多是功能請求,會隨 release 進來。真正會改變「本 fork 要在 Windows 上
63+
驗什麼」的是帶 `platform` 標籤的那些,所以只追這一類,其餘不追。
64+
65+
`tools/upstream_baseline.json` 的 `reviewed_issue_through` 記下已分流到哪個編號,
66+
`check-upstream-updates.ts` 只報比它大的 `platform` issue——**同一個 issue 不會被問第二次**。
67+
`gh` 不可用時報「未檢查」,不會假裝成「沒有待審」。
68+
69+
本次分流到 `#2379`。三筆與本 fork 直接相關的結論:
70+
71+
| Issue | 上游狀態 | 對本 fork 的意義 |
72+
|---|---|---|
73+
| [`#2152`](https://github.com/lidge-jun/opencodex/issues/2152) Windows CI 六個既有失敗 | open | **解釋了我們看到的現象**:`ci.yml` 的 `windows <shard>/4` job 條件是 `github.event_name == 'workflow_dispatch'`,平常(含上游)根本不跑,所以本 fork 的 Cross-platform CI 綠燈**不包含**那套 shard。本 fork 的 Windows 覆蓋來自 `keyring windows`、`npm-global windows-latest` 與自己的 `fork gate (windows-latest)`。不要把那個 skipped 當成壞掉。 |
74+
| [`#2292`](https://github.com/lidge-jun/opencodex/issues/2292) `ocx sync --restart-codex` 後 Windows model picker 仍是舊清單 | open | 純 Windows 使用者體驗問題,正是本 fork 的主戰場。等上游修好隨 release 進來;本線不自行 patch。 |
75+
| [`#1525`](https://github.com/lidge-jun/opencodex/issues/1525) Windows 系統 proxy 自動偵測 | open | 功能請求,與本 fork 的 Windows 服務情境相符,但屬產品功能,等上游。 |
76+
77+
其餘 `platform` 以外的 issue(帳號池、catalog、provider 相容性等)一律不追:它們的結果
78+
會以 release commit 的形式送到審查清冊。
79+
80+
## 下一次要做什麼
81+
82+
```powershell
83+
git fetch upstream main
84+
bun tools/check-upstream-updates.ts --strict
85+
```
86+
87+
報告會同時列出「未審 commit」與「水位之後的新 `platform` issue」。處理完後同時推進
88+
`reviewed_through` 與 `reviewed_issue_through`,並把判斷寫進本檔。
89+

‎tests/fork-hygiene.test.ts‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,16 @@ import { tmpdir } from "node:os";
44
import { join, relative } from "node:path";
55
import { fileURLToPath } from "node:url";
66
import { checkDocument, iterDocuments } from "../tools/check-links";
7-
import { loadBaseline, renderMarkdown, UpstreamCheckError } from "../tools/check-upstream-updates";
7+
import {
8+
loadBaseline,
9+
renderIssueSection,
10+
renderMarkdown,
11+
UpstreamCheckError,
12+
upstreamSlug,
13+
} from "../tools/check-upstream-updates";
814

915
const ROOT = fileURLToPath(new URL("../", import.meta.url));
16+
const NEWLINE = String.fromCharCode(10);
1017
const OFFICIAL_REPO_GUARD = "github.repository == 'lidge-jun/opencodex'";
1118
const FORK_OWNED_WORKFLOWS = new Set([
1219
"fork-maintenance.yml",
@@ -171,6 +178,40 @@ describe("upstream checker", () => {
171178
);
172179
});
173180

181+
test("issue triage watermark is recorded", () => {
182+
// Without it every weekly run re-asks about the same upstream issues, and a
183+
// check that asks a question already answered stops being read.
184+
const baseline = loadBaseline();
185+
expect(typeof baseline.reviewed_issue_through).toBe("number");
186+
expect(baseline.reviewed_issue_through!).toBeGreaterThan(0);
187+
});
188+
189+
test("upstreamSlug reads owner/name from the clone URL", () => {
190+
expect(upstreamSlug("https://github.com/lidge-jun/opencodex.git")).toBe("lidge-jun/opencodex");
191+
expect(upstreamSlug("[email protected]:lidge-jun/opencodex")).toBe("lidge-jun/opencodex");
192+
expect(upstreamSlug("https://example.invalid/thing.git")).toBeUndefined();
193+
});
194+
195+
test("an unavailable gh reads as 'not checked', never as 'nothing to review'", () => {
196+
const baseline = loadBaseline();
197+
const unchecked = renderIssueSection(baseline, undefined).join(NEWLINE);
198+
const empty = renderIssueSection(baseline, []).join(NEWLINE);
199+
expect(unchecked).toContain("Not checked");
200+
expect(unchecked).not.toContain("No new");
201+
expect(empty).toContain("No new");
202+
});
203+
204+
test("only issues above the watermark are listed, with the number to bump", () => {
205+
const baseline = loadBaseline();
206+
const section = renderIssueSection(baseline, [
207+
{ number: 9001, title: "[Bug][Windows]: something | with a pipe", labels: ["bug", "platform"] },
208+
]).join(NEWLINE);
209+
expect(section).toContain(`Triaged through \`#${baseline.reviewed_issue_through}\``);
210+
expect(section).toContain("#9001");
211+
expect(section).toContain("with a pipe");
212+
expect(section).toContain("reviewed_issue_through");
213+
});
214+
174215
test("baseline matches the decisions record", async () => {
175216
const decisions = await Bun.file(join(ROOT, "docs/fork/DECISIONS.md")).text();
176217
const upstream = await Bun.file(join(ROOT, "docs/fork/UPSTREAM.md")).text();

‎tools/check-upstream-updates.ts‎

Lines changed: 106 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,18 @@ export const REPO_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
99
export const BASELINE_PATH = resolve(REPO_ROOT, "tools", "upstream_baseline.json");
1010
const UPSTREAM_REF_PREFIX = "refs/upstream-check";
1111
const REQUIRED_FIELDS = ["repo", "branch", "reviewed_through", "reviewed_date"] as const;
12+
/**
13+
* Upstream tickets the fork tracks.
14+
*
15+
* Not all of them: upstream runs ~40 open pull requests and ~55 open issues at
16+
* any moment, all of it arriving here through releases on `main` anyway (see
17+
* `docs/fork/DECISIONS.md`). Reporting that stream weekly would be a check that
18+
* cries wolf, and one that cries wolf gets ignored.
19+
*
20+
* `platform` is the label whose issues change what this fork has to verify on
21+
* Windows, so it is the one worth a standing question.
22+
*/
23+
const TRACKED_ISSUE_LABEL = "platform";
1224
const FULL_SHA_LENGTH = 40;
1325
const UNIT_SEPARATOR = "\u001f";
1426

@@ -19,6 +31,14 @@ export type Baseline = {
1931
branch: string;
2032
reviewed_through: string;
2133
reviewed_date: string;
34+
/** Highest upstream issue number already triaged; only higher ones are reported. */
35+
reviewed_issue_through?: number;
36+
};
37+
38+
export type Ticket = {
39+
number: number;
40+
title: string;
41+
labels: string[];
2242
};
2343

2444
export type Commit = {
@@ -109,10 +129,87 @@ export function collectNewCommits(
109129
return commits;
110130
}
111131

132+
/** Owner/name from the upstream clone URL, for `gh --repo`. */
133+
export function upstreamSlug(repoUrl: string): string | undefined {
134+
const match = /github\.com[:/](?<owner>[^/]+)\/(?<name>[^/]+?)(?:\.git)?$/.exec(repoUrl);
135+
const { owner, name } = match?.groups ?? {};
136+
return owner && name ? `${owner}/${name}` : undefined;
137+
}
138+
139+
/**
140+
* Open upstream issues above the watermark that carry the tracked label.
141+
*
142+
* Returns `undefined` — not an empty list — when `gh` cannot answer, so a
143+
* missing CLI or an unauthenticated shell reads as "not checked" in the report
144+
* instead of the much worse "nothing to review".
145+
*/
146+
export function collectNewIssues(baseline: Baseline): Ticket[] | undefined {
147+
const slug = upstreamSlug(baseline.repo);
148+
if (!slug) return undefined;
149+
const result = Bun.spawnSync(
150+
["gh", "issue", "list", "--repo", slug, "--state", "open", "--label", TRACKED_ISSUE_LABEL,
151+
"--limit", "100", "--json", "number,title,labels"],
152+
{ stdout: "pipe", stderr: "pipe" },
153+
);
154+
if (result.exitCode !== 0) return undefined;
155+
let parsed: { number: number; title: string; labels?: { name: string }[] }[];
156+
try {
157+
parsed = JSON.parse(new TextDecoder().decode(result.stdout));
158+
} catch {
159+
return undefined;
160+
}
161+
const watermark = Number(baseline.reviewed_issue_through ?? 0);
162+
return parsed
163+
.filter((item) => item.number > watermark)
164+
.sort((left, right) => left.number - right.number)
165+
.map((item) => ({
166+
number: item.number,
167+
title: item.title,
168+
labels: (item.labels ?? []).map((label) => label.name),
169+
}));
170+
}
171+
172+
/** The issue section: what still needs a human's judgement, or why it was not asked. */
173+
export function renderIssueSection(baseline: Baseline, issues: Ticket[] | undefined): string[] {
174+
const watermark = baseline.reviewed_issue_through ?? 0;
175+
const lines = ["## Upstream platform issues", "", `Triaged through \`#${watermark}\`.`, ""];
176+
if (issues === undefined) {
177+
lines.push(
178+
"Not checked: `gh` was unavailable or unauthenticated. This is reported rather than",
179+
"treated as \"nothing to review\" — the difference matters.",
180+
"",
181+
);
182+
return lines;
183+
}
184+
if (issues.length === 0) {
185+
lines.push("No new `platform` issues since that number.", "");
186+
return lines;
187+
}
188+
lines.push(
189+
`${issues.length} new \`platform\` issue(s) to triage.`,
190+
"",
191+
"| Issue | Labels | Title |",
192+
"| --- | --- | --- |",
193+
);
194+
for (const issue of issues) {
195+
lines.push(
196+
`| #${issue.number} | ${issue.labels.join(", ")} | ${issue.title.replaceAll("|", "\|")} |`,
197+
);
198+
}
199+
lines.push(
200+
"",
201+
"Record the verdict in `docs/fork/UPSTREAM.md`, then raise `reviewed_issue_through`",
202+
"so the same issue is never re-triaged.",
203+
"",
204+
);
205+
return lines;
206+
}
207+
112208
export function renderMarkdown(
113209
baseline: Baseline,
114210
commits: Commit[],
115211
error?: string,
212+
issues?: Ticket[] | undefined,
116213
): string {
117214
const lines = [
118215
"# Upstream review report",
@@ -128,6 +225,7 @@ export function renderMarkdown(
128225
}
129226
if (commits.length === 0) {
130227
lines.push("## Result", "", "No new upstream commits. Nothing to review.", "");
228+
lines.push(...renderIssueSection(baseline, issues));
131229
return `${lines.join("\n")}\n`;
132230
}
133231
lines.push(
@@ -191,26 +289,28 @@ export function main(args = Bun.argv.slice(2)): number {
191289
reviewed_date: "unknown",
192290
};
193291
let commits: Commit[] = [];
292+
let issues: Ticket[] | undefined;
194293
let error: string | undefined;
195294

196295
try {
197296
baseline = loadBaseline();
198297
const ref = fetchUpstream(baseline, options.repoDir);
199298
commits = collectNewCommits(baseline, options.repoDir, ref);
299+
issues = collectNewIssues(baseline);
200300
} catch (caught) {
201301
if (!(caught instanceof UpstreamCheckError)) throw caught;
202302
error = caught.message;
203303
}
204304

205-
const report = renderMarkdown(baseline, commits, error);
305+
const report = renderMarkdown(baseline, commits, error, issues);
206306
writeFileSync(options.output, report, "utf8");
207307
process.stdout.write(report);
208308

209309
if (options.githubOutput && process.env.GITHUB_OUTPUT) {
210310
appendFileSync(
211311
process.env.GITHUB_OUTPUT,
212312
[
213-
`needs_attention=${commits.length > 0 || Boolean(error) ? "true" : "false"}`,
313+
`needs_attention=${commits.length > 0 || (issues?.length ?? 0) > 0 || Boolean(error) ? "true" : "false"}`,
214314
`check_failed=${error ? "true" : "false"}`,
215315
`report_path=${options.output}`,
216316
"",
@@ -219,7 +319,10 @@ export function main(args = Bun.argv.slice(2)): number {
219319
}
220320

221321
if (error) return 2;
222-
if (options.strict && commits.length > 0) return 1;
322+
// A new `platform` issue upstream changes what this fork has to verify on
323+
// Windows, so it fails the weekly check the same way a new commit does.
324+
// Clearing it means triaging the issue and raising the watermark, not muting.
325+
if (options.strict && (commits.length > 0 || (issues?.length ?? 0) > 0)) return 1;
223326
return 0;
224327
}
225328

‎tools/upstream_baseline.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@
22
"repo": "https://github.com/lidge-jun/opencodex.git",
33
"branch": "main",
44
"reviewed_through": "6ae83b1f189c353935d4977bb01227484fbdb52b",
5-
"reviewed_date": "2026-08-22"
5+
"reviewed_date": "2026-08-22",
6+
"reviewed_issue_through": 2379
67
}

0 commit comments

Comments
 (0)