Harmon
d108b33f80
- add documentation governance and cleanup audit documents - update README and docs index to distinguish current vs historical sources - move superseded planning, SBAS, Gamma, and experiment notes into docs/archive - fix remaining archive text garbling in two documents
196 lines
4.9 KiB
Markdown
196 lines
4.9 KiB
Markdown
# 文档治理约定
|
||
|
||
最后更新：2026-04-25
|
||
|
||
## 1. 目标
|
||
|
||
本文件用于定义本仓库的文档治理规则，解决以下问题：
|
||
|
||
- 哪些文档是当前事实来源
|
||
- 哪些文档只是设计过程记录
|
||
- 哪些文档应归档而不是继续留在主导航里
|
||
- 新文档应如何命名、放置和维护
|
||
|
||
本文件是长期有效的治理约定，不是一次性的状态快照。
|
||
|
||
## 2. 事实来源优先级
|
||
|
||
当多个文档描述同一主题且内容不一致时，按以下优先级判断：
|
||
|
||
1. `README.md`
|
||
项目总览、当前架构收口、启动入口。
|
||
|
||
2. `docs/INDEX.md`
|
||
当前有效文档与历史参考文档的总入口。
|
||
|
||
3. 当前状态 / 部署 / 审计类文档
|
||
例如：
|
||
- `CURRENT_STATUS_*`
|
||
- `DEPLOYMENT.md`
|
||
- `*_AUDIT_*`
|
||
|
||
4. 当前执行中的设计 / 规格文档
|
||
例如：
|
||
- `*_DESIGN_*`
|
||
- `*_SPEC_*`
|
||
|
||
5. 计划 / TODO / 实验 / 过程记录
|
||
例如：
|
||
- `*_PLAN_*`
|
||
- `*_TODO_*`
|
||
- `*_EXPERIMENT_*`
|
||
- 临时工作笔记
|
||
|
||
6. `docs/archive/`
|
||
默认只作为历史参考，不作为现行事实来源。
|
||
|
||
## 3. 文档分类
|
||
|
||
### 3.1 长期有效文档
|
||
|
||
适合长期保留在 `docs/` 根目录并放入 `docs/INDEX.md` 的文档：
|
||
|
||
- 总览：项目总览、部署说明、运行约束
|
||
- 状态：当前状态快照、健康检查摘要
|
||
- 审计：数据库、自维护、安全、代码库清理等审计结论
|
||
- 设计：当前仍在执行中的架构设计
|
||
- 规格：仍然有效的接口、产物、目录或包结构规范
|
||
|
||
### 3.2 过程型文档
|
||
|
||
通常不应作为主事实来源，除非 `docs/INDEX.md` 显式列入“当前有效”：
|
||
|
||
- 实施计划
|
||
- TODO 清单
|
||
- 阶段性实验记录
|
||
- 迁移草案
|
||
- 工作过程笔记
|
||
|
||
### 3.3 历史文档
|
||
|
||
满足以下任一条件时，应优先考虑归档到 `docs/archive/`：
|
||
|
||
- 已被更新文档明确取代
|
||
- 描述的是已结束阶段
|
||
- 只保留历史讨论价值，不再指导当前开发或部署
|
||
|
||
## 4. 放置规则
|
||
|
||
### 4.1 仓库根目录
|
||
|
||
根目录只保留高频入口或必须靠近项目根的文件：
|
||
|
||
- `README.md`
|
||
- `.env.example`
|
||
- 启动脚本
|
||
- 极少数确实需要放在根目录的说明文件
|
||
|
||
不应在根目录长期堆积阶段性分析、实验记录、临时修复说明。
|
||
|
||
### 4.2 `docs/`
|
||
|
||
`docs/` 根目录用于放当前仍有导航价值的正式文档。
|
||
|
||
### 4.3 `docs/archive/`
|
||
|
||
`docs/archive/` 用于放：
|
||
|
||
- 已退役设计
|
||
- 已完成修复的过程文档
|
||
- 旧版方案
|
||
- 只保留追溯价值的材料
|
||
|
||
当归档材料数量继续增长时，应维护：
|
||
|
||
- `docs/archive/INDEX.md`
|
||
|
||
用于提供历史文档的结构化入口。
|
||
|
||
## 5. 命名规则
|
||
|
||
建议优先使用以下命名模式：
|
||
|
||
- `CURRENT_STATUS_YYYYMMDD.md`
|
||
当前状态快照
|
||
|
||
- `*_AUDIT_YYYYMMDD.md`
|
||
审计结论
|
||
|
||
- `*_DESIGN_YYYYMMDD.md`
|
||
当前设计
|
||
|
||
- `*_SPEC.md`
|
||
稳定规格
|
||
|
||
- `*_PLAN_YYYYMMDD.md`
|
||
计划文档
|
||
|
||
- `*_TODO_YYYYMMDD.md` 或 `*_TODO.md`
|
||
待办事项
|
||
|
||
- `*_EXPERIMENT_YYYYMMDD.md`
|
||
实验记录
|
||
|
||
规则：
|
||
|
||
- 有日期的文档应表达“状态时间点”或“阶段结论”。
|
||
- 没有日期的文档应尽量只用于长期有效的稳定说明。
|
||
- 如果文档已经明显是阶段性材料，不要再继续使用无日期命名。
|
||
|
||
## 6. 索引维护规则
|
||
|
||
每次新增或退役正式文档时，至少同步更新以下其中之一：
|
||
|
||
- `README.md`
|
||
- `docs/INDEX.md`
|
||
|
||
推荐规则：
|
||
|
||
- 新的正式文档进入 `docs/` 根目录时，必须决定是否加入 `docs/INDEX.md`
|
||
- 文档失效时，必须从“当前有效”区移除
|
||
- 被取代文档如仍需保留，应移动到 `docs/archive/`
|
||
|
||
## 7. 语言与编码规则
|
||
|
||
### 7.1 文档语言
|
||
|
||
当前项目以中文工程文档为主，这没有问题。
|
||
|
||
但为了降低终端编码、跨环境协作和代码审阅成本，建议：
|
||
|
||
- 代码注释与 docstring：默认使用 English
|
||
- 用户界面文案：可继续使用中文
|
||
- 面向本地团队的正式说明文档：可使用中文
|
||
- 如同一主题同时涉及代码约束与面向用户的描述，优先让代码侧说明保持 English
|
||
|
||
### 7.2 编码
|
||
|
||
文本文件建议统一使用：
|
||
|
||
- UTF-8
|
||
- 尽量无 BOM
|
||
|
||
如果 PowerShell 中看到乱码，不应立即判断源码损坏。应先：
|
||
|
||
1. 在编辑器中确认文件实际编码
|
||
2. 再决定是否需要修复源文件
|
||
|
||
## 8. `INIT.md` 的定位
|
||
|
||
`INIT.md` 视为“开发/运维工作笔记”，不是系统架构、部署或运行事实的最高依据。
|
||
|
||
使用原则：
|
||
|
||
- 可以记录当前机器、本轮修复、局部操作注意事项
|
||
- 不应替代 `README.md` 和 `docs/INDEX.md`
|
||
- 如果其中内容已经成为长期规则，应迁移到正式文档中
|
||
|
||
## 9. 当前建议的下一步整理方向
|
||
|
||
后续文档清理建议按以下顺序推进：
|
||
|
||
1. 保持 `README.md` 与 `docs/INDEX.md` 为主导航入口
|
||
2. 将明确失效的阶段性文档继续迁入 `docs/archive/`
|
||
3. 收紧 `docs/` 根目录，只保留当前仍需导航的文档
|
||
4. 逐步减少无明确角色的过程型文件
|