提交拉取请求

要贡献新内容页面或改进现有内容页面，请开启拉取请求 (PR)。确保你遵守了在开始之前部分中的所有要求。

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

如果你的改动较大，请阅读通过本地分叉工作来学习如何在计算机本地进行更改。

使用 GitHub 进行更改

如果你对 git 工作流不太熟悉，这里有一种开启拉取请求的简便方法。图 1 概述了步骤，随后是详细说明。

图 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) 屏幕。填写表单

   • 拉取请求的 添加标题 字段默认为提交摘要。如果需要，你可以进行更改。
   • 添加描述 字段包含你扩展的提交消息（如果有的话）和一些模板文本。添加模板文本要求填写的详细信息，然后删除多余的模板文本。
   • 勾选 允许维护者进行编辑 (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 图形界面应用程序。

图 2 显示了通过本地分叉工作时应遵循的步骤。随后是每个步骤的详细信息。

图 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。

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

1. 在 Web 浏览器中，转到 kubernetes/website 代码库。

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

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

4. 从 源代码库 (head repository) 下拉菜单中选择你的分叉。

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

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

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

   • 标题（50 个字符或以内）：简述改动意图。

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

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

8. 选择 创建拉取请求 (Create 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 测试。

   说明

   如果你使用 git commit -m 而不是修正提交，则在合并之前必须压缩 (squash) 你的提交。

来自审阅者的更改

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

1. 从你的远程分叉获取提交并变基 (rebase) 你的工作分支

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

2. 变基后，强制推送新更改到你的分叉

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

合并冲突与变基 (Rebasing)

如果另一位贡献者在另一个 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)

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

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。

   说明

   有关更多信息，请参阅交互模式。

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

接下来

• 阅读审阅以了解有关审阅过程的更多信息。