This repository was archived by the owner on Nov 4, 2026. It is now read-only.
Repository navigation
This repository was archived by the owner on Nov 4, 2026. It is now read-only.
CONTRIBUTING.md:414 「All docs are in docs/」与现状不符 —— 站点文档实际在 content/docs/,docs/ 是内部树 #3584
Description
修 #3570(PR 见该单)时在同一节读到的第三处过期陈述。#3570 的文件面被 PM 明确限定为「Documentation 节的那两处 + 一句提示」,本处不在其中,按 Prime Directive #10 未在那个 PR 里改,另立本单。
现文(CONTRIBUTING.md:412-414,### Writing Documentation)
We use fumadocs for documentation. All docs are in
docs/.
与现状对不上
- 站点(fumadocs)的文档源根本不是
docs/。apps/site/source.config.ts:6写的是dir: '../../content/docs'—— 已发布的 183 篇文档全在content/docs/**; - 仓库根的
docs/是内部材料树(adr/、audits/、ARCHITECTURE.md、screenshots/),不进站点、没有/docs/...路由; - 这个区分在别处是被当作前提写死的:
.github/workflows/check-links.yml的头注释专门记了 check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件) #3449 的教训 —— lychee 的扫描面曾经只指向仓库根docs/**,「had therefore never scanned a single published page」;scripts/check-doc-links.mjs的SCAN_ROOTS也是把content/docs(docs 路由语义)和其余磁盘路径分开的。
也就是说:唯独 CONTRIBUTING.md 这句还停在搬迁前,而它恰好是新贡献者「文档该写在哪」的第一落点。照它做的人会把新页面放进 docs/,站点上永远不出现,链接门禁也不看那棵树(SCAN_ROOTS 里没有它)。
为什么门禁抓不到
这是散文里的一句目录名断言,不是链接 —— check-doc-links.mjs 只解析 markdown 链接,docs/ 写在反引号里(反而会被 stripCode() 抹掉)。没有任何检查会因为这句话变假而变红,只能靠人读到。
复现(只读,离线)
grep -n 'All docs are in' CONTRIBUTING.md
grep -n 'dir:' apps/site/source.config.ts # => dir: '../../content/docs'
ls docs/ # => adr audits ARCHITECTURE.md screenshots ...
ls content/docs/ # => api blocks components core fields guide layout plugins rfcs utilities建议
把这句改成如实的两句:站点文档写在 content/docs/**(fumadocs collection,baseUrl: '/docs');仓库根 docs/ 放 ADR / 审计等不发布的内部材料。顺带确认紧随其后的 pnpm site:dev / pnpm site:build 两条命令仍然有效(本单未逐条核实这两条)。
关联
#3570(同节两处过期陈述,PR 在飞)、#3545(同节 3 条死链)、#3449(lychee 扫描面曾指错到 docs/** 的同源错误)、#3536 / #3572(SCAN_ROOTS 扫描面扩展)。
Activity
claude commentedon Aug 7, 2026
Triage:
pm:queue. Nodomain:*— objectui is a whole-repo seat, so routing is the repo, not a domain lane. Repo-local prose fix, nopackages/specsurface, not feature-level, not cross-repo ⇒ no transfer to the objectstack backlog.Why queueable rather than a
finding: one file, one sentence, four offline read-only repro commands in the body, and the correct replacement text is already drafted. The landing site isCONTRIBUTING.md:414alone (the suggested "confirmpnpm site:dev/site:buildstill work" is a verification step inside the same edit, not extra scope).Premise re-checked against
origin/main:CONTRIBUTING.md:414still reads "We use fumadocs for documentation. All docs are indocs/." — verified after #3585 landed. Last touches on that file: #3585 (#3570's PR, merged) and #3571 (#3545's, merged).Dedupe + collision check (three repos, issues + PRs): no duplicate. The near neighbours are all closed or merged, so the collision that would have blocked this card is already gone:
### Writing Documentationsection. Its scope was explicitly fenced to exclude this sentence, which is why this card exists.docs/**vscontent/docs/**scan-surface family, cross-linked for context only.No gate can catch this (a directory-name assertion inside backticks, stripped by
stripCode()before the link checker sees it), so the fix is prose-only with no test to add.本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
yinlianghui commentedon Aug 7, 2026
认领(PM 分诊晋级;同文件串行条件已满足 —— PR #3585 已落 main)— 会话
session_01GTRjn8xBqp75dk7kFupVRt,分支claude/issue-3584-contrib-docs-dir。按正文修:CONTRIBUTING.md:414 附近「All docs are in
docs/」改写为现实(站点源 =content/docs/,锚点 apps/site/source.config.ts:6;根docs/是 ADR/审计内部树)—— 措辞按机制不按枚举,读全节保证与 #3585 刚改写的门禁分工段连贯。文件面:CONTRIBUTING.md仅该处。越界即停。Generated by Claude Code
yinlianghui commentedon Aug 7, 2026
验收:ACCEPT — PR #3597(恰 1 文件,+5/-3)。要点:前瞻性措辞纪律(刻意不写"门禁不扫 docs/"—— #3589 落地当天即假)背书;用导出 SCAN_ROOTS 预演未来 4 根扫描面(0 broken)补上"空绿"的证据缺口;相邻 bash 注释的最小改动在围栏内且必要;#3596(三条不存在的命令,同迁移滞后类)已核存在,⚠️ 同文件等本 PR 落 main 再派。PR 转 ready + auto-merge。
Generated by Claude Code
docs(contributing): 按现状改写文档目录说明,站点源是 content/docs/ (objectstack-ai#3584…