From dbc9257630bf1c466cb7e47d66b68639bf66c585 Mon Sep 17 00:00:00 2001 From: Michael Date: Sun, 15 May 2022 17:06:26 +0800 Subject: [PATCH] [zh] updated two files in content/zh/docs/contribute/ --- content/zh/docs/contribute/_index.md | 189 ++++++++++++++---- .../docs/contribute/review/reviewing-prs.md | 161 ++++++++++----- 2 files changed, 251 insertions(+), 99 deletions(-) diff --git a/content/zh/docs/contribute/_index.md b/content/zh/docs/contribute/_index.md index 90615038e7..6e755efe95 100644 --- a/content/zh/docs/contribute/_index.md +++ b/content/zh/docs/contribute/_index.md @@ -8,7 +8,7 @@ weight: 80 card: name: contribute weight: 10 - title: 开始贡献 + title: 开始为 Kubernetes 做贡献 --- @@ -40,8 +40,9 @@ To learn more about contributing to Kubernetes in general, see the --> {{< note >}} 要了解有关为 Kubernetes 做出贡献的更多信息，请参阅 -[贡献者文档](https://www.kubernetes.dev/docs/). +[贡献者文档](https://www.kubernetes.dev/docs/)。 {{< /note >}} + +本网站由 [Kubernetes SIG（特别兴趣小组）Docs](/zh/docs/contribute/#get-involved-with-SIG-Docs) 维护。 -本网站由 [Kubernetes SIG（特别兴趣小组） Docs](/zh/docs/contribute/#get-involved-with-SIG-Docs) 维护。 - -Kubernetes 文档项目的贡献者: +Kubernetes 文档项目的贡献者： - 改进现有内容 - 创建新内容 - 翻译文档 - 管理并发布 Kubernetes 周期性发行版的文档 -Kubernetes 文档欢迎来自各方贡献者的改进，无论新手还是高手！ - ## 入门 {#getting-started} 任何人都可以提出文档方面的问题（issue），或贡献一个变更，用拉取请求（PR）的方式提交到 [GitHub 上的 `kubernetes/website` 仓库](https://github.com/kubernetes/website)。 当然你需要熟练使用 [git](https://git-scm.com/) 和 [GitHub](https://lab.github.com/) 才能在 Kubernetes 社区中有效工作。 + +如何参与文档编制： +1. 签署 CNCF 的[贡献者许可协议](https://github.com/kubernetes/community/blob/master/CLA.md)。 +2. 熟悉[文档仓库](https://github.com/kubernetes/website)和网站的[静态站点生成器](https://gohugo.io)。 +3. 确保理解[发起 PR](/zh/docs/contribute/new-content/open-a-pr/) 和[审查变更](/zh/docs/contribute/review/reviewing-prs/)的基本流程。 + + + + +{{< mermaid >}} +flowchart TB +subgraph third[发起 PR] +direction TB +U[ ] -.- +Q[改进现有内容] --- N[创建新内容] +N --- O[翻译文档] +O --- P[管理并发布 K8s
周期性发行版的文档] + +end + +subgraph second[评审] +direction TB + T[ ] -.- + D[仔细查看
K8s/website
仓库] --- E[下载安装 Hugo
静态站点
生成器] + E --- F[了解基本的
GitHub 命令] + F --- G[评审待处理的 PR
并遵从变更审查
流程] +end + +subgraph first[注册] + direction TB + S[ ] -.- + B[签署 CNCF
贡献者
许可协议] --- C[加入 sig-docs
Slack 频道] + C --- V[加入 kubernetes-sig-docs
邮件列表] + V --- M[参加每周的
sig-docs 电话会议
或 slack 会议] +end + +A([fa:fa-user 新的
贡献者]) --> first +A --> second +A --> third +A --> H[提出问题!!!] + + +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 spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,B,C,D,E,F,G,H,M,Q,N,O,P,V grey +class S,T,U spacewhite +class first,second,third white +{{}} + + +图 1. 新手入门指示。 + +图 1 概述了新贡献者的路线图。 +你可以遵从`注册`和`评审`所述的某些或全部步骤。 +至此，你完成了发起 PR 的准备工作， +可以通过`发起 PR`列出的事项实现你的贡献目标。 +再次重申，欢迎随时提出问题！ + + -如何参与文档编制: - -1. 签署 CNCF 的[贡献者许可协议](https://github.com/kubernetes/community/blob/master/CLA.md)。 -2. 熟悉[文档仓库](https://github.com/kubernetes/website) - 和网站的[静态站点生成器](https://gohugo.io)。 -3. 确保理解 - [发起 PR](/zh/docs/contribute/new-content/open-a-pr/) 和 - [审查变更](/zh/docs/contribute/review/reviewing-prs/)的基本流程。 - 有些任务要求 Kubernetes 组织内更高的信任级别和访问权限。 阅读[参与 SIG Docs 工作](/zh/docs/contribute/participate/) ，获取角色和权限的更多细节。 - +## 第一次贡献 {#your-first-contribution} + +你可以提前查阅几个步骤，来准备你的第一次贡献。 +图 2 概述了后续的步骤和细节。 + + + + +{{< mermaid >}} +flowchart LR + subgraph second[第一次贡献] + direction TB + S[ ] -.- + G[查阅其他 K8s
成员发起的 PR] --> + A[检索 K8s/website
问题列表是否有
good first 一类的 PR] --> B[发起一个 PR!!] + end + subgraph first[建议的准备工作] + direction TB + T[ ] -.- + D[阅读贡献概述] -->E[阅读 K8s 内容
和风格指南] + E --> F[了解 Hugo 页面
内容类型
和短代码] + 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 +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,B,D,E,F,G grey +class S,T spacewhite +class first,second white +{{}} + + +图 2. 第一次贡献的准备工作。 + + -## 第一次贡献 {#your-first-contribution} - - 通读[贡献概述](/zh/docs/contribute/new-content/overview/)，了解参与贡献的不同方式。 -- 查看[`kubernetes/website` 问题列表](https://github.com/kubernetes/website/issues/) +- 查看 [`kubernetes/website` 问题列表](https://github.com/kubernetes/website/issues/) ，检索最适合作为切入点的问题。 -- 在现有文档上， - [使用 GitHub 提交 PR ](/zh/docs/contribute/new-content/open-a-pr/#changes-using-github)， +- 在现有文档上，[使用 GitHub 提交 PR](/zh/docs/contribute/new-content/open-a-pr/#changes-using-github)， 掌握在 GitHub 上登记 Issue 的方法。 - Kubernetes 社区其他成员会[评审 PR ](/zh/docs/contribute/review/reviewing-prs/)， 以确保文档精准和语言流畅。 @@ -157,11 +248,11 @@ roles and permissions. - 学习在仓库的[本地克隆中工作](/zh/docs/contribute/new-content/open-a-pr/#fork-the-repo)。 - 为[发行版的特性](/zh/docs/contribute/new-content/new-features/)编写文档。 -- 加入 [SIG Docs](/zh/docs/contribute/participate/), 并成为[成员或评审者](/zh/docs/contribute/participate/roles-and-responsibilities/)。 +- 加入 [SIG Docs](/zh/docs/contribute/participate/)，并成为[成员或评审者](/zh/docs/contribute/participate/roles-and-responsibilities/)。 - 开始或帮助[本地化](/zh/docs/contribute/localization/) 工作。 - ## 参与 SIG Docs 工作 {#get-involved-with-SIG-Docs} [SIG Docs](/zh/docs/contribute/participate/) 是负责发布、维护 Kubernetes 文档的贡献者团体。 参与 SIG Docs 是 Kubernetes 贡献者（开发者和其他人员）对 Kubernetes 项目产生重大影响力的好方式。 -SIG Docs 的几种沟通方式: - +SIG Docs 的几种沟通方式： + - [加入 Kubernetes 在 Slack 上的`#sig-docs` 频道](https://slack.k8s.io/)。 一定记得自我介绍! -- [加入`kubernetes-sig-docs` 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs), +- [加入 `kubernetes-sig-docs` 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs), 这里有更广泛的讨论，和官方决策的记录。 -- 参加 [SIG Docs 的每周视频会议](https://github.com/kubernetes/community/tree/master/sig-docs)。会议总是在 `#sig-docs` 上发出公告，同时添加到 - [Kubernetes社区会议日历](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles)。 +- 参加每两周召开一次的 [SIG Docs 视频会议](https://github.com/kubernetes/community/tree/master/sig-docs)。 + 会议总是在 `#sig-docs` 上发出公告，同时添加到 + [Kubernetes 社区会议日历](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles)。 你需要下载 [Zoom 客户端软件](https://zoom.us/download)，或电话拨号接入。 +- 如果有几周未召开实况 Zoom 视频会议，请参加 SIG Docs 异步 Slack 站会。 + 会议总是在 `#sig-docs` 上发出公告。 + 你可以在会议公告后 24 小时内为其中任一议题做贡献。 ## 其他贡献方式 {#other-ways-to-contribute} -- 访问 [Kubernetes 社区网站](/zh/community/)。 参与 Twitter 或 Stack Overflow, 了解 Kubernetes 当地的聚会和活动, 等等。 -- 阅读[贡献者备忘单](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet)，参与 Kubernetes 功能开发。 +- 访问 [Kubernetes 社区网站](/zh/community/)。 + 参与 Twitter 或 Stack Overflow，了解当地的 Kubernetes 会议和活动等等。 +- 阅读[贡献者备忘单](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet)， + 参与 Kubernetes 功能开发。 +- 访问贡献者网站，进一步了解有关 [Kubernetes 贡献者](https://www.kubernetes.dev/) + 和[更多贡献者资源](https://www.kubernetes.dev/resources/)的信息。 - 提交一篇[博客文章或案例研究](/zh/docs/contribute/new-content/blogs-case-studies/)。 diff --git a/content/zh/docs/contribute/review/reviewing-prs.md b/content/zh/docs/contribute/review/reviewing-prs.md index e420fb919a..7710a6dc14 100644 --- a/content/zh/docs/contribute/review/reviewing-prs.md +++ b/content/zh/docs/contribute/review/reviewing-prs.md @@ -1,5 +1,5 @@ --- -title: 评阅 PRs +title: 评审 PR content_type: concept main_menu: true weight: 10 @@ -25,14 +25,14 @@ Before reviewing, it's a good idea to: [style guide](/docs/contribute/style/style-guide/) so you can leave informed comments. - Understand the different [roles and responsibilities](/docs/contribute/participating/#roles-and-responsibilities) in the Kubernetes documentation community. --> -任何人均可评阅文档的拉取请求。访问 Kubernetes 网站仓库的 -[pull requests](https://github.com/kubernetes/website/pulls) -部分可以查看所有待处理的拉取请求（PRs）。 +任何人均可评审文档的拉取请求。 +访问 Kubernetes 网站仓库的 [pull requests](https://github.com/kubernetes/website/pulls) 部分， +可以查看所有待处理的拉取请求（PR）。 -评阅文档 PR 是将你自己介绍给 Kubernetes 社区的一种很好的方式。 +评审文档 PR 是将你自己介绍给 Kubernetes 社区的一种很好的方式。 它将有助于你学习代码库并与其他贡献者之间建立相互信任关系。 -在评阅之前，可以考虑： +在评审之前，可以考虑： - 阅读[内容指南](/zh/docs/contribute/style/content-guide/)和 [样式指南](/zh/docs/contribute/style/style-guide/)以便给出有价值的评论。 @@ -53,21 +53,62 @@ Before you start a review: --> ## 准备工作 {#before-you-begin} -在你开始评阅之前： +在你开始评审之前： -- 阅读 [CNCF 行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) - 确保你会始终遵从其中约定； -- 保持有礼貌、体谅他人，怀助人为乐初心； -- 评论时若给出修改建议，也要兼顾 PR 的积极方面 -- 保持同理心，多考虑他人收到评阅意见时的可能反应 -- 假定大家都是好意的，通过问问题澄清意图 -- 如果你是有经验的贡献者，请考虑和新贡献者一起合作，提高其产出质量 +- 阅读 [CNCF 行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)。 + 确保你会始终遵从其中约定。 +- 保持有礼貌、体谅他人，怀助人为乐初心。 +- 评论时若给出修改建议，也要兼顾 PR 的积极方面。 +- 保持同理心，多考虑他人收到评审意见时的可能反应。 +- 假定大家都是好意的，通过问问题澄清意图。 +- 如果你是有经验的贡献者，请考虑和新贡献者一起合作，提高其产出质量。 - +## 评审过程 {#review-process} +一般而言，应该使用英语来评审 PR 的内容和样式。 +图 1 概述了评审流程的各个步骤。 +每个步骤的详细信息如下。 + + + + +{{< mermaid >}} +flowchart LR + subgraph fourth[开始评审] + direction TB + S[ ] -.- + M[添加评论] --> N[评审变更] + N --> O[新手应该
选择 Comment] + end + subgraph third[选择 PR] + direction TB + T[ ] -.- + J[阅读描述
和评论]--> K[通过 Netlify 预览构建
来预览变更] + end + + A[查阅待处理的 PR 清单]--> B[通过标签过滤
待处理的 PR] + B --> third --> fourth + + +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 spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,B,J,K,M,N,O grey +class S,T spacewhite +class third,fourth white +{{}} + + +图 1. 评审流程步骤。 + + -## 评阅过程 {#review-process} - -一般而言，应该使用英语来评阅 PR 的内容和样式。 - 1. 前往 [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls)， - 你会看到所有针对 Kubernetes 网站和文档的待处理 PRs。 + 你会看到所有针对 Kubernetes 网站和文档的待处理 PR。 -2. 使用以下标签（组合）对待处理 PRs 进行过滤： +2. 使用以下标签（组合）对待处理 PR 进行过滤： - - `cncf-cla: yes` （建议）：由尚未签署 CLA 的贡献者所发起的 PRs 不可以合并。 + - `cncf-cla: yes` （建议）：由尚未签署 CLA 的贡献者所发起的 PR 不可以合并。 参考[签署 CLA](/zh/docs/contribute/new-content/overview/#sign-the-cla) 以了解更多信息。 - - `language/en` （建议）：仅查看英语语言的 PRs。 - - `size/<尺寸>`：过滤特定尺寸（规模）的 PRs。如果你刚入门，可以从较小的 PR 开始。 + - `language/en` （建议）：仅查看英语语言的 PR。 + - `size/<尺寸>`：过滤特定尺寸（规模）的 PR。 + 如果你刚入门，可以从较小的 PR 开始。 此外，确保 PR 没有标记为尚未完成（Work in Progress）。 - 包含 `work in progress` 的 PRs 通常还没准备好被评阅。 + 包含 `work in progress` 的 PR 通常还没准备好被评审。 - +3. 选定 PR 评审之后，可以通过以下方式理解所作的变更： + - 阅读 PR 描述以理解所作变更，并且阅读所有关联的 Issues。 + - 阅读其他评审人给出的评论。 + - 点击 **Files changed** Tab 页面，查看被改变的文件和代码行。 + - 滚动到 **Conversation** Tab 页面下端的 PR 构建检查节区， + 预览 Netlify 预览构建中的变更。 + 以下是一个屏幕截图（这显示了 GitHub 的桌面版外观； + 如果你在平板电脑或智能手机设备上进行评审， + GitHub 的 Web UI 会略有不同）： + {{< figure src="/images/docs/github_netlify_deploy_preview.png" alt="GitHub PR 详细信息，包括 Netlify 预览链接" >}} + 要打开预览，请点击 **deploy/netlify** 行的 **Details** 链接。 + + -3. 选定 PR 评阅之后，可以通过以下方式理解所作的变更： +4. 前往 **Files changed** Tab 页面，开始你的评审工作。 - - 阅读 PR 描述以理解所作变更，并且阅读所有关联的 Issues - - 阅读其他评阅人给出的评论 - - 点击 **Files changed** Tab 页面，查看被改变的文件和代码行 - - 滚动到 **Conversation** Tab 页面下端的 PR 构建检查节区，点击 - **deploy/netlify** 行的 **Details** 链接，预览 Netlify - 预览构建所生成的结果 - -4. 前往 **Files changed** Tab 页面，开始你的评阅工作 - - 1. 点击你希望评论的行旁边的 `+` 号 - 2. 填写你对该行的评论，之后或者选择**Add single comment** （如果你只有一条评论） - 或者 **Start a review** （如果你还有其他评论要添加） - 3. 评论结束时，点击页面顶部的 **Review changes**。这里你可以添加你的评论结语 - （记得留下一些正能量的评论！）、根据需要批准 PR、请求作者进一步修改等等。 + 1. 点击你希望评论的行旁边的 `+` 号。 + 2. 填写你对该行的评论， + 之后选择 **Add single comment**（如果你只有一条评论） + 或者 **Start a review**（如果你还有其他评论要添加）。 + 3. 评论结束时，点击页面顶部的 **Review changes**。 + 这里你可以添加你的评论结语（记得留下一些正能量的评论！）、 + 根据需要批准 PR、请求作者进一步修改等等。 新手应该选择 **Comment**。 - +## 评审清单 {#reviewing-checklist} +评审 PR 时可以从下面的条目入手。 + + -## 评阅清单 {#reviewing-checklist} - -评阅 PR 时可以从下面的条目入手。 - ### 语言和语法 {#language-and-grammar} - 是否存在明显的语言或语法错误？对某事的描述有更好的方式？ @@ -177,10 +227,6 @@ When reviewing, use the following as a starting point. - Does the page appear correctly in the section's side navigation (or at all)? - Should the page appear on the [Docs Home](/docs/home/) listing? - Do the changes show up in the Netlify preview? Be particularly vigilant about lists, code blocks, tables, notes and images. - -### Other - -For small issues with a PR, like typos or whitespace, prefix your comments with `nit:`. This lets the author know the issue is non-critical. --> ### 网站 {#Website} @@ -193,10 +239,15 @@ For small issues with a PR, like typos or whitespace, prefix your comments with - 该页面能否在对应章节的侧面导航中显示？显示得正确么？ - 该页面是否应出现在[网站主页面](/zh/docs/home/)的列表中？ - 变更是否正确出现在 Netlify 预览中了？ - 要对列表、代码段、表格、注释和图像等元素格外留心 + 要对列表、代码段、表格、注释和图像等元素格外留心。 + ### 其他 {#other} -对于 PR 中的小问题，例如拼写错误或者空格问题，可以在你的评论前面加上 `nit:`。 +对于 PR 中的小问题，例如拼写错误或者空格问题， +可以在你的评论前面加上 `nit:`。 这样做可以让作者知道该问题不是一个不得了的大问题。 -