版本化工作流 : docmd docs

指南
工作流与团队
发布工作流

问题

将软件发版与对应的文档更新保持同步，是一项协调难题。文档更新常常在新代码部署前就先上了线（让现有用户困惑），又或者延迟数日（让早期采用者失望）。

为什么重要

软件行为与文档之间一旦脱节，就会给开发者带来摩擦。要让文档真正发挥作用，它必须严格对应用户所运行的软件版本。为每个版本提供准确的上下文，可以保证顺畅的上手与排错体验。

方法

使用 docmd 的版本化引擎把进行中的开发文档隔离开。团队可以在一个单独的目录（例如 docs-next/）中异步起草新功能的内容，仅当官方软件正式发版时，才将其晋升 (promote) 为"Stable"。

实现

1. 组织好目录结构

将稳定版文档保留在主 docs/ 目录下，并为即将发布的版本单独建一个目录。

project-root/
├── docs/       # 当前稳定版 (v1.x)
├── docs-v2/    # 即将发布 (v2.0)
└── docmd.config.json

2. 配置版本

在配置中注册两个版本。将即将发布的版本标注为 “Beta” 或 “Next”，以便通过版本切换器向用户传达其状态。

docmd.config.json

{
  "versions": {
    "current": "v1.0",
    "all": [
      { "id": "v1.0", "dir": "docs", "label": "v1.x (Stable)" },
      { "id": "v2.0", "dir": "docs-v2", "label": "v2.0 (Beta)" }
    ]
  }
}

3. 晋升 (Promotion) 流程

当您准备好正式发布新版本时：

更新配置：将 docmd.config.json 中 current 的版本号改为 v2.0。
更新标签：移除 all 数组中相应条目 label 上的 “(Beta)” 字样。
归档旧文档：在 all 数组中保留 v1.0 条目，以便使用旧版本的用户仍可访问相关文档。

取舍

维护开销

维护多版本文档需要纪律。若在稳定版中修复了一个关键的拼写错误或安全提示，请务必同步应用到即将发布版本的目录中，避免回归。

SEO 与搜索

多版本偶尔会让搜索结果指向更老的文档。请使用 seo 插件和规范的 canonical 标签，确保"当前 (Current)"版本始终被搜索引擎优先收录。详情可参阅处理 Breaking Changes。

问题