提交拉取请求

说明

代码开发者：如果你正在为即将发布的 Kubernetes 版本记录新特性，请参阅 记录新特性。

要贡献新内容页面或改进现有内容页面，请开启一个拉取请求 (PR)。确保遵循 开始之前 章节中的所有要求。

如果你的修改很小，或者你不熟悉 git，请阅读 使用 GitHub 进行更改 来学习如何编辑页面。

如果你的修改很大，请阅读 从本地仓库分支进行工作 来学习如何在你自己的电脑上进行本地修改。

使用 GitHub 进行更改

如果你对 git 工作流不太熟悉，这里有一种更简单的开启拉取请求的方法。图 1 概述了这些步骤，详细信息随后列出。

flowchart LR A([fa:fa-user 新
贡献者]) --- id1[(kubernetes/website
GitHub)] subgraph tasks[使用 GitHub 进行更改] direction TB 0[ ] -.- 1[1. 编辑此页面] --> 2[2. 使用 GitHub markdown
编辑器进行更改] 2 --> 3[3. 选择提交更改 (Commit changes)...] end subgraph tasks2[ ] direction TB 4[4. 选择提议更改 (Propose changes)] --> 5[5. 选择创建拉取请求 (Create pull request)] --> 6[6. 填写开启拉取请求] 6 --> 7[7. 选择创建拉取请求 (Create pull request)] end id1 --> tasks --> tasks2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,1,2,3,4,5,6,7 grey class 0 spacewhite class tasks,tasks2 white class id1 k8s

图 1. 使用 GitHub 开启 PR 的步骤。

  1. 在你看到问题的页面上，在右侧导航栏中选择 编辑此页面 (Edit this page) 选项。

  2. 在 GitHub 的 markdown 编辑器中进行你的修改。

  3. 在编辑器上方的右侧，选择 提交更改 (Commit changes)。在第一个字段中，为你的提交信息输入标题。在第二个字段中，提供详细说明。

    说明

    不要在你的提交信息中使用任何 GitHub 关键字。你可以稍后将它们添加到拉取请求的描述中。

  4. 选择 提议更改 (Propose changes)。

  5. 选择 创建拉取请求 (Create pull request)。

  6. 出现 开启拉取请求 (Open a pull request) 屏幕。填写表单。

    • 拉取请求的 添加标题 (Add a title) 字段默认为提交摘要。你可以根据需要进行修改。
    • 添加描述 (Add a description) 字段包含你的扩展提交信息（如果有）和一些模板文本。添加模板文本要求的详细信息，然后删除多余的模板文本。
    • 保持 允许维护者编辑 (Allow edits from maintainers) 复选框为选中状态。

    说明

    PR 描述是帮助审阅者理解你更改的好方法。更多信息，请参阅 开启 PR。

  7. 选择 创建拉取请求 (Create pull request)。

在 GitHub 中处理反馈

在合并拉取请求之前，Kubernetes 社区成员会对其进行审查和批准。k8s-ci-robot 会根据页面中提到的最近所有者建议审阅者。如果你有特定的审阅者人选，请在评论中写下他们的 GitHub 用户名。

如果审阅者要求你进行更改

  1. 转到 Files changed (文件更改) 选项卡。
  2. 选择拉取请求中已更改的任何文件上的铅笔（编辑）图标。
  3. 进行要求的更改。
  4. 提交这些更改。

如果你在等待审阅者反馈，请每 7 天跟进一次。你也可以在 #sig-docs Slack 频道中发布消息。

当你的审查完成时，审阅者会合并你的 PR，你的更改将在几分钟后上线。

从本地仓库分支进行工作

如果你有更丰富的 git 经验，或者你的更改超过了几行，请从本地分支进行工作。

确保你的电脑上安装了 git。你也可以使用 git UI 应用程序。

图 2 显示了从本地分支工作时需要遵循的步骤。每个步骤的详细信息如下。

flowchart LR 1[派生 (Fork) kubernetes/website
仓库] --> 2[创建本地克隆
并设置上游 (Upstream)] subgraph changes[你的更改] direction TB S[ ] -.- 3[创建分支
例如: my_new_branch] --> 3a[使用文本编辑器
进行更改] --> 4["使用 Hugo 在本地
预览你的更改
(localhost:1313)
或构建容器镜像"] end subgraph changes2[提交 / 推送] direction TB T[ ] -.- 5[提交你的更改] --> 6[推送提交到
origin/my_new_branch] end 2 --> changes --> changes2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class 1,2,3,3a,4,5,6 grey class S,T spacewhite class changes,changes2 white

图 2. 通过本地分支进行更改的工作方式。

派生 (Fork) kubernetes/website 仓库

  1. 导航到 kubernetes/website 仓库。
  2. 选择 派生 (Fork)。

创建本地克隆并设置上游 (Upstream)

  1. 在终端窗口中，克隆你的分支并更新 Docsy Hugo 主题

    git clone git@github.com:<github_username>/website
cd website

  2. 导航到新的 website 目录。将 kubernetes/website 仓库设置为 upstream 远程仓库

    cd website

