版本控制文档

GitHub Docs 使用 YAML 前置内容和 Liquid 运算符来支持使用单一来源方法的多个 GitHub 版本。

在本文中

在 GitHub Docs 上，我们提供文档版本，反映了 GitHub 主要产品产品在 UI 和功能上的差异。贡献者可以使用版本控制语法将内容限定到特定产品产品。

版本控制语法允许读者手动选择适用于他们正在使用的产品的文档版本。GitHub Docs 的 URL 还可以包括版本控制信息，这允许来自 GitHub.com 和 GitHub Enterprise Server 的链接将读者直接发送到他们正在使用的产品的文档。

如何以及在何处进行版本控制

GitHub Docs 中内容的版本控制为单一来源，以避免重复并保持散文 DRY。对于文章，您可以使用 YAML 元数据对单个 Markdown 文件应用版本控制，然后在文件散文内使用条件语句指示网站根据读者选择的版本显示哪些文本。单一来源与创建反映内容每个版本的单独文件形成对比。

GitHub Docs 有两种类型的版本控制语法。

  • YAML：最常用于 content/ 中 Markdown 文件内的 YAML 前置内容中，但也用于 data/ 中许多类型的 YAML 文件中。指示整个内容部分的版本控制。

    versions:
  PRODUCT: 'VERSIONS'
  PRODUCT: 'VERSIONS'
  ...

    以下示例显示了针对 GitHub.com 和所有版本 GitHub Enterprise Server 进行版本控制的内容。

    versions:
  fpt: *
  ghes: *

  • Liquid：用于 content/ 和 data/reusables/ 中的 Markdown 文件、data/variables/ 中 YAML 文件内的变量字符串或 data/glossaries/external.yml 中的字符串。指示当读者选择由 YAML 前置内容定义了多个版本的版本时应显示哪些文本。

    • 基于产品的版本控制

      {% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}

    • 基于功能的版本控制

      {% ifversion FEATURE-NAME %} ... {% endif %}

关于 GitHub 的不同版本

我们为 GitHub.com 计划（包括 GitHub Enterprise Cloud 和 GitHub Enterprise Server）的用户提供版本化文档。如果网站上存在页面的多个版本，读者可以选择页面顶部的版本选择器中的版本。

GitHub.com

GitHub.com 的文档有两个可能的版本

免费、专业或团队计划

对于 GitHub.com 上的免费、专业或团队计划，请使用 free-pro-team@latest。简称是 fpt。

GitHub Enterprise Cloud

对于 GitHub Enterprise Cloud，请使用 enterprise-cloud@latest。简称是 ghec。

GitHub Enterprise Server

GitHub Enterprise Server 文档有多个版本，可分为两类：受支持版本（我们一次最多支持四个版本）的文档和已弃用版本（我们不会在文档网站上链接到这些版本，但我们永久支持这些文档的“冻结”快照，因此如果您知道 URL，仍然可以访问它们）。有关列表，请参阅 lib/enterprise-server-releases.js。

这些版本被命名为 enterprise-server@<release>。简称是 ghes。在 Liquid 条件中，我们可以指定范围，例如 ghes > 3.0。有关详细信息，请参阅“使用 Liquid 条件运算符进行版本控制”。

YAML 前导数据中的版本控制

您可以在文件的 YAML 前导数据中使用 versions 属性来定义文章将显示在哪些产品中。索引文件需要一个 versions 属性，但它们将根据其子项的版本自动进行版本控制。

例如，以下 YAML 前导数据将为 GitHub Enterprise Server 2.20 及更高版本以及 Free、Pro 或 Team 版本的文章进行版本控制。

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=2.20'

以下示例将为所有受支持的 GitHub Enterprise Server 版本的文章进行版本控制

title: Downloading your license
versions:
  ghes: '*'

您还可以为一系列版本对页面进行版本控制。以下示例将仅为 GitHub.com 和 GitHub Enterprise Server 版本 3.1 和 3.2 对页面进行版本控制

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>=3.1 <3.3'

使用 Liquid 条件运算符进行版本控制

我们使用 Liquid 模板语言（具体来说是 此 Node.js 端口）和一个自定义 {% ifversion ... %} 标记来创建文档版本。

如果您在页面的 YAML 前导数据中的 versions 键中定义了多个产品，则可以在 Markdown 中使用条件运算符 ifversion/else（或 ifversion/elsif/else）来控制网站如何为特定产品在页面上呈现内容。例如，GitHub.com 上的功能可能比 GitHub Enterprise Server 上的功能更多，因此您可以通过 versions 前导数据适当地对内容进行版本控制，并使用 Liquid 条件来描述 GitHub.com 的其他选项。

