版本与维护

文档中心怎么写、怎么编版本、怎么弃用、怎么防陈旧。本页为要点摘录,完整规范详见仓库 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 / 文档 / 站点三者各记各号,禁止一个号代三件事。

二、单一事实源

判定:能被代码、迁移、契约或数据源推导出来的内容,一律生成、不手抄;只有“为什么这样定”“怎么用”这类判断性内容才手写。

必须生成(禁止手写)

允许手写

单一权威位置

三、最后核验与 90 天过期

四、变更日志与弃用流程

变更日志(CHANGELOG)

弃用与下线(Deprecation → Sunset → Retired)

阶段含义协议层表达
Deprecated仍可用,应迁移响应带 Deprecation 头(RFC 9745)
Sunset将于某日停止响应带 Sunset 头(RFC 8594,HTTP-date 格式)
Retired已下线端点返回 410 Gone

五、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。