打开拉取请求
注意
代码开发者:如果您正在为即将发布的 Kubernetes 版本编写新功能文档,请参阅文档新功能。要贡献新内容页面或改进现有内容页面,请打开一个 Pull Request (PR)。确保您遵循开始之前部分的所有要求。
如果您的更改很小,或者您不熟悉 Git,请阅读使用 GitHub 进行的更改以了解如何编辑页面。
如果您的更改很大,请阅读从本地 fork 开始工作以了解如何在本地计算机上进行更改。
使用 GitHub 进行的更改
如果您对 Git 工作流不太熟悉,这里有一个更简单的方法来打开 Pull Request。图 1 概述了这些步骤,详细信息如下。
Contributor]) --- 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. 选择“创建 Pull Request”] --> 6[6. 填写“打开 Pull Request”] 6 --> 7[7. 选择“创建 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 的步骤。
在您看到问题的页面上,在右侧导航面板中选择“编辑此页面”选项。
在 GitHub Markdown 编辑器中进行更改。
在编辑器下方,填写“建议文件更改”表单。在第一个字段中,为您的提交消息添加标题。在第二个字段中,提供描述。
注意
请勿在提交消息中使用任何GitHub 关键字。稍后可以将它们添加到 Pull Request 描述中。选择“建议文件更改”。
选择“创建 Pull Request”。
将出现“打开 Pull Request”屏幕。填写表单。
- Pull Request 的“主题”字段默认为提交摘要。如果需要,可以更改它。
- “正文”包含您的扩展提交消息(如果您有的话)以及一些模板文本。将模板文本要求的详细信息添加到其中,然后删除多余的模板文本。
- 保留“允许维护者编辑”复选框的选中状态。
注意
PR 描述是帮助审阅者理解您更改的好方法。有关更多信息,请参阅打开 PR。选择“创建 Pull Request”。
在 GitHub 中处理反馈
在合并 Pull Request 之前,Kubernetes 社区成员会对其进行审查和批准。k8s-ci-robot
会根据页面中提到的最近所有者推荐审阅者。如果您有特定的人选,请在评论中留下他们的 GitHub 用户名。
如果审阅者要求您进行更改
- 转到“已更改文件”选项卡。
- 选择 Pull Request 所更改的任何文件上的铅笔(编辑)图标。
- 进行请求的更改。
- 提交更改。
如果您正在等待审阅者,每 7 天联系一次。您也可以在 #sig-docs
Slack 频道中发布消息。
审查完成后,审阅者会合并您的 PR,您的更改将在几分钟后上线。
从本地 fork 开始工作
如果您对 Git 更熟悉,或者您的更改大于几行,请从本地 fork 开始工作。
确保您的计算机上已安装 Git。您也可以使用 Git UI 应用程序。
图 2 展示了从本地 fork 工作时要遵循的步骤。每个步骤的详细信息如下。
repository] --> 2[创建本地克隆
并设置 upstream] subgraph changes[您的更改] direction TB S[ ] -.- 3[创建分支
例如:my_new_branch] --> 3a[使用
文本编辑器进行更改] --> 4["本地预览您的更改
使用 Hugo
(localhost:1313)
或构建容器镜像"] end subgraph changes2[Commit / Push] 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 工作以进行更改。
Fork kubernetes/website 存储库
- 导航到
kubernetes/website
存储库。 - 选择“Fork”。
创建本地克隆并设置 upstream
在终端窗口中,克隆您的 fork 并更新Docsy Hugo 主题
git clone git@github.com:<github_username>/website cd website
导航到新的
website
目录。将kubernetes/website
存储库设置为upstream
remotecd website git remote add upstream https://github.com/kubernetes/website.git
确认您的
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)
从您的 fork 的
origin/main
和kubernetes/website
的upstream/main
中获取提交git fetch origin git fetch upstream
这可以确保您的本地存储库在开始更改之前是最新的。
注意
此工作流程与Kubernetes Community GitHub Workflow 不同。在将更新推送到您的 fork 之前,您无需将本地的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
命令查看您已更改的文件。
提交您的更改
当您准备好提交 Pull Request 时,请提交您的更改。
在您的本地存储库中,检查需要提交的文件
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 关键字。稍后可以将它们添加到 Pull Request 描述中。将您的本地分支及其新提交推送到您的远程 fork
git push origin <my_new_branch>
本地预览您的更改
在推送更改或打开 Pull Request 之前,最好先在本地预览您的更改。预览可以让您发现构建错误或 Markdown 格式问题。
您可以构建网站的容器镜像或在本地运行 Hugo。构建容器镜像速度较慢,但会显示Hugo shortcodes,这对于调试可能很有用。
注意
下面的命令默认使用 Docker 作为容器引擎。设置CONTAINER_ENGINE
环境变量以覆盖此行为。在本地构建容器镜像
仅当您正在测试 Hugo 工具本身的更改时,才需要此步骤# Run this in a terminal (if required) make container-image
在本地存储库中获取子模块依赖项
# Run this in a terminal make module-init
在容器中启动 Hugo
# Run this in a terminal make container-serve
在 Web 浏览器中,导航到
https://:1313
。Hugo 会监视更改并根据需要重新构建站点。要停止本地 Hugo 实例,请返回终端并键入
Ctrl+C
,或关闭终端窗口。
或者,在您的计算机上安装并使用 hugo
命令
安装Hugo (Extended edition) 和 Node 版本(如
website/netlify.toml
中指定)。安装任何依赖项
npm ci
在终端中,转到您的 Kubernetes 网站存储库并启动 Hugo 服务器
cd <path_to_your_repo>/website make serve
如果您使用的是 Windows 计算机或无法运行
make
命令,请使用以下命令hugo server --buildFuture
在 Web 浏览器中,导航到
https://:1313
。Hugo 会监视更改并根据需要重新构建站点。要停止本地 Hugo 实例,请返回终端并键入
Ctrl+C
,或关闭终端窗口。
从您的 fork 打开 Pull Request 到 kubernetes/website
图 3 展示了从您的 fork 打开 PR 到 kubernetes/website 的步骤。详细信息如下。
请注意,贡献者可以将 kubernetes/website
简称为 k/website
。
head repository 下拉菜单中选择您的 fork] end subgraph second [ ] direction TB 5[5. 从
compare 下拉菜单中选择您的分支] --> 6[6. 选择“创建 Pull Request”] 6 --> 7[7. 添加描述
到您的 PR] 7 --> 8[8. 选择“创建 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. 从您的 fork 到 kubernetes/website 打开 PR 的步骤。
在 Web 浏览器中,转到
kubernetes/website
存储库。选择“新建 Pull Request”。
选择“跨 fork 比较”。
从“head repository”下拉菜单中,选择您的 fork。
从“compare”下拉菜单中,选择您的分支。
选择“创建 Pull Request”。
为您的 Pull Request 添加描述
标题(50 个字符以内):概括更改的意图。
描述:更详细地描述更改。
- 如果存在相关的 GitHub issue,请在描述中包含
Fixes #12345
或Closes #12345
。如果使用,GitHub 的自动化将在合并 PR 后关闭提到的 issue。如果存在其他相关的 PR,也请链接它们。 - 如果您想就特定事项获得建议,请在描述中包含您希望审阅者思考的任何问题。
- 如果存在相关的 GitHub issue,请在描述中包含
选择“创建 Pull Request”按钮。
恭喜!您的 Pull Request 已在Pull requests 中可用。
打开 PR 后,GitHub 会运行自动化测试,并尝试使用Netlify 部署预览。
- 如果 Netlify 构建失败,请选择“Details”以获取更多信息。
- 如果 Netlify 构建成功,选择“Details”将打开一个 Kubernetes 网站的暂存版本,其中应用了您的更改。这是审阅者检查您更改的方式。
GitHub 还会自动为 PR 分配标签,以帮助审阅者。如果需要,您也可以添加它们。有关更多信息,请参阅添加和删除 issue 标签。
在本地处理反馈
进行更改后,修改您之前的提交
git commit -a --amend
-a
:提交所有更改--amend
:修改之前的提交,而不是创建新提交
如有必要,请更新您的提交消息。
使用
git push origin <my_new_branch>
推送您的更改并重新运行 Netlify 测试。
来自审阅者的更改
有时审阅者会提交到您的 Pull Request。在进行任何其他更改之前,请获取这些提交。
从您的远程 fork 获取提交并 rebase 您的工作分支
git fetch origin git rebase origin/<your-branch-name>
rebase 后,强制推送到您的 fork
git push --force-with-lease origin <your-branch-name>
合并冲突和 rebase
如果另一个贡献者在另一个 PR 中提交了对同一文件的更改,则可能会产生合并冲突。您必须解决 PR 中的所有合并冲突。
更新您的 fork 并 rebase 您的本地分支
git fetch origin git rebase origin/<your-branch-name>
然后强制将更改推送到您的 fork
git push --force-with-lease origin <your-branch-name>
从
kubernetes/website
的upstream/main
获取更改并 rebase 您的分支git fetch upstream git rebase upstream/main
检查 rebase 的结果
git status
这将导致许多文件被标记为已冲突。
打开每个冲突文件并查找冲突标记:
>>>
、<<<
和===
。解决冲突并删除冲突标记。注意
有关更多信息,请参阅冲突的呈现方式。将文件添加到更改集
git add <filename>
继续 rebase
git rebase --continue
根据需要重复步骤 2 到 5。
应用所有提交后,
git status
命令会显示 rebase 已完成。将分支强制推送到您的 fork
git push --force-with-lease origin <your-branch-name>
Pull Request 不再显示任何冲突。
压缩提交
如果您的 PR 有多个提交,则必须在合并 PR 之前将它们压缩成一个提交。您可以在 PR 的“Commits”选项卡中检查提交数量,或在本地运行 git log
命令。
注意
本主题假定vim
是命令行文本编辑器。开始交互式 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 完成后该提交的状态。为了 rebase 的目的,请专注于
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 Address feedback 1
和7d54e15ee Address feedback 2
压缩到d875112ca Original commit
中,只留下d875112ca Original commit
作为时间线的一部分。保存并退出文件。
推送您的压缩提交
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 模板。查看一些打开的 issues 和 PRs,以了解该团队的流程。提交 issues 或 PRs 时,请务必尽可能详细地填写模板。
下一步
- 阅读审查以了解有关审查过程的更多信息。