3.2 KiB
文档维护规则
查询前先对齐
查询项目状态前，先询问维护者正在进行的工作、跟踪 ticket 和尚未成文的现状。 已有明确授权则在该范围内继续，不重复询问；文档查询授权不自动扩展为现场检查。 2026-09-16 维护者指定 SPIFFE/SPIRE 基本以 homelab-infra #34 的记录为依据； 本轮仅查该 ticket 及其直接引用的 runbook，没有查询现场。其他项目仍需先询问。
稳定设计与使用方法放知识库，动态进度链接到 ticket。知识库只保留注明查阅日期的阶段摘要， 不复制维护第二份实时任务列表。issue open 可能表示后续阶段未完成，不能据此推断基础服务未部署。
状态与证据
分别记录服务生命周期和验证程度，避免一个“完成”掩盖多个状态：
- 生命周期：planned（计划）、experimental（试验）、active（投入使用）、retired（退役）、unknown（未知）。
- 证据：configuration（仅配置）、documented（已有实施记录）、live-verified（现场验证）。
- 存在冲突时明确标记 conflict，并链接待核实项；不按文件日期自动决定谁正确。
设计另用 draft / accepted / implementing / implemented / superseded 表示进度； accepted 不代表部署完成，implemented 必须附实现和验收依据。
last_reviewed 是文档审阅日期；last_verified 是对应运行事实的最近核实日期。
没有核实就写 null。历史验证要说明日期、范围和来源，不能冒充本轮验证。
一项工作的完成条件
- 先按上述规则对齐查询范围，再读取服务文档、相关 ticket 和约束，区分动态工作与事实冲突。
- 实施和必要验证后，同步用途、入口、使用方法、依赖和恢复步骤中的变化。
- 新增或退役服务时更新服务总览；退役文档保留替代入口和原因。
- 代码与文档分属仓库时互相链接 commit/PR；未部署或未同步的部分明确写出。
- 报告分别说明已实施、已验证、仍待完成的内容。
新增服务至少提供一次真实的使用路径。部署步骤不等于使用说明；不能只有 Helm/Compose 命令。 页面上半部分面向使用者，下半部分说明运维和证据。
来源与归属
每份事实只维护一个权威正文位置，其他页面链接到它。链接源码时标明仓库与路径； 历史验收尽量使用 commit permalink，现状入口可指向默认分支。引用未提交工作区时明确标记， 合并后补正式链接。禁止把所有来源路径一律转换成可能不存在的远端链接。
发生冲突时在 verification.md 记录两边来源、影响、核实方法和结果。核实完成后更新权威 文档及引用它的总览，保留决策原因；不要长期维护两种“现状”。
格式与检查
使用普通 Markdown 链接、相对附件路径和文字说明；关键事实直接写入正文。 可选 Obsidian 编辑，个人布局、缓存、插件和同步配置不提交。对外分享前检查敏感内容。 提交前检查相对链接、服务目录覆盖，以及新增内容是否混淆计划和运行事实。