内容源版本控制方法

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

使用分支来版本内容是我们推荐的在使用 Antora 时开始使用的方法。分支非常适合于管理相同内容的多个版本。

如果您以前没有使用分支进行版本控制，那么您可能已经将版本存储在文件夹中。如果我们要使用版本文件夹将文档版本全部存储在一个分支中，那么我们必须显式地将一个版本中的所有文件复制到一个新文件夹中以创建一个新版本。这样，我们就不能再依赖 git 来比较、管理和合并同一文档的不同版本。

如果我们使用标记(tags)来存储文档版本，那么一旦创建了标记，我们就无法更新文档，从而有效地阻止文档接收更新。

分支提供适当的平衡。通过从存储库中的现有引用创建一个新分支以持有新版本，存储库仅存储自该分支点以来发生的变化。该分支可以随时接收更新。这就是 Git 最佳的选择。

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

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

与分支类似，标签允许您比较文件的不同版本，并且仓库只存储自上一个标记点以来的更改。标签的缺点是，一旦创建，您无法像分支一样更新它们。因此，如果您发现了错别字或需要添加示例，则无法在标签中编辑内容。它已经被冻结了。您必须删除并重新创建标签，或者创建一个新的标签并指向它，以发布更新。

如果您决定使用标签(tags)来版本控制内容，尽管存在缺点，我们强烈建议为文档使用专用标签（例如，使用 docs/2.0.1 来跟随 release/2.0.1 即，之后创建新标签 ）。这样做可以提供一个更新软件标签之后并且在文档被冻结之前更新文档的机会。否则，您需要确保在发布软件之前所有文档更新都已完成，这很少会发生。（另一种替代方法是频繁发布软件，那么错过软件发布也没什么大不了的）。

使用这种方法，您可以将每个 文档版本 存储在存储库的单个引用(分支或标记)中的文件夹中。然后，在内容源上设置 起始路径键，告诉 Antora 要考虑哪些目录来定位这些文件夹，并设置分支或标记键，以便 Antora 指向目录所在的引用。文件夹本身的名称并不重要。 组件版本描述符 中的 版本键 决定了版本。

我们通常不建议使用这种方法，因为您将失去 git 为您提供的许多优点，如前所述。但是，当许多不同版本的软件组件的文档共存于同一个存储库中时，它可能是有用的。在这种情况下，引用(分支或标记)不能很好地工作，因为单个软件组件的引用将携带来自另一个软件组件的不相关(并且可能过时)文档。这种安排不符合 git 的模式。这可能会让作家感到困惑。

使用文件夹对内容进行版本化可以说是作者使用的最简单的系统。作者可以克隆内容源存储库并立即跨所有版本编辑文件，而无需进行任何分支切换。虽然编写者不能再依赖 git 来比较、管理和合并不同的版本，而且每个版本都是前一个版本的完整副本，但将所有文件放在一起的生产力优势可能会胜出。因此，Antora 支持这种方法。但是，请记住，通过使用 多个工作树，可以实现类似的设置使用。

只有当存储库包含许多不同组件的版本化文档，或者编写者无法使用分支时，才应该考虑使用文件夹对内容进行版本化。

我们把文档看作是发布行中对软件的解释。文档描述了已经发布的软件。因此，即使在软件发布之后(甚至可能在很久之后)，也应该可以更新文档。

文档生命周期并不与软件生命周期绑定，而是遵循软件生命周期。在许多情况下，当软件发布时，文档还没有准备好，并且仍然需要工作(否则，您最终会给文档团队施加巨大的，通常是不合理的压力)。在其他情况下，关于软件发布的新信息需要继续添加到该版本的文档中。

如果软件遵循 语义版本 控制，我们通常建议将文档版本映射到软件的次要版本(例如，1.0、1.1、2.0 等)。当软件是按照一个小的发布线(e.g., v1.0.x, v1.1.x, v2.0.x, etc.)使用分支来管理的，这种映射是可能的。

将文档版本映射到软件的次要版本线是有效的，因为文档通常不与补丁版本绑定。通常，需要更新文档以包含以前遗漏的信息。这些信息可以在下一个补丁发布之前或之后的任何时候添加。

总而言之，我们通常不建议使用标签为软件版本构建文档。文档是对软件的解释，而不是软件本身。在软件的某个版本被冻结和释放后，需要能够更新文档。如果您确实使用标签，我们强烈建议您在文档中使用不同于软件版本的标签。