git remote add upstream https://github.com/kubernetes/website.git

  3. 确认你的 origin 和 upstream 仓库

    git remote -v

    输出类似于

    origin	git@github.com:<github_username>/website.git (fetch)
origin	git@github.com:<github_username>/website.git (push)
upstream	https://github.com/kubernetes/website.git (fetch)
upstream	https://github.com/kubernetes/website.git (push)

  4. 从你分支的 origin/main 和 kubernetes/website 的 upstream/main 获取提交

    git fetch origin
git fetch upstream

    这确保了在开始进行更改之前，你的本地仓库是最新的。

    说明

    此工作流与 Kubernetes 社区 GitHub 工作流 不同。在将更新推送到你的分支之前，不需要合并本地的 main 和 upstream/main。

创建分支

  1. 确定要在哪个分支上进行工作

    • 对于现有内容的改进，使用 upstream/main。
    • 对于关于现有功能的新内容，使用 upstream/main。
    • 对于本地化内容，请使用该本地化版本的惯例。更多信息，请参阅 本地化 Kubernetes 文档。
    • 对于即将发布的 Kubernetes 版本中的新功能，使用功能分支。更多信息，请参阅 记录发布内容。
    • 对于需要多个 SIG Docs 贡献者协作的长期工作（如内容重组），请使用为该工作创建的特定功能分支。

    如果你在选择分支方面需要帮助，请在 #sig-docs Slack 频道中提问。

  2. 创建一个基于步骤 1 中确定的分支的新分支。此示例假设基础分支是 upstream/main

    git checkout -b <my_new_branch> upstream/main

  3. 使用文本编辑器进行你的更改。

在任何时候，都可以使用 git status 命令查看你更改的文件。

提交你的更改

当你准备好提交拉取请求时，提交你的更改。

  1. 在你的本地仓库中，检查你需要提交哪些文件

    git status

    输出类似于

    On branch <my_new_branch>
Your branch is up to date with 'origin/<my_new_branch>'.

Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified:   content/en/docs/contribute/new-content/contributing-content.md

no changes added to commit (use "git add" and/or "git commit -a")

  2. 将 Changes not staged for commit (未暂存以供提交的更改) 下列出的文件添加到提交中

    git add <your_file_name>

    对每个文件重复此操作。

  3. 添加所有文件后，创建一个提交

    git commit -m "Your commit message"

    说明

    不要在你的提交信息中使用任何 GitHub 关键字。你可以稍后将它们添加到拉取请求的描述中。

  4. 将你的本地分支及其新提交推送到你的远程分支

    git push origin <my_new_branch>

在本地预览你的更改

在推送更改或开启拉取请求之前，在本地预览你的更改是一个好主意。本地预览 一文解释了如何运行本地网站并预览建议的更改。

从你的分支向 kubernetes/website 发起拉取请求

图 3 显示了从你的分支向 kubernetes/website 开启 PR 的步骤。详细信息如下。

请注意，贡献者可以将 kubernetes/website 称为 k/website。

flowchart LR subgraph first[ ] direction TB 1[1. 前往 kubernetes/website 仓库] --> 2[2. 选择新建拉取请求 (New Pull Request)] 2 --> 3[3. 选择跨分支比较 (compare across forks)] 3 --> 4[4. 从头仓库下拉菜单中
选择你的分支] end subgraph second [ ] direction TB 5[5. 从比较下拉菜单中
选择你的分支] --> 6[6. 选择创建拉取请求 (Create Pull Request)] 6 --> 7[7. 为你的 PR 添加
描述] 7 --> 8[8. 选择创建拉取请求 (Create pull request)] end first --> second classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold class 1,2,3,4,5,6,7,8 grey class first,second white

图 3. 从你的分支向 kubernetes/website 开启 PR 的步骤。

  1. 在网页浏览器中，转到 kubernetes/website 仓库。

  2. 选择 新建拉取请求 (New Pull Request)。

  3. 选择 跨分支比较 (compare across forks)。

  4. 从 head repository (头仓库) 下拉菜单中，选择你的分支。

  5. 从 compare (比较) 下拉菜单中，选择你的分支。

  6. 选择 创建拉取请求 (Create Pull Request)。

  7. 为你的拉取请求添加描述

    • 标题 (50 个字符以内)：总结更改意图。

    • 描述：更详细地描述更改内容。

      • 如果有相关的 GitHub 议题，请在描述中包含 Fixes #12345 或 Closes #12345。如果使用这些关键字，GitHub 的自动化机制将在合并 PR 后关闭提到的议题。如果还有其他相关的 PR，请一并链接。
      • 如果你想就某项特定内容征求意见，请在描述中包含你希望审阅者考虑的问题。

  8. 选择 创建拉取请求 (Create pull request) 按钮。

恭喜！你的拉取请求已在 Pull requests 中显示。

开启 PR 后，GitHub 会运行自动化测试，并尝试使用 Netlify 部署预览。

  • 如果 Netlify 构建失败，选择 Details (详细信息) 以获取更多信息。
  • 如果 Netlify 构建成功，选择 Details (详细信息) 将打开一个应用了你更改的 Kubernetes 网站预览版。这就是审阅者检查你更改的方式。

