XDocs 发布管理

release management · standard operating procedure

一条主干，
管住所有版本

产品发布、并行维护、海外翻译，都会让同一份文档长出多个版本。XDocs 不做散落的副本——每一次分支复制都记在同一条 lineage 上，可对比、可合并、可追溯。

version id Getting_Started.xml
xi555lineage
2branch
1lang
2version

同一 lineage 下，版本跨分支连接。合并与翻译追踪，都依赖这四段标识。

3 核心工具
Label / Branch / Publish Profile
1 主分支 Trunk
系统文件所在分支
0 冗余副本
分支复制是虚拟注册
4 段版本标识
主干 · 分支 · 语言 · 版本
2 种复制时点
当前版本 / 指定日期
01

发布管理，管的是什么

一句话：让「某份文档」能准确对应「某个产品发布」。产品生命周期因行业而异——有的要同时维护同一产品的多个版本，有的多个子产品共享部分内容。XDocs 不预设一种流程，而是给你三个可组合的工具。

1.0 要发布了，怎么冻结此刻的内容状态，以后再回溯？

1.0 和 2.0 要并行开发，怎么让两组内容互不干扰？

同一份内容要出两个客户版本，怎么控制哪些内容、什么外观？

02

三个工具，各管一件事

不要混用：标签管「时间点」，分支管「空间隔离」，发布配置管「输出形态」。

a — label

标签：冻结一个时间点

一个日期时间戳。打标签即捕获内容在该时刻的完整状态。

  • 可据此查看、导出、分支、发布该时刻的内容版本
  • 因为 XDocs 保留分支上每个文件的所有版本，标签就是可靠锚点
  • 翻译完整、无断链时打标签，价值最高

何时用确定发布点、留可回滚快照

b — branch

分支：隔离一条工作线

一组独立隔离的文件。文件内的链接不会跨分支。

  • 仓库内置主分支 Trunk，系统文件（如 DITAVAL）在此
  • 可从 Trunk 或任意非 Trunk 分支派生新分支
  • 文件进入分支的三种方式：编辑器新建、导入、从其他分支复制

何时用并行维护多个产品版本

c — publish profile

发布配置：控制输出形态

一组 DITAVAL 属性与/或发布参数，在发布时生效。

  • 处理配置（processing）：按条件包含或排除文本、图片
  • 呈现配置（presentation）：章节编号、是否输出目录/索引
  • 可在任意分支上使用，不改变源内容

何时用同一内容出多个变体

03

关键机制：分支复制与 lineage

理解这一节，就理解了 XDocs 分支管理的全部价值——副本不占空间，版本却能跨分支追踪与合并。

Trunk v1 v2 v3
Branch 01 v1 · 分支复制 v2 · 可合并回 Trunk

示例：Getting_Started.xml 在 Trunk 上已有 v1、v2；从 v2 分支复制到 Branch 01，成为该分支的 v1；在分支上修改后形成分支 v2。因共享同一 lineage，分支上的改动可合并回 Trunk。

首次复制 = 注册，不是拷贝

文件首次复制到某分支，即成为该分支的 Version 1。这本质上是文件版本的虚拟副本，避免 CMS 里塞满完全相同的拷贝。

签出签入才产生新版本

文件在某分支上被签出并再次签入时，CMS 才创建新版本。此时新副本只存在于该分支，各分支版本通过文件名与 lineage 相连。

每分支只有一个分支副本

同一文件在每个分支上只能存在一个分支副本。可以把改动合并回去，合并程序会依据 lineage 追加新版本，而不是新建一条线。

复制时点的两种选择：用「As of Date: now」复制当前头版本（如把 Trunk 的 v2 复制到新分支）；或指定历史日期，复制某个旧版本。两种情况下，首次落到目标分支的都是 Version 1。

04

标准作业流程

从项目定义到分支发布，八步走完一次完整的发布分支操作。

操作入口与权限：Branch 选项卡包含 Copy Project Files（按项目整体复制）与 Copy Files（逐个文件复制）。访问 Branch 选项卡，用户必须属于内置用户组 XDocsBranchAdmin，可在 CM Admin 的 Security - Groups 中添加。

