为版本发布记录功能

每个主要 Kubernetes 版本都会引入需要记录的新功能。新版本还会对现有功能和文档进行更新（例如，将功能从 alpha 升级到 beta）。

通常，负责某个功能的 SIG 会将该功能的文档草稿作为拉取请求提交到 kubernetes/website 存储库的相应开发分支，并且 SIG Docs 团队的成员会提供编辑反馈或直接编辑草稿。本节介绍了两个组在发布期间使用的分支约定和流程。

面向文档贡献者

一般而言，文档贡献者不会从头开始为版本发布编写内容。相反，他们会与创建新功能的 SIG 合作，以完善文档草稿并使其准备好发布。

在选择要记录或协助记录的功能后，请在 #sig-docs Slack 频道、每周的 SIG Docs 会议或直接在功能 SIG 提出的 PR 中询问有关该功能的信息。如果您获得批准，您可以使用以下技术之一在 PR 中进行编辑：提交到其他人的 PR.

了解即将发布的功能

要了解即将发布的功能，请参加每周的 SIG 发布会议（请参阅社区页面以了解即将举行的会议）并监控 kubernetes/sig-release 存储库中的版本特定文档。每个版本在 /sig-release/tree/master/releases/ 目录中都有一个子目录。子目录包含版本计划、版本说明草稿以及列出版本团队中每个人的文档。

版本计划包含指向所有其他文档、会议、会议记录和与版本相关的里程碑的链接。它还包含有关版本目标和时间线以及该版本中实施的任何特殊流程的信息。在本文件底部附近，定义了几个与版本相关的术语。

本文件还包含指向 **功能跟踪表** 的链接，它是查找计划包含在版本中的所有新功能的官方方式。

版本团队文档列出了每个版本角色的负责人。如果您不清楚与特定功能或您遇到的问题应该联系谁，请参加版本会议询问您的问题，或联系版本负责人，以便他们将您引导到正确的人员。

版本说明草稿是了解有关版本中特定功能、更改、弃用以及其他信息的良好地方。内容直到版本周期后期才会最终确定，因此请谨慎使用。

功能跟踪表

功能跟踪表对于给定的 Kubernetes 版本列出了计划包含在版本中的每个功能。每个行项都包含功能名称、指向功能主要 GitHub 问题的链接、其稳定级别（Alpha、Beta 或 Stable）、负责实施它的 SIG 和个人、是否需要文档、功能的版本说明草稿以及它是否已合并。请记住以下几点：

Beta 和 Stable 功能通常比 Alpha 功能具有更高的文档优先级。
难以测试（因此难以记录）尚未合并或至少在其 PR 中被认为是功能完整的功能。
确定功能是否需要文档是一个手动过程。即使功能没有标记为需要文档，您也可能需要记录该功能。

面向开发人员或其他 SIG 成员

本节是为其他 Kubernetes SIG 的成员提供的信息，他们为版本发布记录新功能。

如果您是为 Kubernetes 开发新功能的 SIG 的成员，则需要与 SIG Docs 合作，以确保您的功能在版本发布之前及时记录。查看功能跟踪电子表格或在 #sig-release Kubernetes Slack 频道中检查，以验证计划细节和截止日期。

打开一个占位符 PR

在 kubernetes/website 存储库中针对 dev-1.32 分支打开一个 **草稿** 拉取请求，其中包含一个小的提交，您将在稍后修改它。要创建草稿拉取请求，请使用“创建拉取请求”下拉菜单并选择 **创建草稿拉取请求**，然后单击 **草稿拉取请求**。
编辑拉取请求说明以包含指向 kubernetes/kubernetes PR(s) 和 kubernetes/enhancements 问题的链接。
在相关的 kubernetes/enhancements 问题上留下一条评论，其中包含指向 PR 的链接，以通知负责管理此版本的文档人员功能文档即将到来，应跟踪以便发布。

如果您的功能不需要任何文档更改，请确保 sig-release 团队知道这一点，方法是在 #sig-release Slack 频道中提及这一点。如果功能需要文档但未创建 PR，则可能会从里程碑中删除该功能。

PR 准备审查

准备好后，使用功能文档填充您的占位符 PR，并将 PR 的状态从草稿更改为 **准备审查**。要将拉取请求标记为准备审查，请导航到合并框并单击 **准备审查**。

尽力描述您的功能以及如何使用它。如果您需要帮助组织文档，请在 #sig-docs Slack 频道中提问。

完成内容后，分配给您的功能的文档人员会对其进行审查。为了确保技术准确性，内容可能还需要相应 SIG(s) 的技术审查。使用他们的建议将内容调整到发布就绪状态。

如果您的功能需要文档，但未收到第一份草稿内容，则可能会从里程碑中删除该功能。

功能门

如果您的功能是 Alpha 或 Beta 功能，并且位于功能门后面，那么您需要在 content/en/docs/reference/command-line-tools-reference/feature-gates/ 中为其创建功能门文件。文件名称应为功能门，从 UpperCamelCase 转换为 kebab-case，以 .md 作为后缀。您可以查看同一目录中已有的其他文件以了解您的文件应该是什么样子。通常一个段落就足够了；对于更长的解释，请在其他地方添加文档并链接到该文档。

此外，为了确保您的功能门出现在 Alpha/Beta 功能门表格中，请在 Markdown 说明文件的前置 matter 中包含以下详细信息：

stages:
  - stage: <alpha/beta/stable/deprecated>  # Specify the development stage of the feature gate
    defaultValue: <true or false>     # Set to true if enabled by default, false otherwise
    fromVersion: <Version>            # Version from which the feature gate is available
    toVersion: <Version>              # (Optional) The version until which the feature gate is available

对于全新的功能门，还需要单独描述该功能门；在 content/en/docs/reference/command-line-tools-reference/feature-gates/ 中创建一个新的 Markdown 文件（使用其他文件作为模板）。

当您将功能门从默认禁用更改为默认启用时，您可能还需要更改其他文档（不仅仅是功能门列表）。注意诸如“exampleSetting 字段是一个 beta 字段，默认情况下处于禁用状态。您可以通过启用 ProcessExampleThings 功能门来启用它。”之类的内容。

如果您的功能已 GA 或已弃用，请在说明文件中的 stages 块中包含一个额外的 stage 条目。确保 Alpha 和 Beta 阶段保持不变。此步骤将功能门从 Alpha/功能功能门表格转移到毕业或弃用功能的功能门表格。例如

stages:
  - stage: alpha 
    defaultValue: false
    fromVersion: "1.12"
    toVersion: "1.12"
  - stage: beta 
    defaultValue: true
    fromVersion: "1.13"
    toVersion: "1.18"    
  # Added 'stable' stage block to existing stages.  
  - stage: stable     
    defaultValue: true
    fromVersion: "1.19"
    toVersion: "1.27"

最终，Kubernetes 将完全停止包含功能门。为了表示删除功能门，请在相应说明文件的前置 matter 中包含 removed: true。此操作会触发将功能门从已移除功能的功能门部分转移到名为功能门（已移除）的专用页面，包括其描述。

所有 PR 都已审查并准备合并

如果您的 PR 在版本发布截止日期之前尚未合并到 dev-1.32 分支中，请与负责管理版本的文档人员合作，在截止日期之前将其合并。如果您的功能需要文档，但文档尚未准备好，则可能会从里程碑中删除该功能。

上次修改时间：2023 年 12 月 28 日太平洋标准时间下午 2:50：修改有关记录功能门更改的指南 (98c5caf14c)