Help us learn about your current experience with the documentation. Take the survey.

产品可用性详情

产品可用性详情提供有关功能的信息。

  • 如果详情适用于整个页面，请将其放在页面顶部，但在 front matter 之后。
  • 如果适用于特定部分，请将详情放在相应的标题下方。

可用性详情包括层级、提供方式、状态和历史记录。

可用性详情的 Markdown 应如下所示：

title: '主题标题'
---

{{< details >}}

- 层级: Free, Premium, Ultimate
- 提供方式: GitLab.com, GitLab Self-Managed, GitLab Dedicated
- 状态: Experiment

{{< /details >}}

{{< history >}}

- [引入](https://link-to-issue) 于 GitLab 16.3。
- 更新于 GitLab 16.4。

{{< /history >}}

可用选项

为层级、提供方式、附加组件、状态和版本历史记录使用以下文本。

提供方式

对于提供方式，按以下顺序使用这些条目的任意组合，用逗号分隔：

  • GitLab.com
  • GitLab Self-Managed
  • GitLab Dedicated

例如：

  • GitLab.com
  • GitLab.com, GitLab Self-Managed
  • GitLab Self-Managed
  • GitLab Self-Managed, GitLab Dedicated

如果您已审阅页面且该页面不适用于 GitLab Dedicated， 分配元数据。

层级

对于层级，选择一个：

  • Free, Premium, Ultimate
  • Premium, Ultimate
  • Ultimate

GitLab Dedicated 始终包含 Ultimate 订阅。

附加组件

对于附加组件，可能性如下：

- 附加组件: GitLab Duo Pro
- 附加组件: GitLab Duo Enterprise
- 附加组件: GitLab Duo Pro 或 Enterprise
- 附加组件: GitLab Duo with Amazon Q

状态

对于状态，选择一个：

  • Beta
  • Experiment
  • Limited availability

已普遍可用的功能不应有状态。

历史

文档站点使用 shortcodes 来渲染版本历史，例如：

{{< history >}}

- [引入](https://issue-link) 于 GitLab 16.3。
- [变更](https://issue-link) 于 GitLab 16.4。

{{< /history >}}

此外：

  • 确保历史记录列在详情（如果有）之后，并紧跟在标题之后。
  • 确保输出正确生成。
  • 确保版本历史以 - 开头。
  • 如果可能，包含相关问题的链接。如果没有相关问题，链接到合并请求或史诗。
  • 不要链接到 confidential issues。
  • 不要链接到定价页面。不要包含订阅层级。

更新的功能

对于已更改或更新的功能，添加新的列表项。以功能名称或动名词开头。

例如：

- [引入](https://issue-link) 于 GitLab 13.1。
- 从问题板创建问题 [引入](https://issue-link) 于 GitLab 14.1。

或者：

- [引入](https://issue-link) 于 GitLab 13.1。
- 过期令牌的通知 [引入](https://issue-link) 于 GitLab 14.3。

移动的订阅层级

对于移动到其他订阅层级的功能，使用 moved：

- [移动](https://issue-link) 从 GitLab Ultimate 到 GitLab Premium 于 11.8。
- [移动](https://issue-link) 从 GitLab Premium 到 GitLab Free 于 12.0。

变更的功能状态

对于从实验版变更为 beta 版的功能状态，使用 changed：

- [引入](https://issue-link) 作为 [实验](../../policy/development_stages_support.md) 于 GitLab 15.7。
- [变更](https://issue-link) 从实验版到 beta 版于 GitLab 16.0。

对于从 beta 版变更为有限可用性的功能状态，使用 changed：

- [变更](https://issue-link) 从实验版到 beta 版于 GitLab 16.0。
- [变更](https://issue-link) 从 beta 版到有限可用性于 GitLab 16.3。

对于变更为普遍可用的更改，使用：

- [普遍可用](https://issue-link) 于 GitLab 16.10。

作为计划一部分提供的功能

对于作为计划一部分提供给用户的功能，添加新的列表项并链接到该计划。

- [引入](https://issue-link) 于 GitLab 15.1。
- 合并结果管道 [添加](https://issue-link) 到 [注册功能计划](https://page-link) 于 GitLab 16.7。

功能标志后的功能

对于在功能标志后引入的功能，添加有关功能标志的详细信息。更多信息，请参阅 Document features deployed behind feature flags。

移除版本

移除引用不受支持版本的历史记录项和内联文本。

GitLab 支持当前主版本和两个之前的主版本。例如，如果 18.0 是当前主版本，则 GitLab 18.0、17.0 和 16.0 的所有主版本和次版本都受支持。

有关当前支持版本的列表，请参阅 Version support。

仅当与功能标志相关的所有事件都发生在不受支持的版本中时，才移除有关 功能标志后的功能 的信息。如果标志尚未移除，读者应该知道它是什么时候引入的。

移除版本的时机

当新主版本即将发布时，创建合并请求以移除对最后一个不受支持版本的提及。仅在新的主版本里程碑期间合并它们。

例如，如果 GitLab 19.0 是下一个即将发布的主版本：

  • 支持的版本是 18、17 和 16。
  • 当 GitLab 19.0 发布时，GitLab 16 不再受支持。

创建合并请求以移除对 GitLab 16 的提及，但仅在 19.0 里程碑期间合并它们，在 18.11 发布之后。

何时添加可用性详情

在以下位置分配可用性详情：

  • 大多数 H1 主题标题，除了 doc/development/* 和 doc/solutions/* 下的页面。
  • 功能可用性详情与 H1 标题不同的主题标题。

H1 可用性详情应该是适用于页面上功能的最广泛可用性的详情。例如：

  • 如果某些部分适用于 Premium 和 Ultimate，而其他部分仅适用于 Ultimate， H1 层级: 应为 Premium, Ultimate。
  • 如果某些部分适用于所有实例，而其他部分仅适用于 GitLab Self-Managed， 提供方式: 应为 GitLab.com, GitLab Self-Managed, GitLab Dedicated。
  • 如果某些部分是 beta 版，而其他部分是实验版，H1 状态: 应为 Beta。 如果某些部分是 beta 版，而其他部分是普遍可用，那么 H1 不应有 状态:。

何时不添加可用性详情

不要为以下页面分配可用性详情：

  • 教程。
  • 比较不同层级功能的页面。
  • /development 文件夹中的页面。这些页面会自动分配 Contribute 徽章。
  • /solutions 文件夹中的页面。这些页面会自动分配 Solutions 徽章。

此外，当功能没有明显的订阅层级或提供方式时，也不要分配它们。 例如，如果某个功能在 GitLab.com 上适用于一个层级，而在 GitLab Self-Managed 上适用于不同的可用性。

在这种情况下，执行以下一项或多项操作：

  • 使用 metadata 指示页面已审阅且不需要可用性详情。
  • 使用 type="note" 警告框来描述可用性详情。
  • 在其他主题标题下添加可用性详情，在这些地方这些信息更有意义。
  • 不要在 H1 下添加可用性详情。

在子标题上重复层级、提供方式或状态

如果子标题与其父主题具有相同的层级、提供方式或状态， 则无需在子标题的徽章中重复信息。

例如，具有 层级: Premium, Ultimate 和 提供方式: GitLab.com 的子标题， 如果页面详情匹配，则无需重复详情：

title: 我的标题
---

{{< details >}}

- 层级: Premium, Ultimate
- 提供方式: GitLab.com

{{< /details >}}

适用于不同层级但相同提供方式的任何较低级别标题将是：

## 我的标题

{{< details >}}

- 层级: Ultimate

{{< /details >}}

内联可用性详情

通常，不应在其他文本中内联添加可用性详情。 功能真实来源应该是描述该功能的主题。

如果确实需要内联提及可用性详情，请以纯文本形式编写。例如，对于 API 主题：

要将问题分配到的用户 ID。仅限 Ultimate。

更多示例，请参阅 REST API style guide。

内联历史文本

如果您正在向现有主题添加内容，请将历史信息内联到现有文本中。如果可能，包含相关问题、合并请求或史诗的链接。例如：

GitLab 13.4 及更高版本中的投票策略 [要求](https://issue-link) 主要和次要投票者达成一致。

可用性详情的管理员文档

仅适用于实例管理员的主题应具有 GitLab Self-Managed 层级。 实例管理员文档通常包含提及以下内容的部分：

  • 更改 gitlab.rb 或 gitlab.yml 文件。
  • 访问 rails 控制台或运行 Rake 任务。
  • 在 Admin 区域执行操作。

这些页面还应提及这些任务是否只能由实例管理员完成。