为发布版本编写功能文档

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

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

对于文档贡献者

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

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

了解即将推出的功能

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

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

此文档还包含指向功能跟踪表的链接，这是查找计划在版本中推出的所有新功能的官方方式。

发布团队文档列出了谁负责每个发布角色。如果不清楚应该与谁讨论您遇到的特定功能或问题，可以参加发布会议提出您的问题，或者联系发布负责人以便他们可以重定向您。

发布说明草案是了解特定功能、更改、弃用以及更多有关发布信息的好地方。内容在发布周期的后期才会最终确定，因此请谨慎使用。

功能跟踪表

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

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

对于开发人员或其他 SIG 成员

本节是为 Kubernetes 其他 SIG 成员记录发布版本的新功能而准备的信息。

如果您是为 Kubernetes 开发新功能的 SIG 成员，您需要与 SIG Docs 合作，以确保您的功能在发布之前得到记录。请查看功能跟踪表或在 #sig-release Kubernetes Slack 频道中查看，以验证调度详细信息和截止日期。

打开占位符 PR

针对 kubernetes/website 存储库中的 dev-1.33 分支打开一个草稿拉取请求，其中包含一个您稍后将修改的小提交。要创建草稿拉取请求，请使用创建拉取请求下拉列表，选择创建草稿拉取请求，然后单击草稿拉取请求。
编辑拉取请求描述，以包含指向 kubernetes/kubernetes PR 和 kubernetes/enhancements 问题的链接。
在相关的 kubernetes/enhancements 问题上留下评论，其中包含指向 PR 的链接，以通知管理此版本的文档人员，该功能文档即将发布，应在发布时进行跟踪。

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

PR 准备好进行审查

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

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

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

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

功能门

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

此外，为了确保您的功能门出现在Alpha/Beta 功能门表中，请在您的 Markdown 描述文件的前言中包含以下详细信息

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/Beta 功能门表过渡到已毕业或已弃用功能的功能门表。例如

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

最终，Kubernetes 将完全停止包含该功能门。要表示删除功能门，请在相应描述文件的前言中包含 removed: true。进行该更改意味着功能门信息从已毕业或已弃用功能的功能门部分移动到名为功能门（已删除）的专用页面，包括其描述。

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

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

上次修改时间为 2024 年 10 月 18 日上午 10:33 PST：清理 new-content/new-features.md (1503cc0cfd)