备注

  • 针对基于产品的版本使用 ifversion 和 基于功能的版本。
  • 不要使用 if 或 unless。
  • 确保使用 elsif 而不是 else if。Liquid 无法识别 else if，并且不会呈现 else if 块内的内容。

比较运算符

对于没有编号版本的版本（如 fpt 和 ghec），你有两个选项

  • {% ifversion ghec %}
  • {% ifversion not ghec %}

对于有编号版本的版本（目前只有 ghes），你可以对所有版本中都可用或任何版本中都不可用的内容执行相同操作

  • {% ifversion ghes %}
  • {% ifversion not ghes %}

如果你需要表示仅在特定版本中可用（或不可用）的内容，则可以使用以下运算符

运算符含义示例
=等于{% ifversion ghes = 3.0 %}
>大于{% ifversion ghes > 3.0 %}
<小于{% ifversion ghes < 3.0 %}
!=不等于{% ifversion ghes != 3.0 %}（不要在范围内使用 not）

Liquid 运算符 ==、>= 和 <= 在 GitHub 文档中不受支持。

逻辑运算符

当所有操作数都必须为真时，条件才为真，使用运算符 and

{% ifversion ghes > 2.21 and ghes < 3.1 %}

当至少一个操作数必须为真时，条件才为真，使用运算符 or

{% ifversion fpt or ghes > 2.21 %}

不要使用运算符 && 或 ||。Liquid 无法识别它们，并且内容不会在预期版本中呈现。

空格控制

在列表中使用 Liquid 条件时，可以使用 空格控制 字符来防止添加换行符和其他空格，这些空格会破坏列表呈现。

你可以在左侧、右侧或两侧添加连字符 (-) 以指示该侧不应有换行符或其他空格。

{%- ifversion fpt %}

例如，要对某个步骤进行单步版本控制，不要像这样从上一步结束处开始为该步骤添加液体版本控制

1. This step is for all versions{% ifversion ghes %}
1. This step is for GHES only{% endif %}
1. This step is for all versions

你可以将液体版本控制包含在它自己的行中，并使用空白控制来删除液体标签左侧的新行。这使得阅读源代码变得更加容易，而不会破坏列表的呈现

1. This step is for all versions
{%- ifversion ghes %}
1. This step is for GHES only
{%- endif %}
1. This row is for all versions

关于基于功能的版本控制

当你记录任何新的更改或功能时，请使用基于功能的版本控制。

少数功能和更改只会应用于一个产品。大多数功能都会进入 GitHub.com，并最终到达所有产品。通常，更改会从 GitHub.com（包括 GitHub Enterprise Cloud）流向 GitHub Enterprise Server。

基于功能的版本控制提供了名为“功能标志”的命名，简化了文档的维护和版本控制。你可以使用一个功能名称（或“标志”）来对内容中的散文进行分组和版本控制。当一个功能进入其他产品时，你只需要对 data/features/ 中的文件中的 YAML 版本控制进行更改。

管理功能

每个功能都通过 data/features/ 中的单独 YAML 文件进行管理。

注意：不要删除 data/features/placeholder.yml，因为它被测试使用。

要创建新功能，请首先在此目录中创建包含你要使用的功能名称的新 YAML 文件。对于名为 meow 的功能，它将是 data/features/meow.yml。

向 YAML 文件中添加一个 versions 块，其中包含该功能可用的版本的简称。例如

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>3.1'

格式和允许的值与 frontmatter 版本属性相同。有关更多信息，请参阅 github/docs 存储库自述文件中的“版本”。

Liquid 条件

现在你可以在内容文件中使用 {% ifversion meow %} ... {% endif %}！

Frontmatter

你还可以使用内容文件中的 frontmatter 中的功能

versions:
  feature: 'meow'

你只能在 versions 下使用一个 feature 条目，并且 feature 的值只能包含一个功能名称。

您可以在 frontmatter 中结合基于功能的版本控制和标准版本控制。执行此操作时，文章将包含在基于功能的版本控制文件中和 Markdown 文件中直接指定的所有版本的超集中。例如，您可能有一个目前仅在 GHEC 中可用的功能，并且这在基于功能的版本控制中指定。但是，您希望此功能的“关于”文章也出现在 FPT 文档中。在这种情况下，您可以在 front matter 中将 fpt 和 feature 添加到 versions 块

versions:
  fpt: '*'
  feature: 'some-new-feature'

最佳实践

