内容源版本控制方法

使用此方法，您将每个文档版本存储在git存储库的一个分支中，就像您使用分支存储软件项目的版本线一样。然后，在内容源上设置branches键，告诉Antora要使用哪些分支。分支本身的名称并不重要。在组件版本描述符或playbook中的版本键决定了版本。

使用分支对内容进行版本控制是我们推荐使用Antora时的方法。分支非常适合管理同一内容的多个版本。

如果您以前没有使用分支进行版本控制，可能会将版本存储在文件夹中。如果我们使用版本文件夹将所有文档版本存储在单个分支中，那么我们将不得不显式地将版本中的所有文件复制到新文件夹中以创建新版本。这样做后，我们将无法依赖git来比较、管理和合并同一文档的不同版本。

如果我们使用标签存储文档版本，那么一旦创建标签，我们将无法更新文档，有效冻结文档，无法接收更新。

分支提供了正确的平衡。通过从存储库中的现有引用创建一个新分支来保存新版本，存储库仅存储自那个分支点以来发生的更改。并且该分支随时可以接收更新。这正是git最擅长的。

分支与git提供的引用系统很好地映射，并且足够灵活，允许文档自由更新。

使用此方法，您将每个文档版本存储在git存储库的一个标签中，就像您使用标签存储软件发布一样。然后，在内容源上设置tags键，告诉Antora要使用哪些标签。标签提供了许多与分支相同的好处，但也有一些明显的缺点。

与分支一样，标签允许您比较不同版本的文件实例，存储库仅存储自上一个标签点以来发生的更改。标签的缺点是，一旦创建，您无法像使用分支那样更新它们。因此，如果发现拼写错误或需要添加示例，您无法在标签中编辑内容。它被冻结了。您必须删除并重新创建标签，或创建一个新标签并指向它，以便发布更新。

如果决定使用标签对内容进行版本控制，尽管存在缺点，我们强烈建议为文档使用专用标签（例如，docs/2.0.1跟随release/2.0.1）。这样做可以在软件标签创建后以及文档冻结之前（通过标记）更新文档。否则，您必须确保所有文档更新在发布软件之前完成，这很少发生。（另一种选择是频繁发布软件，以便错过软件发布并不是什么大问题）。

使用此方法，您将每个文档版本存储在存储库的单个引用（分支或标签）的文件夹中。然后，在内容源上设置start_paths键，告诉Antora要考虑哪些目录以定位这些文件夹，并设置分支或标签键以指向Antora应该定位这些目录的引用。文件夹本身的名称并不重要。在组件版本描述符中的版本键决定了版本。

我们通常不建议使用此方法，因为您将失去git为您提供的许多优势，如前面所述。但是，当许多不同版本化软件组件的文档共存于同一存储库中时，这种方法可能会有用。在这种情况下，引用（分支或标签）不适用，因为单个软件组件的引用将携带与之不相关（且可能过时）的另一个软件组件的文档。这种安排与git的模型不符合。对作者来说可能会感到困惑。

使用文件夹对内容进行版本控制可能是对作者来说最容易的系统。作者可以克隆内容源存储库，并立即编辑所有版本的文件，而无需进行任何分支切换。尽管作者无法再依赖git来比较、管理和合并不同版本，并且每个版本都从前一个版本的完整副本开始，但拥有所有文件在一起的生产力优势可能会胜出。这就是为什么Antora支持这种方法。但是，请记住，通过使用多个工作树，可以实现类似的设置，使用分支而不会牺牲使用git的修订控制机制的能力。

只有在存储库托管了许多不同组件的版本化文档或您的作者无法使用分支时，才应考虑使用文件夹对内容进行版本控制。

我们将文档视为发布线中软件的解释。文档描述已发布的软件。因此，即使软件已发布（甚至很久之后），也应该可以更新文档。

文档生命周期不受软件生命周期的限制，而是遵循软件生命周期。在许多情况下，当软件发布时文档尚未准备好，仍需要工作（否则，您会对文档团队施加巨大且常常不合理的压力）。在其他情况下，有关软件发布的新信息需要添加到该发布的文档中。

如果软件遵循语义化版本控制，我们通常建议将文档版本映射到软件的次要版本（例如，1.0、1.1、2.0等）。当软件使用遵循次要发布线的分支进行管理时（例如，v1.0.x、v1.1.x、v2.0.x等），这种映射是可能的。

将文档版本映射到软件的次要版本线是可行的，因为通常文档不与补丁发布相关。往往，文档会更新以包含先前遗漏的信息。并且该信息可以在下一个补丁发布之前或之后的任何时间添加。

总之，我们通常建议不要使用标签构建软件发布的文档。文档是软件的解释，而不是软件本身。在软件版本被冻结和发布后，应该可以更新文档。如果您使用标签，我们强烈建议使用与软件发布标签不同的文档标签。