版本与维护
文档中心怎么写、怎么编版本、怎么弃用、怎么防陈旧。本页为要点摘录,完整规范详见仓库 docs/01-core/文档中心规范-版本与维护.md。
一、三类版本号规则
站点版本、文档版本、API 版本各自独立编号,禁止混用同一个号。
| 版本类型 | 标识位置 | 升级规则 |
|---|---|---|
| 站点版本(文档站整体) | docs-site/ 的 /<major>/ 历史快照;/latest/ 指最新;versions.json 记录受支持版本 |
每个对外大版本保留历史快照,不覆盖旧目录;旧版本页由构建脚本统一注入“旧版本,最新稳定版见…”banner;发布只改 versions.json。 |
| 文档版本(单页内容) | 元数据头 最后核验:YYYY-MM-DD 与 适用版本: |
用元数据表达“这一版对应哪个产品或 API 版本”,不用文件名 v1/v2/final;实质变化才更新 最后核验 并递增 适用版本,只改错别字不更新。 |
| API 版本 | URL 路径主版本(/open/v1) |
兼容增量(新增可选字段、端点、错误码、枚举值)同版本内发布不升版;破坏性变更(删字段、改含义/类型、可选变必填、改枚举语义)升主版本。API / 文档 / 站点三者各记各号,禁止一个号代三件事。 |
二、单一事实源
判定:能被代码、迁移、契约或数据源推导出来的内容,一律生成、不手抄;只有“为什么这样定”“怎么用”这类判断性内容才手写。
必须生成(禁止手写)
- API 参考文档:端点、参数、请求/响应 schema、错误码、状态码,由 OpenAPI 描述生成。
- 字段清单与数据字典:字段名、类型、可空性、默认值,由迁移或 schema 现量导出;会漂移的数字只写在生成文件里,正文用链接引用。
- 路由与权限点清单:由契约表现量导出,不维护第二份。
- OpenAPI 示例:与 schema 同源生成或经校验,示例与 schema 不一致视为缺陷。
允许手写
- 快速开始、认证、错误处理、速率限制、分页等说明性章节。
- 架构决策与取舍、迁移指南、注意事项、边界与“待确认”项。
- 每个端点的“何时使用”与业务背景。
单一权威位置
- 同一条事实只在一个权威位置存在,其它处用链接指向,不复制正文。
- 仓库根
README.md、AGENTS.md、docs/README.md只放入口与指针,不复述具体口径。 - 既需对外又需内部更完整时,用“一份真源 + 生成”,不做两份手写副本。
三、最后核验与 90 天过期
- 每篇活动文档必须具备
最后核验:YYYY-MM-DD与维护人:,缺一即make doc-meta-check报错。 最后核验表示“最后一次逐条核对事实”的日期;只改错别字不算核验。- 默认过期阈值 90 天:
最后核验距今超过 90 天,标记为过期并进入复核队列。 - 过期分两级:
docs/内部文档软告警(构建报告标红);docs-site/对外页面硬阻断(阻断发布),须复核后才放行。 最后核验很新但正文与代码/事故记录冲突时,以冲突信号为准,立即重开复核,不采信日期。
四、变更日志与弃用流程
变更日志(CHANGELOG)
- 维护一份
CHANGELOG.md,遵循 Keep a Changelog:按版本倒序,按新增/变更/弃用/移除/修复/安全分类,日期用YYYY-MM-DD。 - 版本号遵循语义化版本
主.次.修订:不兼容升主版本、兼容新增升次版本、兼容修复升修订。 Unreleased段常驻,未发布改动先记账;发布时把Unreleased移到新版本号下并注明日期。
弃用与下线(Deprecation → Sunset → Retired)
| 阶段 | 含义 | 协议层表达 |
|---|---|---|
| Deprecated | 仍可用,应迁移 | 响应带 Deprecation 头(RFC 9745) |
| Sunset | 将于某日停止 | 响应带 Sunset 头(RFC 8594,HTTP-date 格式) |
| Retired | 已下线 | 端点返回 410 Gone |
- 弃用响应同时带
Link: <迁移文档>; rel="deprecation",把调用方引到迁移页。 - 对外 API 弃用至少提前 180 天公告;安全、合规、防滥用等例外可缩短,但须在公告写明理由与新期限。
- 公告同时发布在四处:
CHANGELOG.md、对应版本文档、状态页/邮件通知、响应头,措辞一致并指向同一迁移文档。
五、CI 门禁清单
每次提交(pre-commit 或 CI)必须跑通下列全部检查,任一失败即阻断合并:
| 检查项 | 命令 / 实现 | 失败条件 |
|---|---|---|
| 相对链接可解析 | make dict-docs-check(tools/dict/check_docs.py) | 相对链接指向不存在的文件 |
| 必备元数据齐全 | make doc-meta-check(tools/dict/check_doc_meta.py) | 缺 状态/创建日期/最后核验/用途/权威实现/原材料与来源/维护人 |
| 对外文档无内部叙事 | make guard(../foundu-kb/tools/text_guard.py) | 出现内部叙事或对既往的追溯表述 |
| 静态站死链 | make docs-site-link-check(对 docs-site/*.html 的 href) | 站内链接目标文件不存在 |
| 文档过期 | make docs-freshness-check(读 最后核验,默认 90 天) | docs-site/ 页面超期 |
| 已废弃页含迁移链接 | 构建脚本校验 | 标 已废弃 但无“迁移至”链接 |
本页为要点摘录;完整规则、写作模板、落地做法与参考来源见仓库 docs/01-core/文档中心规范-版本与维护.md。