打开一个 Pull Request

要贡献新的内容页面或改进现有内容页面，请打开一个 Pull Request (PR)。请确保你遵循准备工作章节中的所有要求。

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

如果你的更改较大，请阅读使用本地派生库进行工作了解如何在你的计算机上本地进行更改。

使用 GitHub 进行更改

如果你不熟悉 git 工作流，这里有一个更容易打开 Pull Request 的方法。图 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. 填写 Propose file change（提议更改文件）] end subgraph tasks2[ ] direction TB 4[4. 选择 Propose file change（提议更改文件）] --> 5[5. 选择 Create pull request（创建 Pull Request）] --> 6[6. 填写 Open a pull request（打开 Pull Request）] 6 --> 7[7. 选择 Create pull request（创建 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. 在你看到问题的页面上，在右侧导航面板中选择编辑此页选项。

  2. 在 GitHub Markdown 编辑器中进行更改。

  3. 在编辑器下方，填写 Propose file change 表单。在第一个字段中，为你的提交消息指定标题。在第二个字段中，提供描述。

  4. 选择 Propose file change。

  5. 选择 Create pull request。

  6. 出现 Open a pull request 屏幕。填写表单。

    • Pull Request 的主题 (Subject) 字段默认为提交摘要。如果需要，你可以更改它。
    • 正文 (Body) 包含你的扩展提交消息（如果有）和一些模板文本。添加模板文本要求提供的详细信息，然后删除多余的模板文本。
    • 保持选中 Allow edits from maintainers（允许维护者编辑）复选框。

  7. 选择 Create pull request。

在 GitHub 中处理反馈

在合并 Pull Request 之前，Kubernetes 社区成员会进行评审并批准。k8s-ci-robot 会根据页面中提到的最近所有者建议评审者。如果你有特定的评审者，请在评论中留下他们的 GitHub 用户名。

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

  1. 转到文件更改 (Files changed) 选项卡。
  2. 在 Pull Request 更改的任何文件上选择铅笔（编辑）图标。
  3. 进行要求的更改。
  4. 提交更改。

如果你在等待评审者，请每 7 天联系一次。你也可以在 #sig-docs Slack 频道中发布消息。

评审完成后，评审者会合并你的 PR，你的更改将在几分钟后生效。

使用本地派生库进行工作

如果你对 git 更熟悉，或者你的更改大于几行，请使用本地派生库进行工作。

确保你的计算机上安装了 git。你也可以使用 git UI 应用程序。

图 2 显示了当你从本地派生库进行工作时需要遵循的步骤。每个步骤的详细说明如下。

flowchart LR 1[派生 kubernetes/website
仓库] --> 2[创建本地克隆
并设置 upstream] subgraph changes[你的更改] direction TB S[ ] -.- 3[创建一个分支
例如: my_new_branch] --> 3a[使用文本编辑器进行更改] --> 4["在本地预览你的更改
(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. 从本地派生库进行工作来做出你的更改。

派生 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

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

创建分支

  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 命令查看你更改了哪些文件。

提交你的更改

准备提交 Pull Request 时，提交你的更改。

  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"

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

    git push origin <my_new_branch>

在本地预览你的更改

在推送更改或打开 Pull Request 之前，最好在本地预览你的更改。预览可以让你发现构建错误或 Markdown 格式问题。

你可以构建网站的容器镜像或在本地运行 Hugo。构建容器镜像较慢，但会显示Hugo Shortcode，这对调试很有用。

  1. 在本地构建容器镜像
    仅在你测试 Hugo 工具本身的更改时才需要此步骤

    # Run this in a terminal (if required)
make container-image

  2. 在你的本地仓库中获取子模块依赖

    # Run this in a terminal
make module-init

  3. 在容器中启动 Hugo

    # Run this in a terminal
make container-serve

  4. 在网页浏览器中，导航到 http://localhost:1313。Hugo 会监听更改并在需要时重建站点。

  5. 要停止本地 Hugo 实例，返回终端并输入 Ctrl+C，或关闭终端窗口。

或者，在你的计算机上安装并使用 hugo 命令

  1. 安装 Hugo (Extended edition) 和 Node，版本应与 website/netlify.toml 中指定的版本一致。

  2. 安装所有依赖项

    npm ci

  3. 在终端中，进入你的 Kubernetes website 仓库并启动 Hugo 服务器

    cd <path_to_your_repo>/website
make serve

    如果你在 Windows 机器上或无法运行 make 命令，请使用以下命令

    hugo server --buildFuture

  4. 在网页浏览器中，导航到 http://localhost:1313。Hugo 会监听更改并在需要时重建站点。

  5. 要停止本地 Hugo 实例，返回终端并输入 Ctrl+C，或关闭终端窗口。

从你的派生库向 kubernetes/website 打开一个 Pull Request

图 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. 从
head repository 下拉菜单中选择你的派生库] end subgraph second [ ] direction TB 5[5. 从
compare 下拉菜单中选择你的分支] --> 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. 为你的 Pull Request 添加描述

    • 标题 (Title)（50 个字符或更少）：总结更改的意图。

    • 描述 (Description)：更详细地描述更改。

      • 如果存在相关的 GitHub Issue，请在描述中包含 Fixes #12345 或 Closes #12345。如果使用这些关键词，GitHub 的自动化功能会在 PR 合并后关闭提到的 Issue。如果还有其他相关的 PR，也请一并链接。
      • 如果你想在特定事项上征求建议，请在描述中包含你希望评审者考虑的任何问题。

  8. 选择 Create pull request 按钮。

恭喜！你的 Pull Request 已可在Pull requests 中查看。

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

  • 如果 Netlify 构建失败，选择 Details 查看更多信息。
  • 如果 Netlify 构建成功，选择 Details 会打开一个带有你更改的 Kubernetes 网站的预发布版本。评审者就是通过这种方式检查你的更改。

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

在本地处理反馈

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

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

  2. 如有需要，更新你的提交消息。

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

评审者所做的更改

有时评审者会提交到你的 Pull Request。在进行任何其他更改之前，请拉取这些提交。

  1. 从你的远程派生库拉取提交并 rebase 你的工作分支

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

  2. Rebase 后，强制推送新更改到你的派生库

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

合并冲突和 rebasing

如果另一位贡献者在另一个 PR 中提交了对同一文件的更改，可能会导致合并冲突。你必须解决 PR 中的所有合并冲突。

  1. 更新你的派生库并 rebase 你的本地分支

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

    然后强制推送更改到你的派生库

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

  2. 从 kubernetes/website 的 upstream/main 拉取更改并 rebase 你的分支

    git fetch upstream
git rebase upstream/main

  3. 检查 rebase 的结果

    git status

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

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

  5. 将文件添加到更改集

    git add <filename>

  6. 继续 rebase

    git rebase --continue

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

    应用所有提交后，git status 命令会显示 rebase 已完成。

  8. 强制推送分支到你的派生库

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

    Pull Request 不再显示任何冲突。

压缩提交

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

  1. 开始交互式 rebase

    git rebase -i HEAD~<number_of_commits_in_branch>

    压缩提交是 rebase 的一种形式。-i 开关告诉 git 你想要交互式 rebase。HEAD~<number_of_commits_in_branch 指示 rebase 时查看多少个提交。

    输出类似于

    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.

    输出的第一部分列出了 rebase 中的提交。第二部分列出了每个提交的选项。更改 pick 这个词会改变 rebase 完成后提交的状态。

    对于 rebasing，请关注 squash 和 pick。

  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 组织中的所有仓库。这可以帮助你确定在哪里提交 Issue 或 PR。

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

大多数仓库使用 Issue 和 PR 模板。查看一些开放的 Issue 和 PR，了解该团队的流程。在提交 Issue 或 PR 时，务必尽可能详细地填写模板。

接下来

  • 阅读评审，了解有关评审过程的更多信息。
最后修改时间 太平洋标准时间 2025 年 2 月 4 日下午 6:46：更新了文档，其中包含安装 Docsy 主题并与 Hugo 一起使用的正确步骤。(9538fde064)