Skip to content

Commit 59b58a3

Browse files
committed
docs(spec): translate plan.md and add bilingual cross-links to zh_cn/
Final batch (4 of 4) of the zh→en translation pass: Part A — D-class plan translation: - plan.md (force-added past .gitignore; the project-internal plan.md is normally a working-tree artifact, but for the project-spec series it must be tracked alongside 00-06/98/99) Part B — bilingual cross-links into zh_cn/ (20 files): Inserts `> English version: ../<filename>.md` line at the top of each of the 20 Chinese files (idempotent — skip-if-present), matching the existing `> Chinese version: ./zh_cn/<filename>.md` header on every translated English file: - 00-overview-and-glossary.md - 01-requirements-spec.md - 02-architecture-analysis.md - 03-freebsd-15-changes.md - 04-diff-and-port-strategy.md - 05-implementation-plan.md - 06-test-and-acceptance-spec.md - 98-independent-audit-report.md - 99-review-report.md - M1-execution-log.md / M2-execution-log.md / Phase-5b-execution-log.md / M3-execution-log.md / M4-execution-log.md / M5-execution-log.md - M5-test-report.md - M1-research-brief.md / M2-research-brief.md / M3-research-brief.md - plan.md Each zh_cn/ file got exactly +1 line of cross-link insertion; zero edits to any other Chinese content. Project translation pass summary (across batches 1-4): - 20 English files added under `docs/freebsd_13_to_15_upgrade_spec/` (flat, sibling of `zh_cn/` subdir, per DP-target-dir=B) - 20 zh_cn/ files patched with English-version cross-link - 4 git commits (per DP-execution-mode=B): Batch 1: 9 A-class specs (00-06 / 98 / 99) Batch 2: 6 execution logs + 1 test report Batch 3: 3 research briefs Batch 4: 1 plan + 20 zh_cn cross-links - All file paths, function/symbol names, Git commit hashes, decision-point IDs (DP-xxx, R-xxx, T-xxx, TC-01..09), KNOB names, FSTACK markers, file sizes, .o counts and other numeric facts preserved verbatim - All deletions during the pass went through /data/workspace/rm_tmp_file.sh (DP-10 + DP-10-reinforce); zero direct rm invocations - All commit messages in English (per AI memory id 73362122) The English Spec series can now serve international developers and upstream-back-port reviewers alongside the Chinese master.
1 parent cb58dac commit 59b58a3

21 files changed