Browse 选项卡顶部的四个选择器决定了你看到什么：Project（项目）、Branch（分支）、Language（语言）、As of Date（内容时点）。

  1. 01

    在 CM Admin 定义 Project

    项目定义分支、源语言、目标语言（如适用）以及资源集合的 home folder。它是后续所有复制的边界——Copy Project Files 正是以项目定义为范围。

  2. 02

    在 Trunk 上完成并发布首个版本

    内容在 Trunk 上定稿、发布，形成 v1。此时文件已建立 lineage，后续所有版本都会归属这条主干。

  3. 03

    打一个 Label 锚定发布点

    用日期时间戳标记该次发布。若后续需要回溯、导出、重新分支或重新发布，这个标签就是精确入口。

  4. 04

    检查翻译新鲜度（如涉及多语言）

    分支复制前先运行 Localization 选项卡的 Status 报告，确认有多少译文已过期。这直接决定你该选哪种翻译分支策略。

  5. 05

    核对链接状态

    查看 Branch 报告中的链接状态。若存在 unresolved 链接，打开 View > Outgoing Links 面板定位涉及的具体链接，先修再复制。

  6. 06

    执行分支复制

    选择 Copy Project Files（整体）或 Copy Files（按文件），指定源项目/分支与目标项目/分支，按需选择 As of Date。复制完成后，目标分支上生成该文件的 Version 1。

  7. 07

    在分支上工作与发布

    在分支上编辑内容、执行翻译、发布输出。需要输出变体时，在发布对话框中选用对应的 Publish Profile。

  8. 08

    对比差异，按需合并

    执行 Branch Copy 搜索并查看 Branch Copy Report，比较两个分支上哪些内容相同、已变更、为新增。共享同一 lineage 的变更，可从一个分支合并到另一个分支。

05

翻译内容怎么跟着分支走

Copy Project Files 与 Copy Files 都能同时复制源语言与目标语言内容。但译文与源文不同步时，会出现断链。

要理解的机制

使用 Copy Project Files 时，整个分支的文件成员范围由源语言项目文件集决定（即 CM Admin 项目设置中 DITA map、文件、文件夹所定义的范围）。随后 XDocs 会把目标语言文件限制为与源语言匹配的子集。

因此，如果译文已过期——某个文件在源语言项目文件集中已不存在，但目标语言内容仍在引用它——分支复制时这个目标语言文件不会被找到，链接会被标记为 Unresolved，并在分支上留下占位符（例如图片或 xref 的未解析占位）。

一个具体例子

  1. 英文内容中，topicA.xml 链接到 image1.png
  2. 用 Localization 模块送出翻译，导入法文（fr-FR）版 topicA.xml
  3. 法文 topicA.xml 同样链接到 image1.png
  4. 更新英文内容时，移除了指向 image1.png 的链接
  5. 此时法文版已过期，仍保留着该链接
  6. 把内容从 Trunk 复制到分支（为两个客户各留一份）
  7. Copy Project Files 的状态报告提示：复制后 fr-FR 版 topicA.xml 将出现未解析的图片链接

三种处理策略

策略做法与代价
分支复制之后再做本地化 先把源语言与目标语言内容一起复制到分支，然后在分支上跑一轮新的本地化周期，更新分支上的译文。
分支复制之前先做本地化 先跑本地化周期，让目标语言内容处于最新状态，再进行分支复制——复制过去的内容从一开始就是同步的。
不复制目标语言内容 只分支复制源语言内容，然后在分支上跑本地化周期，用 XDocs Localization 导入全新译文。适合译文长期滞后、历史包袱较重的场景。

三条最佳实践：

① 规划分支复制排期时，把本地化周期一并考虑进去。

② 若打算复制译文，先跑一遍 Localization Status 报告，心里有数再动手。

③ 若希望复制的是「译文完整、无断链」的那个版本，就用标签指定当时的日期时间去复制；复制完成后，再把较新的源语言版本单独复制过去。

06

发布那一刻，用配置控制变体

内容的差异靠分支隔离，输出的差异靠 Publish Profile——两者不重复，各管一层。

处理配置 · Processing Profile

在发布时包含或排除内容（文本与图片）。它与 DITA 内容中的条件化属性值配合工作——内容本身不动，发布时按条件筛选。

呈现配置 · Presentation Profile

改变已发布输出的外观，例如章节是否带编号、是否输出目录或索引。它与发布插件中定义的参数配合工作——在 XDocs 发布对话框中通常显示为「Output type」。

要点：发布配置在发布时选用，可从任意分支发布。当你想在内容和呈现上做出变体时，就创建发布配置并使用它。

07

动手前的检查清单

分支复制不可逆的只有一点——复制过去就是新分支的 v1。所以复制前多花五分钟。

项目定义已确认：分支、源语言、目标语言、home folder 无误
待发布版本已在 Trunk 定稿并发布
已为发布点打上 Label，日期时间准确
已运行 Localization Status 报告，掌握译文过期比例
已核对链接状态，无未解析链接（或已知其影响）
已决定复制时点：当前版本，还是指定历史日期
已确定复制范围：Copy Project Files 还是 Copy Files
已选定翻译策略：先本地化 / 后本地化 / 不复制译文
操作用户已加入 XDocsBranchAdmin 用户组
发布所需的 Publish Profile 已创建并验证