GitHub 还会自动为 PR 分配标签，以帮助审阅者。如果需要，你也可以添加标签。更多信息，请参阅 添加和移除议题标签。

在本地处理反馈

  1. 进行更改后，修改你之前的提交

    git commit -a --amend
    • -a：提交所有更改
    • --amend：修改上一次提交，而不是创建一个新的提交

  2. 如果需要，更新你的提交信息。

  3. 使用 git push origin <my_new_branch> 来推送你的更改并重新运行 Netlify 测试。

    说明

    如果你使用 git commit -m 而不是修改提交，你必须在合并前 压缩你的提交。

来自审阅者的更改

有时审阅者会对你的拉取请求进行提交。在进行任何其他更改之前，请获取这些提交。

  1. 从你的远程分支获取提交并重置你的工作分支

    git fetch origin
git rebase origin/<your-branch-name>

  2. 重置后，强制将新更改推送到你的分支

    git push --force-with-lease origin <your-branch-name>

合并冲突和重置 (Rebasing)

说明

更多信息，请参阅 Git 分支 - 基础分支和合并，高级合并，或者在 #sig-docs Slack 频道中寻求帮助。

如果另一个贡献者在另一个 PR 中对同一文件进行了更改，可能会产生合并冲突。你必须解决 PR 中的所有合并冲突。

  1. 更新你的分支并重置你的本地分支

    git fetch origin
git rebase origin/<your-branch-name>

    然后强制将更改推送到你的分支

    git push --force-with-lease origin <your-branch-name>

  2. 从 kubernetes/website 的 upstream/main 获取更改并重置你的分支

    git fetch upstream
git rebase upstream/main

  3. 检查重置的结果

    git status

    这会导致一些文件被标记为存在冲突。

  4. 打开每个存在冲突的文件并查找冲突标记：>>>, <<<, 和 ===。解决冲突并删除冲突标记。

    说明

    更多信息，请参阅 如何展示冲突。

  5. 将文件添加到变更集

    git add <filename>

  6. 继续重置

    git rebase --continue

  7. 根据需要重复步骤 2 到 5。

    应用所有提交后，git status 命令将显示重置已完成。

  8. 强制将分支推送到你的分支

    git push --force-with-lease origin <your-branch-name>

    拉取请求将不再显示任何冲突。

压缩提交 (Squashing commits)

说明

更多信息，请参阅 Git 工具 - 重写历史，或者在 #sig-docs Slack 频道中寻求帮助。

如果你的 PR 有多个提交，你必须在合并 PR 之前将它们压缩成一个提交。你可以在 PR 的 Commits (提交) 选项卡上，或者通过在本地运行 git log 命令来检查提交数量。

说明

本主题假设 vim 是你的命令行文本编辑器。

  1. 开始交互式重置

    git rebase -i HEAD~<number_of_commits_in_branch>

    压缩提交是重置的一种形式。-i 开关告诉 git 你想要进行交互式重置。HEAD~<分支中的提交数量> 指示在重置时查看多少个提交。

    输出类似于

    pick d875112ca Original commit
pick 4fa167b80 Address feedback 1
pick 7d54e15ee Address feedback 2

# Rebase 3d18sf680..7d54e15ee onto 3d183f680 (3 commands)

...

# These lines can be re-ordered; they are executed from top to bottom.

    输出的第一部分列出了重置中的提交。第二部分列出了每个提交的选项。更改单词 pick 将在重置完成后更改提交的状态。

    就重置而言，请专注于 squash 和 pick。

    说明

    更多信息，请参阅 交互模式 (Interactive Mode)。

  2. 开始编辑文件。

    更改原始文本

    pick d875112ca Original commit
pick 4fa167b80 Address feedback 1
pick 7d54e15ee Address feedback 2

    到

    pick d875112ca Original commit
squash 4fa167b80 Address feedback 1
squash 7d54e15ee Address feedback 2

    这将提交 4fa167b80 Address feedback 1 和 7d54e15ee Address feedback 2 压缩到 d875112ca Original commit 中，仅保留 d875112ca Original commit 作为时间线的一部分。

  3. 保存并退出你的文件。

  4. 推送你的压缩提交

    git push --force-with-lease origin <branch_name>

为其他仓库做出贡献

Kubernetes 项目 包含 50 多个仓库。其中许多仓库包含文档：面向用户的帮助文本、错误消息、API 参考或代码注释。

如果你看到想要改进的文本，请使用 GitHub 搜索 Kubernetes 组织下的所有仓库。这可以帮助你找到提交议题或 PR 的位置。

每个仓库都有自己的流程和程序。在你提交议题或 PR 之前，请阅读该仓库的 README.md, CONTRIBUTING.md 和 code-of-conduct.md（如果存在）。

大多数仓库都使用议题和 PR 模板。查看一些已开启的议题和 PR，以了解团队的流程。在提交议题或 PR 时，请确保尽可能详细地填写模板。

接下来

  • 阅读 审查 来详细了解审查过程。

最后修改时间：2026 年 4 月 14 日凌晨 1:15（太平洋标准时间）：fix(links): update kubernetes/community links from master to main (03c191bcc4)