Lines changed: 219 additions & 0 deletions
Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# F-Stack FreeBSD 13.0 → 15.0 Upgrade Spec Work Plan
2+
3+
> Chinese version: ./zh_cn/plan.md (full prose detail)
4+
>
5+
> Doc series root: `/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/`
6+
> Document version: v0.1 (2026-05-26; §1.3 / §8 status updated 2026-05-28)
7+
> Author: Leader (in main dialogue)
8+
>
9+
> NOTE: This English version is a structural condensation. All section headings, sub-section IDs, deliverable list, agent-team role definitions, phase order, decision-point IDs (DP-1..5), and the 5 external-research items are preserved verbatim from the Chinese master.
10+
11+
---
12+
13+
## 0. Plan Goals
14+
15+
### Deliverables (must end up under `freebsd_13_to_15_upgrade_spec/zh_cn/`)
16+
17+
The 9-doc spec set: `plan.md`, `00-overview-and-glossary.md`, `01-requirements-spec.md`, `02-architecture-analysis.md`, `03-freebsd-15-changes.md`, `04-diff-and-port-strategy.md`, `05-implementation-plan.md`, `06-test-and-acceptance-spec.md`, `99-review-report.md` (later supplemented with `98-independent-audit-report.md` v0.2 on 2026-05-28; and English-version translations under the parent directory).
18+
19+
---
20+
21+
## 1. Workspace State and Boundaries (measured, not guessed)
22+
23+
### 1.1 Three source-tree roots
24+
25+
| Path | Role | Version |
26+
|---|---|---|
27+
| `/data/workspace/freebsd-src-releng-13.0/` | Community FreeBSD 13.0 | RELEASE-p2 |
28+
| `/data/workspace/freebsd-src-releng-15.0/` | Community FreeBSD 15.0 | RELEASE-p9 |
29+
| `/data/workspace/f-stack/` | F-Stack project root | adapted from 13.0 |
30+
31+
### 1.2 13.0 original backup (exists)
32+
33+
`/data/workspace/freebsd-src-releng-13.0/f-stack-lib/` — 25 freebsd + 22 tools subdirectories.
34+
35+
### 1.3 15.0 original backup (**created in Phase 1.4, 2026-05-26**)
36+
37+
`/data/workspace/freebsd-src-releng-15.0/f-stack-lib/` — 25,044 files (`freebsd/` 24,593 + `tools/` 451 + INVENTORY.md). Status status corrected 2026-05-28: this directory exists.
38+
39+
### 1.4 F-Stack already-adapted directories (core upgrade subject)
40+
41+
f-stack/freebsd/ (102 diffs vs 13.0 backup) + f-stack/tools/ (163 diffs).
42+
43+
### 1.5 `f-stack/lib/` scope to include in upgrade (**q2-corrected precise boundary**)
44+
45+
30 `.c` + 14 `.h` = 44 ff_* glue files; precise inventory in 02 §4.
46+
47+
### 1.6 13.0 ↔ 15.0 sys-top-level diff (measured)
48+
49+
(Full table in Chinese master; see 04 §1 for the per-subdir authoritative diff -rq stats added 2026-05-28.)
50+
51+
---
52+
53+
## 2. Agent Team Composition (hybrid mode)
54+
55+
### 2.1 Leader (executed in main dialogue)
56+
57+
| Item | Detail |
58+
|---|---|
59+
| Role | Leader |
60+
| Responsibility | Owns the whole plan; orchestrates 3 subagents; writes the 7 specs and 99 report; handles user q&a; final sign-off |
61+
| Implementation | Main dialogue only (no `Task` spawn) |
62+
63+
### 2.2 Sub-Agent A: Analyzer-13 (code-explorer subagent)
64+
65+
| Item | Detail |
66+
|---|---|
67+
| Role | Analyzer-13 |
68+
| Responsibility | Measure F-Stack adaptation footprint vs the 13.0 baseline; produce the 9-pattern adaptation inventory (H-1..H-9) |
69+
| Implementation | `Task` tool → `code-explorer` subagent (read-only) |
70+
71+
### 2.3 Sub-Agent B: Analyzer-15 (code-explorer + web research)
72+
73+
| Item | Detail |
74+
|---|---|
75+
| Role | Analyzer-15 |
76+
| Responsibility | Measure 13→15 upstream changes in `sys/` + external research (FreeBSD release notes / mailing lists / commit logs / blogs) for 14.0+ ABI/KPI breakage |
77+
| Implementation | `Task` tool → `code-explorer` subagent + `web_search` / `web_fetch` |
78+
79+
### 2.4 Sub-Agent C: Diff-Comparator (code-explorer subagent)
80+
81+
| Item | Detail |
82+
|---|---|
83+
| Role | Diff-Comparator |
84+
| Responsibility | Cross-cut Sub-Agent A + B outputs; produce the `04-diff-and-port-strategy.md` per-file port-task table |
85+
| Implementation | `Task` tool → `code-explorer` subagent (read-only) |
86+
87+
### 2.5 Spec-Writer & Reviewer (Leader concurrent in main dialogue)
88+
89+
| Item | Detail |
90+
|---|---|
91+
| Role | Spec-Writer + Reviewer |
92+
| Responsibility | Spec-Writer drafts 00-06 + 99 + 98 from Sub-Agent A/B/C inputs; Reviewer reviews internally |
93+
| Implementation | Leader in main dialogue executes both |
94+
95+
---
96+
97+
## 3. Execution Steps (chronological)
98+
99+
### Phase 1: Material readiness (Leader in main dialogue)
100+
101+
1.1 Probe workspace
102+
1.2 Create output directory `f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
103+
1.3 Produce `plan.md` (this document)
104+
1.4 **Create 15.0 backup** `/data/workspace/freebsd-src-releng-15.0/f-stack-lib/` (cp -a + INVENTORY.md generation)
105+
106+
### Phase 2: Parallel research (spawn 3 code-explorer subagents)
107+
108+
2.A Sub-Agent A executes Analyzer-13
109+
2.B Sub-Agent B executes Analyzer-15
110+
2.C Sub-Agent C executes Diff-Comparator
111+
112+
### Phase 3: Produce 7 spec docs (Leader+Spec-Writer in main dialogue)
113+
114+
3.1 00-overview-and-glossary.md
115+
3.2 01-requirements-spec.md
116+
3.3 02-architecture-analysis.md
117+
3.4 03-freebsd-15-changes.md
118+
3.5 04-diff-and-port-strategy.md
119+
3.6 05-implementation-plan.md
120+
3.7 06-test-and-acceptance-spec.md
121+
122+
### Phase 4: Reviewer audit (Leader+Reviewer)
123+
124+
Audit the 7 specs along 4 dimensions (consistency / completeness / risk coverage / executability) and produce 99-review-report.md.
125+
126+
### Phase 5: Delivery report
127+
128+
Aggregate the 9 deliverables; explicit "no git / no source change" declaration; pointer to M1 implementation entry.
129+
130+
---
131+
132+
## 4. Risks and Key Decision Points
133+
134+
### 4.1 Identified risks (each elaborated by the spec docs)
135+
136+
(See 03 §7 for the full panorama: R-001 mips / R-002 netlink / R-003 mbuf / R-004 RACK / R-005 pkgbase / R-006 KTLS / R-007 ABI break / R-008 baseline drift / R-009 clang/llvm / R-010 inotify-OOS / R-011 pr_usrreqs / R-012 inpcb SMR / R-013 if_t opaque.)
137+
138+
### 4.2 Key decision points (must be answered explicitly when writing specs in Phase 3)
139+
140+
| DP | Decision | Default tendency |
141+
|---|---|---|
142+
| DP-1 | Whether to delete `f-stack/freebsd/mips/` | **Delete** |
143+
| DP-2 | Whether to pull sys/netlink/ into f-stack/freebsd/ | **Do NOT introduce** |
144+
| DP-3 | Sync strategy: big-bang full sync vs progressive | **Progressive (M1→M5)** |
145+
| DP-4 | Whether ff_*.c is upgraded in lockstep with f-stack/freebsd | **Must be in lockstep** |
146+
| DP-5 | Whether tools/ upgrade is its own milestone | **Independent M5** |
147+
148+
---
149+
150+
## 5. Relationship with Existing F-Stack Docs
151+
152+
(See 00 §6 / 02 §5 for the full mapping. Summary: reuse the 3-layer architecture docs + knowledge-graph; do NOT reuse ld_preload_ring_spec/ workstream.)
153+
154+
---
155+
156+
## 6. External Research Inventory (for Analyzer-15)
157+
158+
5 items (see Chinese master for the full URL inventory): (1) FreeBSD 14.0R/14.1R/14.2R/14.3R/14.4R/15.0R release notes; (2) `pr_usrreqs` merge phabricator review; (3) `inpcb` SMR migration commits + design; (4) `if_t` opaque-ization design; (5) `routing/rib/nexthop` rewrite (D26577).
159+
160+
---
161+
162+
## 7. Things Out of Scope of This Plan
163+
164+
| Item | Note |
165+
|---|---|
166+
| Actual code migration and build verification | Spec phase only; later phases handle |
167+
| Performance benchmarks / stress tests | No binary built |
168+
| Git commit / push | Only working-tree files written |
169+
| English Spec | (Later satisfied by the English translation pass — see 99 §1 final-review entry) |
170+
| 15.0 new-capability ports (netlink port / ML-KEM / inotify / timerfd / kqueuex / membarrier) | "Alignment only, no capability extension" |
171+
| F-Stack `adapter/syscall/` | Independent workstream `docs/ld_preload_ring_spec/` |
172+
173+
---
174+
175+
## 8. Pacing Control (harness-engineering-orchestrator style)
176+
177+
(Plan finished entirely on 2026-05-26; on 2026-05-28 entered audit-revision phase + v0.2 independent audit; on 2026-05-29 M1-M5 implementation closed and project final delivery PASS.)
178+
179+
**Current status (2026-05-29 / project closure)**: Phase 1-5 + v0.2 audit all delivered; M1-M5 implementation all done; G-Acceptance PASS. The plan has been fully executed.

docs/freebsd_13_to_15_upgrade_spec/zh_cn/00-overview-and-glossary.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 00 — 项目概览与术语表
22

3+
> English version: ../00-overview-and-glossary.md
4+
35
> 文档语言:中文(首版)
46
> 系列文档根目录:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
57
> 文档版本:v0.1(2026-05-26)

docs/freebsd_13_to_15_upgrade_spec/zh_cn/01-requirements-spec.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 01 — 升级需求规约(Requirements Spec)
22

3+
> English version: ../01-requirements-spec.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26)
57
> 前序:`00-overview-and-glossary.md`

docs/freebsd_13_to_15_upgrade_spec/zh_cn/02-architecture-analysis.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 02 — F-Stack 当前架构分析(对 FreeBSD 13.0 的改造点全景)
22

3+
> English version: ../02-architecture-analysis.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26)
57
> 数据来源:**Sub-Agent A(Analyzer-13)** 实测调研产物 + leader 后续整理

docs/freebsd_13_to_15_upgrade_spec/zh_cn/03-freebsd-15-changes.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 03 — FreeBSD 13.0 → 14.x → 15.0 关键变更清单
22

3+
> English version: ../03-freebsd-15-changes.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26)
57
> 数据来源:**Sub-Agent B(Analyzer-15)** 调研产物 + 本地双版本源码实测对比

docs/freebsd_13_to_15_upgrade_spec/zh_cn/04-diff-and-port-strategy.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 04 — 13↔15 差异分析与移植策略(Diff & Port Strategy)
22

3+
> English version: ../04-diff-and-port-strategy.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26)
57
> 数据来源:**Sub-Agent A + B + C 三路调研交叉** + 02 / 03 文档汇总

docs/freebsd_13_to_15_upgrade_spec/zh_cn/05-implementation-plan.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 05 — 详细实施计划(Implementation Plan)
22

3+
> English version: ../05-implementation-plan.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26)
57
> 输入:`04-diff-and-port-strategy.md` 的 57 个 T-* 任务清单

docs/freebsd_13_to_15_upgrade_spec/zh_cn/06-test-and-acceptance-spec.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 06 — 测试与验收 Spec(Test & Acceptance Spec)
22

3+
> English version: ../06-test-and-acceptance-spec.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26)
57
> 输入:`01-requirements-spec.md` FR-5 / FR-6 / NFR-1

docs/freebsd_13_to_15_upgrade_spec/zh_cn/98-independent-audit-report.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 98 — Independent Audit Report(独立审计报告)
22

3+
> English version: ../98-independent-audit-report.md
4+
35
> 审计对象:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/` 下 9 份 Spec 文档,以及 Phase 1.4 产物 `/data/workspace/freebsd-src-releng-15.0/f-stack-lib/INVENTORY.md`
46
> 审计时间:2026-05-26 19:45
57
> 审计方式:独立复读文档 + 抽样核验本地源码事实 + 一致性/完整性/可执行性审查

docs/freebsd_13_to_15_upgrade_spec/zh_cn/99-review-report.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 99 — Review Report(一致性 / 完整性 / 风险覆盖度 / 可执行性审查)
22

3+
> English version: ../99-review-report.md
4+
35
> 系列文档:`/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/zh_cn/`
46
> 文档版本:v0.1(2026-05-26);v0.2(2026-05-28,追加独立审计修订记录 §12.1-§12.11);**v0.3(2026-05-28,最终评审通过)**
57
> 审查人:Leader 兼 Reviewer(按 plan.md §2.5 设定)

0 commit comments

Comments
 (0)