文件卫生

文档 社区

技能解读

当前原文的自动摘译,尚未人工审校。

概述

定义项目的文档契约——记录什么、存放在哪里、如何保持最新状态——在文档腐烂之前。输出为.forge/docs-policy.md:每个存储库和子目录的自述文件标准、代码内注释政策(为什么而不是什么)、文档腐烂预防规则(日期、代码链接、生成的文档)、公共与内部文档分割和变更日志规则。与code-review-and-quality(审查强制执行策略)和shipping-and-launch(每个版本更新的变更日志)配对。

何时使用

存储库已超过 3 个月,自第一次提交以来,自述文件尚未被触及 子目录已增长到 5 个以上文件,没有入口点文档 代码内注释主要是重述代码,而不是解释意图 新贡献者需要超过 2 小时才能弄清楚事物的位置 发布的版本没有变更日志条目

何时不使用

新建项目,第一天——自述文件将存在;完整的政策可以等到第 2 周 一次性原型 一份文档中的一个拼写错误修复

常见的合理化理由

想法·现实“代码是自记录的”·代码显示什么,而不是为什么。两个月后,原作者无法重构原因。 “无论如何,文档都会过时,何必麻烦” · 带有代码链接的过时文档比未注明日期的文档腐烂得慢。靠近其代码的注释的半衰期是数年;距离它的代码还很远,几周。 “README 就足够了” · 没有子目录 docs 的 README 为每个新贡献者创造了一次寻宝之旅。

危险信号

自创建存储库以来尚未触及的自述文件 包含 10 多个文件且没有入口点文档的子目录 重述代码的注释:i++ 旁边的 // increment i by 1 没有上次更新日期或提交引用的文档 任何文档中的死链接(损坏的内部链接或 404 外部链接)

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
文档
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

01
第 1 步:定义 README 标准

在`.forge/docs-policy.md`中,每个存储库顶级的自述文件契约:对于每个具有> 5个文件的子目录:一个自述文件回答“这里有什么,为什么在这里,谁拥有它”。

02
第 2 步:设置代码内注释策略

规则:解释为什么,而不是解释什么。坏(什么) · 好(为什么) `// increment i` · `// skip the sentinel row at index 0` `// loop over users` · `// fan-out concurrency capped at 5 to respect upstream rate limit` `// returns null` · `// returns null when the user has been soft-deleted; callers must filter`

03
第 3 步:建立文档腐烂预防措施

每个文档都包含: 顶部的上次更新日期(或“` footer) Code links that resolve at HEAD (use permalinks to `main”,而不是提交哈希) - 如果链接 404,CI 失败 范围声明 - 该文档涵盖的内容,不涵盖的内容 所有者 - 负责保持其最新状态的个人或团队

04
步骤 4:定义公共文档与内部文档的划分

在 `.forge/docs-policy.md` 中: 公共文档 — 面向用户、营销级、版本化(端点文档的交叉引用 `api-design`) 内部文档 — 面向工程、存储库内、允许假设上下文(`CONTRIBUTING.md`、ADR、运行手册) 机密文档 — 凭证、客户数据、财务 — 从未在存储库中 每个文档都有一个横幅,指示其层级。

05
第 5 步:设置变更日志规则

关注 保留变更日志:每个用户可见的变更一个条目,按 `Added`、`Changed`、`Deprecated`、`Removed`、`Fixed`、`Security` 分组。带有 `BREAKING:` 前缀的重大更改。重构不会获得条目,除非它们影响性能、安全性或行为。 *在进行更改的 PR 中更新*,而不是在发布时更新。

06
第 6 步:审核无效链接和陈旧文档

CI 作业每周运行: 检查每个内部链接解析 检查每个外部链接返回 2xx 标记任何上次更新时间 > 180 天的文档,其中链接代码自此以来发生了更改 标记任何早于 90 天的 TODO

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。