打开拉取请求

注意

代码开发者：如果您正在为即将发布的 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. 填写“提出文件更改”表单] end subgraph tasks2[ ] direction TB 4[4. 选择“提出文件更改”] --> 5[5. 选择“创建拉取请求”] --> 6[6. 填写“打开拉取请求”表单] 6 --> 7[7. 选择“创建拉取请求”] 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 的步骤。

在您看到问题的页面上，选择右侧导航面板中的编辑此页面选项。
在 GitHub Markdown 编辑器中进行更改。
在编辑器下方，填写提出文件更改表单。在第一个字段中，为您的提交信息添加标题。在第二个字段中，提供描述。
注意
请勿在提交信息中使用任何 GitHub 关键字。您可以在稍后将这些关键字添加到拉取请求描述中。
选择提出文件更改。
选择创建拉取请求。
将出现打开拉取请求屏幕。填写表单
- 拉取请求的主题字段将默认设置为提交摘要。如有必要，您可以更改它。
- 正文包含您的扩展提交信息（如果有），以及一些模板文本。添加模板文本要求的详细信息，然后删除额外的模板文本。
- 保持允许维护者进行编辑复选框处于选中状态。
注意
PR 描述是帮助审阅者了解您的更改的好方法。有关更多信息，请参阅打开 PR。
选择创建拉取请求。

在 GitHub 中解决反馈

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

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

转到已更改的文件选项卡。
选择拉取请求更改的任何文件上的铅笔（编辑）图标。
进行审阅者要求的更改。
提交更改。

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

当您的审阅完成时，审阅者会合并您的 PR，您的更改将在几分钟后生效。

从本地分支进行工作

如果您对 git 更熟悉，或者您的更改大于几行，请从本地分支进行工作。

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

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

flowchart LR 1[分支 kubernetes/website
存储库] --> 2[创建本地克隆
并设置上游] 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. 从本地分支进行工作以进行更改。

分支 kubernetes/website 存储库

导航到 kubernetes/website 存储库。
选择分支。

创建本地克隆并设置上游

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

git clone [email protected]:<github_username>/website
cd website
git submodule update --init --recursive --depth 1

