Skip to content

[PR] docs: permit root README.<locale>.md community translations (#6000) - #6001

Merged
ranxianglei merged 3 commits into
masterfrom
2026-11-09_root-readme-translation-exception
Nov 9, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-11-09_root-readme-translation-exception

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Carve out a bounded exception to the Documentation Layout rule ("repo root keeps only four entry files") so the root may also hold recognized community-maintained README translations (README.<locale>.md).

Why

Owner approved option 2 for #6000 (2026-11-09): the Japanese README lives at the root as README.ja.md, using GitHub's native README.<locale>.md convention so the top-right language switcher picks it up automatically. Without this carve-out, adding a root README.ja.md would contradict the written rule in five places.

Scope

Docs-only — no code, wire, config, or persistence change. Amended consistently in all five locations that state the rule:

  • AGENTS.md §3 "Documentation Layout" (One hub)
  • docs/index.md, docs/index.zh-CN.md
  • docs/README.md, docs/README.zh-CN.md

The four core entry files stay locked; new non-translation docs still go in docs/.

Split with the translation PR

This PR is the enabling rule change (maintainer-owned spec edit). The actual README.ja.md plus the 「日本語」 language-link entries in README.md / README.zh-CN.md come from @eltociear's separate translation PR, which will close #6000. Disjoint files; sequenced rule-first → translation-second.

Refs #6000

ework-agent and others added 2 commits November 9, 2026 10:49
…n LIVE_FILES

Converged master-red fix (sentinel ci-fixes lane): #5989 merged the
spawning suite without registering it, so the #1248 SPAWN_RE tripwire
kills all 11 core-matrix test shards before any test runs on every PR
head. Hunk is byte-identical to open PR #5990 (which carries the same
registration plus a test-tolerance change to master).
Carve out a bounded exception to the 'repo root keeps only four entry files' Documentation Layout rule: the root may also hold recognized community-maintained README translations (README.<locale>.md), e.g. README.ja.md (owner-approved 2026-11-09, #6000). The four core entry files stay locked; new non-translation docs still go in docs/. Amended consistently across all five locations (AGENTS.md, docs/index{,.zh-CN}.md, docs/README{,.zh-CN}.md).
@ranxianglei ranxianglei added documentation Improvements or additions to documentation p3 scope/docs labels Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-09_root-readme-translation-exception (b3aed0b)

Latest build — install this exact version

npm install -g billion-context@0.0.8747-pr.6001.ea0c184

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
b3aed0b billion-context@0.0.8747-pr.6001.ea0c184 build
1f6f7cc billion-context@0.0.8744-pr.6001.fad0b1d build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr6001.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title docs: permit root README.<locale>.md community translations (#6000) [PR] docs: permit root README.<locale>.md community translations (#6000) Nov 9, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复 — 本线程就是规则口子 PR #6001 本身;检索 open+closed 无并行的同类规则修订 PR,上游需求为 #6000(本 PR 为其前置,Refs 而非 Closes)。

标签: pr(既有) + p3 + scope/docs — 纯文档规范修订,无代码/wire/config 影响。

Live 状态核验(刚查 GitHub API + 本地 master tip):

正在做: 按 CI 协调政策把 origin/ci-fixes merge 进 PR 分支并推送(不自行在分支修 master 级问题),随后在 #4599 留一行结论;全量 review 结论(八问)随后补在本线程。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Review verdict — PR #6001 (head b3aed0b960, base master 1f311dd8d)

Independently re-verified (not taken from the issue text): live PR metadata + full 5-file diff; pre-change rule text at master tip; the #6000 thread confirming owner chose option 2 (root README.ja.md, GitHub-native locale naming); a repo-wide grep proving the "root keeps only four entry files" rule appears in exactly these five places (no sixth location missed); en/zh parity across the four bilingual docs; and confirmation the rule is documentation-level, not a CI gate (tools/check-architecture-docs.mjs checks architecture-doc coverage only, never the root file list).

Behavior change (disclosed): old spec "root keeps only README.md / README.zh-CN.md / AGENTS.md / CHANGELOG.md (+ redirect stubs)" → new spec "four core entry files stay locked + recognized community-maintained README translations (README.<locale>.md)". Intended and owner-approved (#6000, option 2, 2026-11-09) — not drift. The carve-out merely formalizes existing practice: README.zh-CN.md already lives at the root.

Diff cleanliness: 5 files, one-line hunks, every line on-topic. One addition made during review: merged origin/ci-fixes (831b645804, +7 lines in scripts/live-files.mjs) into the branch to clear the inherited LIVE_FILES red — the sentinel commit now rides along in the diff (sanctioned by the #4599 coordination policy; one-line conclusion also posted there).

CI: first run red solely from the inherited master-level gate (test added by #5989 unregistered in LIVE_FILES; all 12 shards died pre-test; reproduced locally at master tip). Rerun on b3aed0b960: fully green — 36 success / 12 skipped / 0 failure across all 48 check runs, including the complete test matrix and all doc guards (architecture-docs, docs-sync, docs-coverage, lifecycle-ledger-guard). PR open, no conflicts.


结构化八问

  1. 是什么问题:文档规则缺口——Documentation Layout 写明「根目录只保留四个入口文件」,但 owner 已拍板日文译本放根目录([Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里? #6000 选项 2),不改规则则新做法与 5 处成文规则直接冲突。
  2. 什么原因导致的:原规则([PR] docs: batch-migrate 14 root-level documents into docs/ (consolidation + master index + redirect placeholders) | docs: 14 个根级文档一次性迁入 docs/(集中 + 总目录 + 重定向占位) #5920)制定时未覆盖 GitHub 原生 README.<locale>.md 社区译本惯例;[Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里? #6000 提出日文 README 后选定根目录方案,旧条文没有这个场景。
  3. 影响范围与严重程度:纯规范文字修订,无代码/wire/config/持久化变化,无用户可感知行为变化;严重度为无——不修只是「成文规则 vs 已批准做法」漂移,会误导后续 agent/reviewer 把根目录译本判成违规。
  4. 怎么修复的:在规则出现的全部 5 处加同一条有界例外——根目录额外允许「受认可的社区 README 译本(README.<locale>.md)」;四个核心入口文件仍锁定、非译文新文档仍一律进 docs/;每处标注批准时间与出处(2026-11-09 / [Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里? #6000)。
  5. 是否有回归问题:无。逐项过——① 独立 grep master tip 确认规则文本恰好只在这 5 处,无漏改的第六处;② 中英四份文档语义一致(en/zh parity);③ 原句「临时重定向占位」「lifecycle §5 记账」语义原样保留;④ 该规则是文档级约束而非 CI 硬门禁,CI 判定路径零变化;⑤ 高危模式逐项排除:无语义漂移、无阈值/时序/输出格式变化、fail-fast 未动。
  6. 是否破坏缓存:不涉及——未触碰任何缓存/重试/游标/去重逻辑。
  7. 是否改了设计方向:无转向。docs/ 单一文档中心 + reference/ 惰性加载的格局不变;本 PR 把既成事实(README.zh-CN.md 本就在根目录)形式化为有界例外,门是收窄不是放宽——只放 README.<locale>.md 译本,其他文件仍禁入根目录。
  8. 是否引入新的配置:无新 env/config/默认值。

判定:可合。 内容审核通过 + CI 全绿(b3aed0b960)。合并权在你(agent 不合并 PR):#6001 。@eltociear 的翻译 PR 可与本 PR 并行开(文件不重叠),建议本 PR 先合、译文随后。

@ranxianglei
ranxianglei merged commit 5c3c268 into master Nov 9, 2026
48 checks passed
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.1114-master.5c3c268 (rolling master tag).

npm install -g billion-context@0.0.1114-master.5c3c268  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation p3 scope/docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里?

1 participant