版本化内容影响读者，但也影响任何对内容做出贡献或审查内容的人。以下是一些提示，旨在改善版本控制语法的编写、阅读和审查体验。这些做法都不是强制性的，您会发现边缘和极端情况，但它们旨在作为有用的启发式方法，帮助您思考版本控制。

避免不必要的版本控制

对于读者而言，获得一般性理解比阅读准确反映特定产品或计划之间差异的详细信息更为重要。在概念性或程序性内容中，请尝试以不需要版本控制语法的通用方式描述功能或 UI 部分。除了更容易维护之外，这还能加强对参考多个产品文档的读者的理解。

  • 请自问，“我是否可以用适用于所有产品且无需任何版本控制的方式来编写此内容？”
  • 请尽量避免对屏幕截图进行版本控制，因为创建它们需要花费精力。UI 文本之间的细微差异可能不会影响理解。如果存在特定于产品文本或 UI 元素，但屏幕截图仍然提供有用的上下文，请自问对屏幕截图进行版本控制是否会对理解产生有意义的影响。
  • 如果您可以在不针对特定产品进行版本控制的情况下解释概念或指导读者完成程序，请不要对散文进行版本控制。

修改现有内容文件时，尽早且经常地审查现有版本控制

保持对现有版本控制的认知将有助于确保您编写相关的版本控制声明，并且可以帮助您记住准确地对新内容进行版本控制。

  • 开始编辑后，请立即审查 front matter 中整个页面的版本控制。
  • 请审查您正在编辑的内容周围的版本控制。
  • 请审查您正在进行的更改的呈现版本，并作为自审的一部分切换到页面可用的每个版本。

尽可能避免重复

在句子或段落中使用版本控制语法来区分两个不同计划或产品的散文。贡献者可以使用版本控制声明编辑一个段落，而无需考虑更大的版本化文本块，并在两个地方修改类似但版本不同的散文。审阅者可以一次提出更改建议，而无需在多个地方留下相同的建议。但是，如果行为差异很大，或者句子或段落中的版本控制变得复杂或难以解析，请考虑重复自己以使散文更容易维护。

  • 请在段落中内联使用版本控制语法，以避免重复句子或整个段落。

    你可以执行 {% ifversion fpt %}某些操作{% elsif ghec %}其他操作{% endif %}。

  • 请运用你的判断力：对于在句子或段落中不使用大量版本控制语法就难以编写或阅读的散文，请考虑为每个相关产品在版本块中重复整个段落。

    {% ifversion fpt %}

    如果你使用免费、专业或团队计划，则可以执行某些操作。以下是有关你可以使用免费、专业或团队计划执行的操作的更多信息...

    {% elsif ghec %}

    如果你使用 GitHub Enterprise Cloud，则可以执行其他操作。以下是有关你可以使用 GitHub Enterprise Cloud 执行的操作的更多信息...

    {% endif %}

要明确，不要含蓄

如果你确切知道内容描述了哪些产品，则明确地针对这些产品进行版本控制。诸如 not 和 else 之类的语法尤其可能不精确。not 和 else 的最终结果取决于每篇文章的正文，因此贡献者必须进行更多调查才能理解使用此版本控制的散文。这会产生错误的可能性。在可重用项中，隐式版本控制的复杂性会增加，其中引用可重用项的文章可能具有不同的版本控制，因此对 not 或 else 的评估也不同。当 GitHub 推出新产品时，我们偶尔也会向 GitHub 文档中引入新版本，这会改变我们在现有文章中添加新版本时 not 和 else 的最终结果。

  • 请记住，GitHub 提供四种产品，并且请记住，GitHub 文档在任何给定时间都可以显示八个总版本的文档。
  • 当你开始编辑时，请在正文中查看整篇文章的版本控制，因为这可以帮助你了解 not 和 else 将如何在 Liquid 语句中表现，或者在你启用正文中的新版本时发生变化。

在你完成内容设计和创建时验证和传达版本控制

有时更改不会包含在最初预期的版本中。对于版本和改进，你可以在整个内容设计和创建过程中确认版本控制，从而为审阅者节省时间并确保内容更加准确。

  • 请在内容设计中考虑版本控制，并在你请求利益相关者审阅内容创建时仔细检查版本控制。
  • 为其他作者和利益相关者简化审阅：在审阅请求中指出版本之间的差异，如有必要，链接到内容的特定呈现版本。
  • 信任，但要验证。

测试、测试，再测试

无论您是撰写内容还是审阅内容，都要注意内容设计计划和受影响的产品，并在暂存或开发环境中检查呈现的内容，以确保内容准确描述了每个产品。