导航到新的 website 目录。将 kubernetes/website 存储库设置为 upstream 远程
```
cd website

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

确认您的 origin 和 upstream 存储库

git remote -v

输出类似于

origin	[email protected]:<github_username>/website.git (fetch)
origin	[email protected]:<github_username>/website.git (push)
upstream	https://github.com/kubernetes/website.git (fetch)
upstream	https://github.com/kubernetes/website.git (push)

从您的分支的 origin/main 和 kubernetes/website 的 upstream/main 获取提交
```
git fetch origin
git fetch upstream
```
这确保您的本地存储库在您开始进行更改之前是最新的。
注意
此工作流程与 Kubernetes 社区 GitHub 工作流程不同。您无需在将更新推送到您的分支之前将 main 的本地副本与 upstream/main 合并。

创建分支

决定将您的工作基于哪个分支
- 对于现有内容的改进，请使用 upstream/main。
- 对于有关现有功能的新内容，请使用 upstream/main。
- 对于本地化内容，请使用本地化的约定。有关更多信息，请参阅本地化 Kubernetes 文档。
- 对于即将发布的 Kubernetes 版本中的新功能，请使用功能分支。有关更多信息，请参阅为发布编写文档。
- 对于多个 SIG Docs 贡献者协作的长期工作，例如内容重组，请使用为此工作创建的特定功能分支。
如果您需要帮助选择分支，请在 #sig-docs Slack 频道中询问。
基于步骤 1 中确定的分支创建新的分支。此示例假设基本分支是 upstream/main
```
git checkout -b <my_new_branch> upstream/main
```
使用文本编辑器进行更改。

随时使用 git status 命令查看您更改了哪些文件。

提交更改

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

在您的本地存储库中，检查您需要提交哪些文件

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")

将未暂存以提交的更改下列出的文件添加到提交中
```
git add <your_file_name>
```
对每个文件重复此操作。
在添加所有文件后，创建提交
```
git commit -m "Your commit message"
```
注意
请勿在提交信息中使用任何 GitHub 关键字。您可以在稍后将这些关键字添加到拉取请求描述中。
将您的本地分支及其新的提交推送到您的远程分支
```
git push origin <my_new_branch>
```

在本地预览您的更改

在推送或打开拉取请求之前在本地预览您的更改是个好主意。预览可以帮助您发现构建错误或 Markdown 格式问题。

您可以构建网站的容器映像，也可以在本地运行 Hugo。构建容器映像速度较慢，但会显示 Hugo Shortcodes，这对于调试很有用。

容器中的 Hugo
命令行上的 Hugo

注意

以下命令使用 Docker 作为默认容器引擎。设置 CONTAINER_ENGINE 环境变量以覆盖此行为。

在本地构建容器映像
只有在测试对 Hugo 工具本身的更改时才需要此步骤
```
# Run this in a terminal (if required)
make container-image
```

在容器中启动 Hugo

# Run this in a terminal
make container-serve

在 Web 浏览器中，导航到 https://127.0.0.1:1313。Hugo 会监视更改并在需要时重建网站。
要停止本地 Hugo 实例，请返回终端并键入 Ctrl+C，或关闭终端窗口。

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

安装 Hugo 版本，该版本在 website/netlify.toml 中指定。
如果您没有更新您的网站存储库，website/themes/docsy 目录将为空。没有本地主题副本，网站无法构建。要更新网站主题，请运行
```
git submodule update --init --recursive --depth 1
```
在终端中，转到您的 Kubernetes 网站存储库并启动 Hugo 服务器
```
cd <path_to_your_repo>/website
hugo server --buildFuture
```
在 Web 浏览器中，导航到 https://127.0.0.1:1313。Hugo 会监视更改并在需要时重建网站。
要停止本地 Hugo 实例，请返回终端并键入 Ctrl+C，或关闭终端窗口。

从您的分支到 kubernetes/website 打开拉取请求

图 3 显示了从您的分支到 kubernetes/website 打开 PR 的步骤。具体细节如下。

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

flowchart LR subgraph first[ ] direction TB 1[1. 转到 kubernetes/website 存储库] --> 2[2. 选择“新建拉取请求”] 2 --> 3[3. 选择跨分支比较] 3 --> 4[4. 从
头部存储库下拉菜单中选择您的分支] end subgraph second [ ] direction TB 5[5. 从
比较下拉菜单中选择您的分支] --> 6[6. 选择“创建拉取请求”] 6 --> 7[7. 为您的 PR
添加描述] 7 --> 8[8. 选择“创建拉取请求”] 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 的步骤。

在 Web 浏览器中，转到 kubernetes/website 存储库。
选择新建拉取请求。
选择跨分支比较。
从头部存储库下拉菜单中，选择您的分支。
从比较下拉菜单中，选择您的分支。
选择创建拉取请求。
为您的拉取请求添加描述
- 标题（不超过 50 个字符）：总结更改的意图。
- 描述：更详细地描述更改。
  - 如果存在相关的 GitHub 问题，请在描述中包含 Fixes #12345 或 Closes #12345。如果使用，GitHub 的自动化将在合并 PR 后关闭提到的问题。如果还有其他相关的 PR，请链接它们。
  - 如果您希望获得有关特定事项的建议，请在描述中包含您希望审阅者考虑的任何问题。
选择创建拉取请求按钮。

恭喜！您的拉取请求已在拉取请求中提供。

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

如果 Netlify 构建失败，请选择 **详细信息** 获取更多信息。
如果 Netlify 构建成功，选择 **详细信息** 将打开 Kubernetes 网站的暂存版本，其中应用了您的更改。审阅者将使用此版本检查您的更改。

GitHub 还会自动将标签分配给 PR，以帮助审阅者。如果需要，您也可以添加标签。有关更多信息，请参阅添加和删除问题标签。

本地解决反馈

在进行更改后，修改之前的提交
```
git commit -a --amend
```
- -a: 提交所有更改
- --amend: 修改之前的提交，而不是创建新的提交
如果需要，更新您的提交信息。
使用 git push origin <my_new_branch> 推送您的更改并重新运行 Netlify 测试。
注意
如果您使用 git commit -m 而不是修改，则必须在合并之前压缩您的提交。

来自审阅者的更改

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

从您的远程分支获取提交并重新整理您的工作分支
```
git fetch origin
git rebase origin/<your-branch-name>
```
重新整理后，强制推送新的更改到您的分支
```
git push --force-with-lease origin <your-branch-name>
```

合并冲突和重新整理

注意

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

如果其他贡献者在另一个 PR 中对同一文件进行更改，则可能会创建合并冲突。您必须解决 PR 中的所有合并冲突。

更新您的分支并重新整理您的本地分支

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

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

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

从 kubernetes/website 的 upstream/main 获取更改并重新整理您的分支
```
git fetch upstream
git rebase upstream/main
```
检查重新整理的结果
```
git status
```
这将导致一些文件被标记为冲突。
打开每个冲突文件，查找冲突标记：>>>、<<< 和 ===。解决冲突并删除冲突标记。
注意
有关更多信息，请参阅冲突是如何呈现的。
将文件添加到变更集
```
git add <filename>
```
继续重新整理
```
git rebase --continue
```
根据需要重复步骤 2 到 5。
应用所有提交后，git status 命令将显示重新整理已完成。
强制推送分支到您的分支
```
git push --force-with-lease origin <your-branch-name>
```
拉取请求不再显示任何冲突。

压缩提交

注意

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

如果您的 PR 包含多个提交，则必须在合并 PR 之前将它们压缩为单个提交。您可以在 PR 的 **提交** 选项卡上或通过在本地运行 git log 命令来检查您的 PR 中的提交数量。

注意

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

开始交互式重新整理
```
git rebase -i HEAD~<number_of_commits_in_branch>
```
压缩提交是一种重新整理的形式。-i 开关告诉 git 您想以交互方式重新整理。HEAD~<number_of_commits_in_branch 指示要查看多少个提交进行重新整理。
输出类似于
```
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。
注意
有关更多信息，请参阅交互模式。

开始编辑文件。

更改原始文本

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 解决反馈 1 和 7d54e15ee 解决反馈 2 压缩到 d875112ca 原始提交 中，只留下 d875112ca 原始提交 作为时间线的一部分。

保存并退出您的文件。

推送压缩的提交

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 时，请确保尽可能详细地填写模板。

下一步

阅读审阅了解有关审阅流程的更多信息。

上次修改于 2023 年 11 月 14 日下午 2:22 PST: [en] 在所有地方都以相同的方式提及 kubernetes/websites (#40493) (01ac54510a)