diff --git a/content/zh/docs/contribute/_index.md b/content/zh/docs/contribute/_index.md index d826160593..0acea1e84a 100644 --- a/content/zh/docs/contribute/_index.md +++ b/content/zh/docs/contribute/_index.md @@ -1,191 +1,9 @@ --- -content_type: concept -title: 为 Kubernetes 文档做贡献 -linktitle: 贡献 -main_menu: true -weight: 80 +title: 贡献新内容 +weight: 20 --- - - - - - -如果你想帮助对 Kubernetes 文档或网站做出贡献，我们很高兴得到你的帮助！ -任何人都可以做出贡献，无论你刚参与项目还是参与了很长时间，无论你是开发人员还是用户，或是无法忍受看到拼写错误的人。 - - - -更多途径参与 Kubernetes 社区或了解我们，请访问 [Kubernetes 社区网站](/community/)。 - - - -查找 [样式指南](/docs/contribute/style/style-guide/) 或者 [Kubernetes 社区网站](/community/)？ - - - - - - - -## 贡献者类型 - - - -- [签署了 CLA](/docs/contribute/start#sign-the-cla)并为项目贡献了时间和精力的 Kubernetes 组织的_成员_。 - 参见 [社区成员](https://github.com/kubernetes/community/blob/master/community-membership.md) 中对于成员资格的具体标准。 - - - -- SIG Docs 的_评审者_是对评审文档 PR 感兴趣，并被 SIG Docs 审批者添加到 Github 群组并在 Github 仓库中 `OWNERS` 文件的 Kubernetes 组织的成员。 - - - -- SIG Docs 的_审批者_是对项目持续贡献，并被授予合并 PR 权限和代表 Kubernetes 组织发布内容的成员。 - 批准人也可以在更广泛的 Kubernetes 社区中代表 SIG Docs 团队。 - SIG Docs审批者的一些职责，如协调发布版本，需要大量的时间投入。 - - - -## 贡献途径 - - - -以下列表将工作分成了：任何人都可以做的工作、Kubernetes 组织成员可以做的工作，和熟悉 SIG Docs 流程并且有更高访问权限才能做的工作。 -持续的贡献可以帮助你理解已有的工具和组织决策。 - - - -你对 Kubernetes 文档可以做出的贡献不仅限于列表列出的条目，但它可以帮助你开动起来。 - - - -- [任何人](/docs/contribute/start/) - - 登记记录可修正的错误 - - - -- [成员](/docs/contribute/start/) - - 完善已有文档 - - 在 Slack 或 SIG Docs 邮件列表中提出改进意见 - - 提升文档的易用性 - - 对 PR 提出无约束的反馈 - - 编写博文和案例分析 - - - -- [评审者](/docs/contribute/intermediate/) - - 为新功能特性编写文档 - - 对 issue 进行筛选和分类 - - 评审 PR - - 创建图表、图形分析和嵌入式的屏幕/视频 - - 本地化 - - 作为 docs 小组的代表为其他项目仓库做贡献 - - 在代码中编辑面向用户的字符串 - - 改进代码注释和 Godoc - - - -- [审批者](/docs/contribute/advanced/) - - 通过批准和合并 PR 发布贡献成果 - - 作为 docs 团队的代表参与 Kubernetes 发布团队 - - 对样式指南提出改进建议 - - 对文档测试提出改进建议 - - 对 Kubernetes 网站或其他工具提出改进建议 - - - -## 其他贡献途径 - - - -- 如果您要通过 Twitter 或 Stack Overflow 等在线论坛为社区做贡献，或了解本地会议及 Kubernetes 事件，请查看 [Kubernetes 社区网站](/community/). - - - -- 如果您要开发新的特性，请阅读 [contributor cheatsheet](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet). - - diff --git a/content/zh/docs/contribute/advanced.md b/content/zh/docs/contribute/advanced.md index a01c6c632d..771f75b98b 100644 --- a/content/zh/docs/contribute/advanced.md +++ b/content/zh/docs/contribute/advanced.md @@ -2,29 +2,28 @@ title: 高级贡献 slug: advanced content_type: concept -weight: 30 +weight: 98 --- -如果你已经阅读并掌握[开始贡献](/docs/contribute/start/)和[中级贡献](/docs/contribute/intermediate/)，并准备了解更多贡献的途径，请阅读此文。您需要使用 Git 命令行工具和其他工具做这些工作。 - +如果你已经了解如何[贡献新内容](/zh/docs/contribute/new-content/overview/)和 +[评阅他人工作](/zh/docs/contribute/review/reviewing-prs/)，并准备了解更多贡献的途径， +请阅读此文。您需要使用 Git 命令行工具和其他工具做这些工作。 @@ -34,13 +33,13 @@ client and other tools for some of these tasks. ## 做一周的 PR 管理者 -SIG Docs 的 [approvers](/docs/contribute/participating/#approvers) 可以成为 PR 管理者。SIG Docs approvers 会每周轮换地加入到 [PR 管理者轮换日程](https://github.com/kubernetes/website/wiki/PR-Wranglers#2019-schedule-q1q2)中。 +SIG Docs [approvers](/docs/contribute/participating/#approvers) take week-long turns [wrangling PRs](https://github.com/kubernetes/website/wiki/PR-Wranglers) for the repository. - +SIG Docs 的[批准人（Approvers）](/zh/docs/contribute/participating/#approvers)们每周轮流负责 +[管理仓库的 PRs](https://github.com/kubernetes/website/wiki/PR-Wranglers)。 + PR 管理者的工作职责包括： -- 每天检查[悬决的 PR](https://github.com/kubernetes/website/pulls) 的质量并确保它们遵守[风格指南]](/docs/contribute/style/style-guide/)。 +- 每天检查[悬决的 PR](https://github.com/kubernetes/website/pulls) 的质量并确保它们遵守[样式指南](/zh/docs/contribute/style/style-guide/)和[内容指南](/zh/docs/contribute/style/content-guide/)。 - 首先查看最小的 PR（`size/XS`），然后逐渐扩展到最大的 PR（`size/XXL`）。 - 尽可能多地审阅 PR。 - 确保每个贡献者完成 CLA 签署。 @@ -78,7 +77,8 @@ PR 管理者的工作职责包括： - 为已审阅的但在合并前需要更多信息的或采取措施的 PR 设置 `Doc Review: Open Issues` 或者 `Tech Review: Open Issues` 标签。 - 为可以合并的 PR 添加 `/lgtm` 和 `/approve` 标签。 - 合并已经就绪的，或关闭不应该接受的 PR。 -- 每天对新增的 issues 进行分类和标记。有关 SIG 文档如何使用 metadata 的准则，请参见[中级贡献](/docs/contribute/intermediate/)。 +- 每天对新增的 Issue 报告进行分类和判别。有关 SIG 文档如何使用 metadata 的准则，请参见 + [对 Issue 进行分类](/zh/docs/contribute/review/for-approvers/#triage-and-categorize-issues)。 -### 对于负责人有用的 GitHub 查询 +### 对于管理人有用的 GitHub 查询 执行管理操作时，以下查询很有用。完成以下三个查询后，剩余的要审阅的 PR 列表通常很小。 +这些查询都排除了本地化的 PR，并仅包含 `master` 分支上的 PR（除了最后一个查询）。 -- [没有签署 CLA, 不能 merge](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+no%22+-label%3Ado-not-merge+label%3Alanguage%2Fen): +- [没有签署 CLA, 不能合并](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+no%22+-label%3Ado-not-merge+label%3Alanguage%2Fen): 提醒贡献者签署 CLA。如果机器人和审阅者都已经提醒他们，请关闭 PR，并提醒他们在签署 CLA 后可以重新提交。 **在作者没有签署 CLA 之前，不要审阅他们的 PR！** - [需要 LGTM](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Aopen+is%3Apr+-label%3Ado-not-merge+label%3Alanguage%2Fen+-label%3Algtm+): 如果需要技术审查，请告知机器人所建议的审阅者。如果 PR 需要文档审查或复制编辑，提交更改建议或向 PR 提交一个 copyedit 以使之进入下一步。 - [有 LGTM ，需要批准](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+-label%3Ado-not-merge+label%3Alanguage%2Fen+label%3Algtm): 确定 PR 是否需要进行其他更改或更新才能合并。如果您认为 PR 已准备好合并，请输入 `/approve`。 +- [快速批阅](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+base%3Amaster+-label%3A%22do-not-merge%2Fwork-in-progress%22+-label%3A%22do-not-merge%2Fhold%22+label%3A%22cncf-cla%3A+yes%22+label%3A%22size%2FXS%22+label%3A%22language%2Fen%22+)：对于针对 master 分支的小规模 PR，可以快速审阅。 + 在浏览 PR 时，可以注意到 size 标签为 "XS" 的 PRs。 - [非 master 分支的 PR](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Aopen+is%3Apr+-label%3Ado-not-merge+label%3Alanguage%2Fen+-base%3Amaster)： 如果 PR 针对 `dev-` 分支，则表示它适用于即将发布的版本。请添加带有 `/assign @<负责人的 github 账号>` 的注释，确保[发行版本负责人](https://github.com/kubernetes/sig-release/tree/master/release-team)注意到该 PR。如果 PR 是针对旧分支，请帮助 PR 作者确定是否所针对的是最合适的分支。 @@ -132,7 +135,7 @@ Don't be afraid to close pull requests. Contributors can easily reopen and resum To close a pull request, leave a `/close` comment on the PR. --> - 关闭两个星期未签署 CLA 的 PR。 -PR 作者可以在签署 CLA 后重新打开 PR，因此这是确保未签署 CLA 的 PR 不会被合并的一种风险较低的方法。 + PR 作者可以在签署 CLA 后重新打开 PR，因此这是确保未签署 CLA 的 PR 不会被合并的一种风险较低的方法。 - 如果作者在两周或更长时间内未回复评论或反馈，请关闭 PR。 @@ -140,28 +143,29 @@ PR 作者可以在签署 CLA 后重新打开 PR，因此这是确保未签署 CL 要关闭 PR，请在 PR 上输入 `/close`。 -{{< note >}} - -一项名为 [`fejta-bot`](https://github.com/fejta-bot) 的自动服务会在 issues 停滞 90 天后会自动将其标记为过期；然后再等 30 天，如果仍然无人过问，则将其关闭。PR 管理者应该在 issues 处于无人过问状态 14-30 天后关闭它们。 +{{< note >}} +一项名为 [`fejta-bot`](https://github.com/fejta-bot) 的自动服务会在 Issue 停滞 90 +天后自动将其标记为过期；然后再等 30 天，如果仍然无人过问，则将其关闭。 +PR 管理者应该在 issues 处于无人过问状态 14-30 天后关闭它们。 {{< /note >}} ## 提出改进建议 -SIG Docs 的 [成员](/docs/contribute/participating/#members) 可以提出改进建议。 +SIG Docs 的 [成员](/zh/docs/contribute/participating/#members) 可以提出改进建议。 -在对 Kubernetes 文档贡献了一段时间后，你可能会对样式指南、用于构建文档的工具链、网页样式、评审和合入 PR 的流程，或者文档的其他方面产生改进的想法。为了尽可能透明化，这些提议都需要在 SIG Docs 会议或 [kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)上讨论。此外，在提出全面的改进之前，它能真正帮助我们了解有关“当前工作如何运作”和“以往的决定是为何做出”的背景。想了解文档的当前运作方式，最快的途径是咨询 [kubernetes.slack.com](https://kubernetes.slack.com) 中的 `#sig-docs` 聊天群组。 +在对 Kubernetes 文档贡献了一段时间后，你可能会对[样式指南](/zh/docs/contribute/style/style-guide/)、 +[内容指南](/zh/docs/contribute/style/content-guide/)、用于构建文档的工具链、网站样式、 +评审和合并 PR 的流程或者文档的其他方面产生改进的想法。 +为了尽可能透明化，这些提议都需要在 SIG Docs 会议或 +[kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)上讨论。 +此外，在提出全面的改进之前，这些讨论能真正帮助我们了解有关“当前工作如何运作”和“以往的决定是为何做出”的背景。 +想了解文档的当前运作方式，最快的途径是咨询 [kubernetes.slack.com](https://kubernetes.slack.com) +中的 `#sig-docs` 聊天群组。 -## 为 Kubernetes 版本发布协调文档 - -SIG Docs 的[批准者（approvers）](/docs/contribute/participating/#approvers) 可以为 Kubernetes 版本发布协调文档。 +## 为 Kubernetes 版本发布协调文档工作 + +SIG Docs 的[批准者（approvers）](/zh/docs/contribute/participating/#approvers) 可以为 +Kubernetes 版本发布协调文档工作。 -每一个 Kubernetes 版本都是由参与 sig-release 的 SIG（特别兴趣小组）的一个团队协调的。指定版本的发布团队中还包括总体发布牵头人，以及来自 sig-pm、sig-testing 的代表等。了解更多关于 Kubernetes 版本发布的流程，请参考 [https://github.com/kubernetes/sig-release](https://github.com/kubernetes/sig-release)。 +每一个 Kubernetes 版本都是由参与 sig-release 的 SIG（特别兴趣小组）的一个团队协调的。 +指定版本的发布团队中还包括总体发布牵头人，以及来自 sig-pm、sig-testing 的代表等。 +要了解更多关于 Kubernetes 版本发布的流程，请参考 +[https://github.com/kubernetes/sig-release](https://github.com/kubernetes/sig-release)。 -SIG Docs 团队的代表需要为一个指定的版本协调以下工作： - -- 通过特性跟踪表来监视新功能特性或现有功能特性的修改。如果版本的某个功能特性的文档没有为发布做好准备，那么该功能特性不允许进入发布版本。 + +SIG Docs 团队的代表需要为一个指定的版本协调以下工作： + +- 通过特性跟踪表来监视新功能特性或现有功能特性的修改。 + 如果版本的某个功能特性的文档没有为发布做好准备，那么该功能特性不允许进入发布版本。 - 定期参加 sig-release 会议并汇报文档的发布状态。 - 评审和修改由负责实现某功能特性的 SIG 起草的功能特性文档。 - 合入版本发布相关的 PR，并为对应发布版本维护 Git 特性分支。 @@ -235,14 +250,11 @@ SIG Docs 团队的代表需要为一个指定的版本协调以下工作： Coordinating a release is typically a 3-4 month commitment, and the duty is rotated among SIG Docs approvers. --> -协调一个版本发布通常需要 3-4 个月的时间投入，该任务由 SIG Docs approvers 轮流承担。 +协调一个版本发布通常需要 3-4 个月的时间投入，该任务由 SIG Docs 批准人轮流承担。 -## 担任新的贡献者大使 - -SIG Docs [approvers](/docs/contribute/participating/#approvers) 可以担任新的贡献者大使。 -新的贡献者大使共同努力欢迎 SIG-Docs 的新贡献者，对新贡献者的 PR 提出建议，以及在前几份 PR 提交中指导新贡献者。 +## 担任新的贡献者大使 + +SIG Docs [批准人（Approvers）](/zh/docs/contribute/participating/#approvers) +可以担任新的贡献者大使。 + +新的贡献者大使共同努力欢迎 SIG-Docs 的新贡献者，对新贡献者的 PR 提出建议， +以及在前几份 PR 提交中指导新贡献者。 新的贡献者大使的职责包括： @@ -265,11 +282,11 @@ SIG Docs [approvers](/docs/contribute/participating/#approvers) 可以担任新 - Helping new contributors create the more complex PRs they need to become Kubernetes members. - [Sponsoring contributors](/docs/contribute/advanced/#sponsor-a-new-contributor) on their path to becoming Kubernetes members. --> -- 可在 [Kubernetes #sig-docs 频道](https://kubernetes.slack.com) 上回答新贡献者的问题。 +- 监听 [Kubernetes #sig-docs 频道](https://kubernetes.slack.com) 上新贡献者的 Issue。 - 与 PR 管理者合作为新参与者寻找合适的第一个 issues。 -- 通过前几个 PR 指导新贡献者到文档存储库。 +- 通过前几个 PR 指导新贡献者为文档存储库作贡献。 - 帮助新的贡献者创建成为 Kubernetes 成员所需的更复杂的 PR。 -- [为贡献者提供担保](/docs/contribute/advanced/#sponsor-a-new-contributor)，使其成为 Kubernetes 成员。 +- [为贡献者提供保荐](#sponsor-a-new-contributor)，使其成为 Kubernetes 成员。 -## 为新的贡献者提供担保 - -SIG Docs 的 [reviewers](/docs/contribute/participating/#reviewers) 可以为新的贡献者提供担保。 +## 为新的贡献者提供保荐 {#sponsor-a-new-contributor} + +SIG Docs 的[评审人（Reviewers）](/zh/docs/contribute/participating/#reviewers) 可以为新的贡献者提供保荐。 -新的贡献者针对一个或多个 Kubernetes 项目仓库成功提交了 5 个实质性 PR 之后，就有资格申请 Kubernetes 组织 [成员身份](/docs/contribute/participating#members)。贡献者的成员资格需要同时得到两位 reviewers 的保荐。 +新的贡献者针对一个或多个 Kubernetes 项目仓库成功提交了 5 个实质性 PR 之后， +就有资格申请 Kubernetes 组织的[成员身份](/zh/docs/contribute/participating#members)。 +贡献者的成员资格需要同时得到两位评审人的保荐。 -新的文档贡献者可以通过咨询 [Kubernetes Slack 实例](https://kubernetes.slack.com) 上的 #sig-docs 频道或者 [SIG Docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)来请求评审者保荐。如果你对申请人的工作充满信心，你自愿保荐他们。当他们提交成员资格申请时，回复 “+1” 并详细说明为什么你认为申请人适合加入 Kubernetes 组织。 +新的文档贡献者可以通过咨询 [Kubernetes Slack 实例](https://kubernetes.slack.com) +上的 #sig-docs 频道或者 [SIG Docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) +来请求评审者保荐。如果你对申请人的工作充满信心，你自愿保荐他们。 +当他们提交成员资格申请时，回复 “+1” 并详细说明为什么你认为申请人适合加入 Kubernetes 组织。 ## 担任 SIG 联合主席 -SIG Docs [approvers](/docs/contribute/participating/#approvers) 可以担任 SIG Docs 的联合主席。 +SIG Docs [批准人（Approvers）](/zh/docs/contribute/participating/#approvers) +可以担任 SIG Docs 的联合主席。 ### 前提条件 @@ -332,9 +354,14 @@ Approvers must meet the following requirements to be a co-chair: Approvers 必须满足以下要求才能成为联合主席： - 已维持 SIG Docs approver 身份至少 6 个月 -- [曾领导 Kubernetes 文档发布](/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) 或者在两个版本发布中有实习经历 +- [曾领导 Kubernetes 文档发布](/zh/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) + 或者在两个版本发布中有实习经历 - 理解 SIG Docs 工作流程和工具：git、Hugo、本地化、博客子项目 -- 理解其他 Kubernetes SIG 和仓库会如何影响 SIG Docs 工作流程，包括：[k/org 中的团队](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml)、[k/community 中的流程](https://github.com/kubernetes/community/tree/master/sig-docs)、[k/test-infra](https://github.com/kubernetes/test-infra/) 中的插件、[SIG Architecture](https://github.com/kubernetes/community/tree/master/sig-architecture) 中的角色。 +- 理解其他 Kubernetes SIG 和仓库会如何影响 SIG Docs 工作流程，包括： + [k/org 中的团队](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml)、 + [k/community 中的流程](https://github.com/kubernetes/community/tree/master/sig-docs)、 + [k/test-infra](https://github.com/kubernetes/test-infra/) 中的插件、 + [SIG Architecture](https://github.com/kubernetes/community/tree/master/sig-architecture) 中的角色。 - 在至少 6 个月的时段内，确保每周至少投入 5 个小时（通常更多） - 保持 SIG Docs 专注于通过出色的文档最大限度地提高开发人员的满意度 -- 以身作则，践行[社区行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) 并要求 SIG 成员对自身行为负责 -- 通过更新贡献准则，为 SIG 学习并设置最佳实践 +- 以身作则，践行[社区行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)， + 并要求 SIG 成员对自身行为负责 +- 通过更新贡献指南，为 SIG 学习并设置最佳实践 - 安排和举行 SIG 会议：每周状态更新，每季度回顾/计划会议以及其他需要的会议 - 在 KubeCon 活动和其他会议上安排和负责文档工作 -- 与 {{< glossary_tooltip text="CNCF" term_id="cncf" >}} 及其尊贵合作伙伴（包括 Google、Oracle、Azure、IBM 和华为）一起以 SIG Docs 的身份招募和宣传 +- 与 {{< glossary_tooltip text="CNCF" term_id="cncf" >}} 及其尊贵合作伙伴 + （包括 Google、Oracle、Azure、IBM 和华为）一起以 SIG Docs 的身份招募和宣传 - 负责 SIG 正常运行 ### 召开高效的会议 -为了安排和召开高效的会议，这些准则说明了如何做、怎样做以及原因。 +为了安排和召开高效的会议，这些指南说明了如何做、怎样做以及原因。 **坚持[社区行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)**： @@ -470,4 +499,3 @@ The video uploads automatically to YouTube. 视频会自动上传到 YouTube。 - diff --git a/content/zh/docs/contribute/intermediate.md b/content/zh/docs/contribute/intermediate.md deleted file mode 100644 index 93cba0dc71..0000000000 --- a/content/zh/docs/contribute/intermediate.md +++ /dev/null @@ -1,1453 +0,0 @@ ---- -title: 中级贡献 -slug: intermediate -content_type: concept -weight: 20 -card: - name: contribute - weight: 50 ---- - - - - - -本文假定你已经阅读并掌握了[开始贡献](/docs/contribute/start/)中介绍的内容，想要了解更多关于贡献的内容。 - - -{{< note >}} - -有些任务需要使用 Git 命令行客户端和其他工具。 -{{< /note >}} - - - - - - -现在，您已经熟悉了 Kubernetes 文档，并按照[开始贡献](/docs/contribute/start/)文章中介绍的方式进行了贡献，您可能已经准备好做更多的工作。这些任务假设您已经或愿意获得以下主题领域的更深入的知识: - - -- Kubernetes 概念 -- Kubernetes 文档工作流程 -- 在哪里和如何找到即将推出的 Kubernetes 功能的信息 -- 较强的研究能力 - - -这些任务不像初学者的任务那样是顺序的。没有人期望一个人会一直做所有的事情。 - -## 评审 pull request - - -通常，每周都会有一个特定的文档审核志愿者对 [pull requests 和 issues](#triage-and-categorize-issues) 进行分类和审核。这个人就是本周的 “PR 轮流负责人”。排班计划在 [PR 轮流负责人排班](https://github.com/kubernetes/website/wiki/PR-Wranglers) 中维护。 -如果想要加入排班计划，需要参加每周的 SIG Docs 会议并志愿申请。 -尽管你不在本周的排班计划中，你也可以审核那些还未开始检视的 PR。 - - -除了轮换之外，自动化系统（机器人）会根据修改的文件自动推荐相应的 approver 和 reviewer。 -PR 作者应该遵循机器人的指导，这也有助于 PR 得到快速审查。 - - -我们希望尽快合并和发布 pull requests。 -为了确保文档是准确的和最新的，每个 PR 都需要由理解内容的人以及具有编写优秀文档经验的人来评审。 - - -评审人员和批准人员需要提供可操作的和建设性的反馈，以保持贡献者的参与并帮助他们改进。 -有时候，帮助一个新的贡献者把他们的 PR 准备好合并比你自己重写它需要更多的时间， -但是从长远来看，当我们有不同的积极参与者时，这个项目会更好。 - - -在开始评审 PR 之前，请确保熟悉[文档内容指南](/docs/contribute/style/content-guide/)、[文档风格指南](/docs/contribute/style/style-guide/)、[行为准则](/community/code-of-conduct/)。 - - -### 找一个 PR 来评审 - - -要查看所有打开的 PR，请转到 GitHub 仓库中的**Pull Requests**选项卡。 -当符合以下所有条件时，PR 才有资格进行评审： - - -- 拥有 `cncf-cla:yes` 标签 -- 描述中没有 WIP -- 没有包含 `do-not-merge` 字样的标签 -- 没有合并冲突 -- 基于正确的分支(通常为 “master”，除非 PR 与某个未发布的功能相关) -- 没有被其他文档人员（或其他技术领域的评审人）评审，除非你被显式的请求参与评审。 - 需要说明的是，如果其他评审已经结束的情况下，你再留下很多新的意见，会让人感到沮丧，这适得其反。 - - -如果 PR 不符合合并的条件，请留下评论，让作者知道问题所在，并帮助他们解决问题。 -如果他们被告知并在几周或几个月内没有解决问题，最终他们的 PR 将被关闭而不会合并。 - - -如果您是新手，或者您没有太多的带宽，请寻找具有 `size/XS` 或 `size/S` 标记集的 PR。 -大小由 PR 更改的行数自动设置。 - -#### Reviewers and approvers - - -Kubernetes 网站仓库与 Kubernetes 的一些代码仓库在涉及审核者和审批者角色时的操作方式不同。 -有关评审人员和批准人员职责的更多信息，请参见[参与](/docs/contribute/participating/)。 -这里只做一个概述。 - - -- 当评审人员以评审 PR 的技术准确性时，评审人员发表一个 `/lgtm` 评论表示技术上是无误的。 - - {{< note >}}如果你对技术准确性不确信，不要在涉及文档修改的 PR 中回复 `/lgtm`。 {{< /note >}} - -- 批准者审核有关文档修改的内容时，注重质量和相关规范（比如[风格规范](/docs/contribute/style/style-guide)）。 - 只有在 [`OWNERS`](https://github.com/kubernetes/website/blob/master/OWNERS) 文件中列出的 - 人才可以批准 PR。批准 PR 时，需要回复一个 `/approve` 评论。 - - -如果 PR 拥有来自 Kubernetes 社区的任何人的 `/lgtm` 评论和来自 `sig-docs-maintainers` 组的 `/approve` 评论，只要它没有被 hold 并且作者已签署了 CLA，PR 就会被合并。 - - - -{{< note >}} -["参与"](/docs/contribute/participating/#approvers)部分包含有关 reviewers 和 approvers 的更多信息，包括 approvers 的具体职责。 -{{< /note >}} - - -### 审核 PR - - - - -1. 阅读 PR 描述，并阅读任何附加的 issues 或链接，如果有的话。 - “快速评审”有时弊大于利，所以确保你有正确的知识来提供有意义的评审。 - -2. 如果其他人是审核这个 PR 的最佳人选，请通过添加 `/assign @` 的评论让他们知道。 - 如果你要求一个非文档人员进行技术评审，但仍然想从文档的角度来评审 PR，那就继续吧。 - -3. 转到 **Files changed** 选项卡。查看所有的修改行。删除的内容具有红色背景，这些行也以 `-` 符号开头。 - 添加的内容具有绿色背景，这些行也以 `+` 符号开始。在一行中，实际修改的内容的背景颜色比该行的其余部分略深一些。 - - - 特别是如果 PR 使用复杂的格式或更改 CSS、Javascript 或其他站点范围内的元素，您可以使用 PR 预览网站。 - 转到 **Conversation** 选项卡，单击页面底部附近的 `deploy/netlify` 测试的 **Details** 链接。 - 默认情况下，它会在同一个浏览器窗口中打开，所以在一个新窗口中打开它，这样你就不会丢失你的部分评论。 - 切换回 **Files changed** 选项卡以继续您的审阅。 - - 确保 PR 符合文档[风格指南](/docs/contribute/style/style-guide/)， - 如果不符合，请将作者链接到风格指南的相关部分。 - - 如果您对给定的更改有疑问、评论或其他反馈，请将鼠标悬停在一行上，然后单击出现的蓝白相间的 `+` 号。 - 键入您的评论并单击 **Start a review**。 - - - 如果你有更多的评论，请以同样的方式留下评论。 - - 按照惯例，如果您看到一个与 PR 的主要目的无关的小问题，比如一个打印错误或空格错误， - 您可以将它指出来，并在注释前加上 nit: 以便作者知道您认为它是无关紧要的。 - 他们仍然应该解决这个问题。 - - 当您查看完所有内容，或者没有任何评论时，回到页面顶部并单击 **Review changes**。 - 选择**Comment** 或**Request Changes**。添加评审摘要， - 并在评审摘要字段中另起一行添加适当的 [Prow 命令](https://prow.k8s.io/command-help)。 - SIG Docs 遵循 [Kubernetes 代码审查流程](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process)。 - 您所有的意见将在一个单一的评论中发送给 PR 作者。 - - - 如果您认为 PR 已经准备好合并，请将文本 `/approve` 添加到摘要中。 - - 如果 PR 不需要额外的技术审查，也可以同时添加文本 `/lgtm` 。 - - 如果 PR *确实* 需要额外的技术审查，使用 `/assign` + GitHub 用户名添加需要提供技术审查的人。 - 查看上面出现的 Markdown 文件中的`reviewers`字段，看看谁可以提供技术审阅。 - - 如果需要阻止 PR 被合并，加上 `/hold` ，就会设置 `do-not-merge/hold` 标签。 - - 如果 PR 没有冲突、有 `lgtm` 和 `approve` 标签且没有 `hold` 标签，它就会自动合并。 - - 如果 PR 拥有 `lgtm` 和 `approve` 后再有新的变更，那么这些标签会自动清除。 - - PR 中可能用到的命令，参阅 - [斜线命令列表](https://prow.k8s.io/command-help)。 - - - 如果您以前选择了**Request changes** ，并且 PR 作者已经处理了您的关注点， - 那么您可以在**Files changed** 选项卡或 **Conversation** 选项卡底部更改您的审阅状态。 - 确保添加 `/approve` 标签，并在必要时指派技术审阅人员，以便合并 PR。 - - -### 提交到别人的 PR - - -留下评论是有帮助的，但有时你需要把自己的想法融入到其他人的 PR 中，而不仅仅是留下评论。 - - -除非对方明确要求你“接手”，或者你想重新建立一个长期被抛弃的 PR，否则不要急于“接手”。 -虽然短期内这样做可能更快，但会剥夺这个人做出贡献的机会。 - - -您的做法（接手）取决于您是需要编辑已经在 PR 范围内的文件，还是 PR 尚未触及的文件。 - - -如果以下任何一件事是符合的，你就不能提交到某人的 PR: - - -- 如果 PR 作者将他们的分支直接推入 [https://github.com/kubernetes/website/](https://github.com/kubernetes/website/) 仓库，那么只有具有 push 访问权限的审阅者才能提交到他们的 PR 中。 -- 如果 PR 作者明确禁止审批者进行编辑，那么除非他们更改此设置，否则您无法提交到他们的 PR 中。 - - -#### 文件已在 PR 中修改 - - -这个方法使用 GitHub UI。如果您愿意，您可以使用命令行，即使您想更改的文件是 PR 的一部分，如果您更愿意这样工作的话。 - - - -1. 点击 **Files changed** 选项卡。 -2. 向下找到你想要编辑的文件，点击铅笔图标。 -3. 修改并在下面添加提交记录，点击 **Commit changes**。 - - -您的提交现在被推送到 PR 对应的分支(可能在作者的分支上)， -在 PR 中，您的更改反映在 **Files changed** 选项卡中。 -留下评论，让 PR 作者知道你修改了 PR。 - - -如果作者使用命令行而不是 GitHub UI 来处理这个 PR，那么在处理 PR 之前， -他们需要获取 fork 的更改并将本地分支重新建立在 fork 中的分支上。 - -#### 如果文件没有被 PR 修改 - - -如果需要更改尚未包含在 PR 中的文件，则需要使用命令行。 -如果您喜欢使用这个方法而不喜欢使用 GitHub UI，那么您总是可以使用这个方法。 - - -1. - 获取作者的 fork 的 URL。你可以在**Conversation** 标签的底部找到它。 - 查找文本 **Add more commits by pushing to** 。 - 这个短语后面的第一个链接是到分支的，第二个链接是到 fork 的。 - 复制第二个链接。稍后会用到分支的名称。 - -2. - 要给远程设置一个名称(比如作者的 GitHub 用户名)，然后使用以下语法添加远程： - - ``` - git remote add - ``` - -3. - 获取远程。这不会更改任何本地文件，但会更新克隆的远程对象的概念(如分支和标记)及其当前状态。 - - ``` - git remote fetch - ``` - -4. - 拉取远程分支。如果已经有同名的本地分支，则此命令将失败。 - - ``` - git checkout - ``` - -5. - 进行更改，使用 `git add` 添加更改，然后提交更改。 - -6. - 将您的更改推到作者的远程。 - - ``` - git push - ``` - -7. - 回到 GitHub UI 并刷新 PR。给 PR 作者留言，让他们知道你修改了 PR。 - - -如果作者使用命令行而不是 GitHub UI 来处理这个 PR，那么在处理 PR 之前， -他们需要获取 fork 的更改并将本地分支重新建立在 fork 中的分支上。 - - -## 使用本地克隆 - - -对于需要多个文件的更改，或者涉及创建新文件或移动文件的更改， -使用本地 Git 克隆比依赖 GitHub UI 更有意义。 -这些指令使用 git 命令，并假设您已经在本地安装了它。 -您可以将它们调整为使用本地图形化 Git 客户机。 - - -### 克隆仓库 - - -对于处理 Kubernetes 文档的每个物理机，只需要克隆存储库一次。 - - - -1. 在终端中使用 `git clone` 来克隆仓库。你不需要指定任何证书。 - - ``` - git clone https://github.com/kubernetes/website - ``` - 新目录 `website` 会在当前目录中创建并包含该仓库的内容。 - -2. 进入 `website` 目录，将默认的 `origin` 重命名为远端 `upstream`。 - - ``` - cd website - - git remote rename origin upstream - ``` - -3. 如果还没有这样做，请在 GitHub 上创建存储库的分支。 - 在您的 web 浏览器中，访问 [https://github.com/kubernetes/website](https://github.com/kubernetes/website) - 并单击 Fork 按钮。几秒钟后，您将被重定向到您的 fork 的 URL，它通常类似于 `https://github.com//website`，除非您已经有一个名为 `website` 的存储库。复制这个网址。 - -4. 在你的 fork 中增加另一个远端 `origin`: - - ``` - git remote add origin - ``` - - -### 使用本地仓库 - - -在本地存储库上启动新的工作单元之前，您需要确定将工作基于哪个分支。 -答案取决于你在做什么，但是下面的指导方针是适用的： - - -- 对于现有内容的一般改进，可以从 `master` 开始。 -- 对于关于 Kubernetes 发布版本中已经存在的特性的新内容，请从 `master` 开始。 -- 对于多个 SIG Docs 贡献者将协作的长期工作，例如内容重组，使用为该工作创建的特定功能分支。 -- 对于与即将发布但尚未发布的 Kubernetes 版本相关的新内容，请使用为该 Kubernetes 版本创建的预发布特性分支。 - - -更多指导，请参考[选择分支](/docs/contribute/start/#choose-which-git-branch-to-use)。 - - -在您决定要使用哪个分支之后(或者用 Git 术语来说，基于它)， -使用以下工作流来确保您的工作基于该分支的最新版本。 - - -1. - 拉取 `upstream` 和 `origin` 远端。 - 这将更新您对这些分支所包含内容的本地概念，但不会更改您的本地分支。 - - ``` - git fetch upstream - git fetch origin - ``` - -2. - 基于你选择的分支创建一个新的跟踪分支。以你使用 master 为例： - - ``` - git checkout -b upstream/master - ``` - - - 新分支基于 `upstream/master`, 而不是你本地的 `master`。它跟踪 `upstream/master`。 - -3. - 在检出的分支上使用编辑器修改。 - 你可以随时使用 `git status` 命令来查看你的更改。 - - -4. - 当您准备提交 pull request 时，提交您的更改。 - 首先使用 git status 查看需要向变更集中添加哪些更改。 - 有两个重要的部分：`Changes staged for commit` 和 `Changes not staged for commit`。 - 如果您希望将后一节中显示的 `modified` 或 `untracked` 文件添加到提交中，你需要使用 `git add`。 - - ``` - git add example-file.md - ``` - - - 当所有文件准备好时，使用 `git commit` 命令提交： - - ``` - git commit -m "Your commit message" - ``` - -{{< note >}} - -不要在提交消息中引用 GitHub issue 或 PR(通过 ID 或 URL)。如果您这样做了，那么每当提交出现在新的 Git 分支中时，就会导致该 issue 或 PR 获得通知。稍后，您可以在 GitHub UI 中链接 issues 并将请求拉到一起。 -{{< /note >}} - -5. - 您还可以选择使用 hugo 命令在本地暂存站点来测试您的更改。参阅[本地查看更改](#本地查看更改)。您还可以在提交 PR 后查看更改。 - -6. - 在创建包含本地提交的 PR 之前，需要将分支推到 fork，也就是 `origin` 端点。 - - ``` - git push origin - ``` - - 从技术上讲，您可以从 push 命令中省略分支名称，但是这种情况下的行为取决于您使用的 Git 版本。 - 如果包含分支名称，结果将更加可重复。 - - -7. - 此时，如果您在 web 浏览器中访问 https://github.com/kubernetes/website, GitHub 会检测到您将一个新的分支推送到您的 fork，并提供创建一个 pull 请求。填写 pull request 模板。 - - - 标题不应超过 50 个字符，并总结更改的意图。 - - - 长表单描述应该包含关于修复的更多信息，如果 PR 修复了 GitHub issue， - 则应该包含类似 `Fixes #12345` 这样的行。 - 这将导致在合并 PR 时自动关闭该 issue。 - - - 您可以添加标签或其他元数据并分配审阅人员。有关语法，请参见[分类 issues](#triage-and-categorize-issues)。 - - 点击 **Create pull request** - -8. - 几个自动化测试将运行与您所应用的更改的网站状态。 - 如果任何测试失败，请单击**Details**链接获取更多信息。 - 如果 Netlify 测试成功完成，它的**Details**链接将转到 Kubernetes 网站的阶段性版本， - 其中应用了您的更改。 - 这是审阅人员检查更改的方式。 - -9. - 如果您注意到需要进行更多的更改，或者评审人员给了您反馈，请在本地处理反馈， - 然后再次重复步骤 4 - 6，创建一个新的提交。新的提交被添加到您的 pull 请求中， - 测试再次运行，包括 Netlify。 - -10. - 如果审查员将更改添加到您的 pull 请求中，您需要从 fork 获取这些更改，然后才能添加更多的更改。 - 假设您的分支当前已签出，请使用以下命令来完成此操作。 - - ``` - git fetch origin - git rebase origin/ - ``` - - 在 rebasing 之后，您需要添加 `-f` 标志来强制推送分支。 - - ``` - git push -f origin - ``` - -11. - 如果其他人的更改合并到您工作所基于的分支中，并且您对相同文件的相同部分进行了更改， - 则可能会发生冲突。如果 pull 请求显示有需要解决的冲突，您可以使用 GitHub UI 解决它们， - 或者在本地解决它们。 - - 首先执行第 10 步，确保你的 fork 仓库与你本地分支一致。 - - - 接着，拉取 `upstream` 并 rebase 你的分支。 - - ``` - git fetch upstream - git rebase upstream/master - ``` - - - 如果存在 Git 无法自动解决的冲突，可以使用 `git status` 命令查看冲突文件。 - 对于每个冲突文件，编辑它并查找冲突标记 `>>>`，`<<<`，and `===`。 - 解决冲突并删除冲突标记。然后使用 `git add `， - 并使用 `git rebase --continue` 继续将更改添加到更改集中。 - 当所有提交都已应用，并且没有更多冲突时，`git status` 将显示您不在 rebase 中， - 并且不需要提交任何更改。此时，强制将分支推到 fork, pull 请求应该不再显示任何冲突。 - - -如果您在解决冲突方面遇到困难，或者您被与 pull 请求相关的任何其他事情卡住， -请在 `#sig-docs` Slack 通道或 [kubernet-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) 中寻求帮助。 - - -### 本地查看更改 - - -如果您还没有准备好创建一个 pull 请求， -但是您希望看到您的更改是什么样子的， -那么您可以构建并运行一个 docker 映像来生成所有文档并在本地提供它。 - - -1. 本地构建镜像: - - ``` - make docker-image - ``` - -2. `kubernetes-hugo` 镜像构建完成后，可以构建并启动网站： - - ``` - make docker-serve - ``` - -3. 在浏览器地址栏输入 `localhost:1313`。Hugo 将监视文件系统的更改，并根据需要重新构建站点。 - -4. 如果想停掉本地 Hugo 实例，只需要在命令行中输入 `Ctrl+C` 来关闭命令行窗口。 - - -或者，您可以在您的开发机器上安装并使用 hugo 命令： - -1. - [安装 Hugo](https://gohugo.io/getting-started/installing/) 版本 {{< hugoVersion >}} 或更新版本. - -2. - 在终端中，转到您克隆的 Kubernetes 文档的根目录，并输入以下命令： - - ``` - hugo server - ``` - -3. - 在浏览器地址栏中输入 `localhost:1313`。 - -4. - 如果想停掉本地 Hugo 实例，只需要在命令行中输入 `Ctrl+C` 来关闭命令行窗口。 - - -## issues 归类 - - -在任何给定的一周内，一个特定的文档审批者会自愿对 pull 请求和 issues 进行初步分类和审查。 -要进入这个名单，参加每周的团体文档会议和志愿者。 -即使你不在这周的时间表上，你仍然可以审核 PR。 - - -SIG 文档人员只负责对文档 issues 进行分类和分类。一般的网站 issues 也归档在 `kubernetes/website` 资源库中。 - - -当你对一个 issue 进行分类时： - - -- 评估这个 issue 是否有价值。有些 issues 可以通过回答问题或向作者指出资源来迅速解决。 -- 如果 issue 没有足够的细节可以采取行动，或者模板没有填好，询问作者更多的信息。 -- 向 issue 添加标签(有时称为标签)、项目或者里程碑。SIG 文档团队并没有大量使用项目和里程碑。 -- 根据您的判断，对某个 issue 拥有所有权并为其提交 PR (特别是如果它是快速的或与您已经在做的工作相关的)。 - - -如果你针对 issue 分类有疑问，请在 Slack `#sig-docs` 频道或 [kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) 中询问。 - - -### 有关标签的更多信息 - - -这些准则并非一成不变，可能会发生变化。 - - -- 一个 issue 可以有多个标签。 -- 一些标签使用斜杠符号进行分组，可以将其视为“子标签”。例如，`sig/` 存在许多标签，例如 `sig/cli` 和 `sig/api-machinery`。 -- 系统会根据 issue 所涉及文件中的元数据，issue 注释中使用的斜杠命令或 issue 文本中的信息，自动添加一些标签。 -- 由负责 issue 分类的人员（或报告 issue 的人员，如果他们是 SIG 文档批准者）手动添加一些标签。 - - `Actionable`：似乎有足够的信息可以解决或解决此 issue。 - - `good first issue`： Kubernetes 或 SIG Docs 经验有限的人也有可能可以解决此 issue。 - - `kind/bug`、`kind/feature`、`kind/documentation`： - 如果提出 issue 的人未正确填写模板，则可能不会自动分配这些标签。 - 错误是现有内容或功能的 issue，功能是对新内容或功能的请求。`kind/documentation` 标签当前未使用。 - - 优先级标签：定义 issue 的相对严重性。 - 如 [Kubernetes 贡献者指导](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority) 中所述。 -- 要添加标签，添加 `/label `。标签必须已经存在。 - 如果您尝试添加不存在的标签，该命令将被默认忽略。 - - -### 处理特殊 issue 类型 - - -我们经常遇到以下类型的 issues，足以记录如何处理它们。 - - -#### 重复的 issues - - -如果单个问题可以解决一个或多个 issues，则应将该问题合并为一个 issue。 -您应该决定哪个 issue 保持打开状态（或打开一个新 issue），移植所有相关信息，链接相关 issues， -并关闭描述同一 issue 的所有其他 issues。只处理一个 issue 将有助于减少混乱并避免重复处理同一问题。 - - -#### 无效链接 issues - - -根据报告无效链接的位置，需要采取不同的措施来解决此 issue。 -API 和 Kubectl 文档中的无效链接是自动化 issues，应分配为 `/priority critical-urgent`， -直到可以完全解决该问题为止。所有其他无效链接都是需要手动修复的 issues， -可以将其分配为 `/priority important-longterm`。 - - -#### 博客 issues - - -随着时间的流逝，Kubernetes 博客条目预计会过时， -因此我们仅保留不到一年的博客条目。 -如果某个 issue 与存在超过一年的博客条目有关，则应将其关闭而不进行修复。 - - -#### 支持请求或代码错误报告 - - -相反，为文档带来的一些 issues 是底层代码的 issues， -或者在某些内容（例如教程）不起作用时请求帮助。 -对于与文档无关的 issues，请关闭 issue 并指示请求者正确的支持场所（Slack，Stack Overflow）， -并在适当的地方针对具有功能缺陷的问题提出 issue（可以从 kubernetes/kubernetes 开始）。 - - -对支持请求的响应示例： - -```none -This issue sounds more like a request for support and less -like an issue specifically for docs. I encourage you to bring -your question to the `#kubernetes-users` channel in -[Kubernetes slack](http://slack.k8s.io/). You can also search -resources like -[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes) -for answers to similar questions. - -You can also open issues for Kubernetes functionality in - https://github.com/kubernetes/kubernetes. - -If this is a documentation issue, please re-open this issue. -``` - - -示例代码错误报告响应： - -```none -This sounds more like an issue with the code than an issue with -the documentation. Please open an issue at -https://github.com/kubernetes/kubernetes/issues. - -If this is a documentation issue, please re-open this issue. -``` - - -## 记录新功能 - - -每个主要的 Kubernetes 版本都包含新功能，其中许多功能至少需要少量文档才能向人们展示如何使用它们。 - - -通常，负责功能的 SIG 负责对 `kubernetes/website` 存储库的相应 release 分支发起 PR， -提交该功能的文档草稿，并且由 SIG Docs 团队中的某人提供编辑反馈或直接编辑草稿。 - - -### 了解即将推出的功能 - - -要了解即将发布的功能，请参加每周一次的 sig-release 会议 -（请参阅[社区](https://kubernetes.io/community/)页面以获取即将举行的会议， -并在 [kubernetes/sig-release](https://github.com/kubernetes/sig-release/) 存储库中留意特定于发行版的文档。 -每个发行版在 [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases) - 目录下都有一个子目录。每个子目录包含一个发布计划，一个发布说明草稿以及一个列出发布团队中每个人的文档。 - - -- 发布时间表包含与发布有关的所有其他文档、会议、会议记录和里程碑的链接。 - 它还包含有关该发行版的目标和时间表的信息，以及此发行版的任何特殊流程。 - 在文档底部附近，定义了几个与发布相关的术语。 - - 本文档还包含**Feature tracking sheet**的链接，这是查找排定要发布的所有新功能的正式方法。 - -- 发布团队文档列出了负责每个发布角色的人员。 - 如果不清楚要与谁谈论某个特定功能或问题，请参加发布会议询问您的问题， - 或者与发布负责人联系，以便他们可以重定向您。 -- 发行说明草稿是了解更多有关特定功能、更改、不推荐使用以及更多有关发行版本的好地方。 - 该内容要到发布周期的后期才能最终确定，因此请谨慎使用。 - - -#### 功能跟踪表 - - -给定 Kubernetes 版本的功能跟踪表列出了计划发布的每个功能。 -每个订单项都包含功能名称，功能主要 GitHub issue 的链接，其稳定性级别（Alpha，Beta 或 Stable）， -SIG 和负责实施此功能的人员，是否需要文档，发布说明草稿功能，以及是否已合并。请记住以下几点： - - -- Beta 和稳定功能通常比 Alpha 功能具有更高的文档优先级。 -- 很难测试（因此要文档记录）尚未合并的功能，或者至少在其 PR 中被认为功能完整的功能。 -- 确定某个功能是否需要文档是一个手动过程，并且仅仅因为某个功能未标记为需要文档并不意味着它就不需要它们。 - - -### 记录功能 - - -如上所述，新功能的草案内容通常由负责实施新功能的 SIG 提交。 -这意味着您的角色可能更像是给定功能的牧羊人角色。 - - -选择要记录/跟踪的功能后，请在 `#sig-docs` Slack 频道， -每周一次的 sig-docs 会议中或直接在功能 SIG 提交的 PR 上询问有关功能。 -如果得到批准，则可以使用[提交到别人的 PR](#commit-into-another-persons-pr) 中介绍的技术来编辑 PR。 - - -如果您需要编写新主题，则以下链接很有用： - - -- [撰写新主题](/docs/contribute/style/write-new-topic/) -- [使用页面模板](/docs/contribute/style/page-templates/) -- [文档样式指南](/docs/contribute/style/style-guide/) - - -SIG 成员记录了新功能 - - -如果您是 Kubernetes 开发新功能的 SIG 成员，则需要一并更新 SIG 文档， -以确保在发布该功能时及时记录了您的功能。 -查看[功能跟踪电子表格](https://github.com/kubernetes/sig-release/tree/master/releases)， - 或在 #sig-release Slack 频道中查看验证计划详细信息和截止日期。 - 与文档相关的一些截止日期是： - - -- **文档截止期限 - 打开占位 PR** ：针对 `kubernetes/website` 仓库中的 `release-X.Y` 分支提交一个 PR， - 稍作修改(占位)，稍后您将继续修改。使用 Prow 命令 `/milestone X.Y` 将 PR 分配给相关的里程碑。 - 这会提醒管理此版本的文档人员功能文档即将发布。 - 如果您的功能不需要任何文档更改，请在 #sig-release Slack 频道中说一下， - 以确保 sig-release 团队知道这一点。 - 如果该功能确实需要文档，但未创建 PR，则该功能可能已从里程碑中删除。 -- **文档截止日期 - PR 审核**：您的 PR 现在需要包含功能文档的初稿。不必担心格式或修饰。 - 只需描述该功能的用途以及使用方法即可。管理发行版的文档人员将与您合作，使内容成形以进行发布。 - 如果您的功能需要文档且未收到第一稿内容，则该功能可能已从里程碑中删除。 -- **文档完成 - PR 已审核，准备合并**：如果您的 PR 尚未在 `release-X.Y` 此期限之前合并到分支中， - 请与管理发行版的文档人员一起合作帮助它合入。 - 如果您的功能需要文档且文档尚未准备好，该功能可能会从里程碑中删除。 - - -如果您的功能是 Alpha 功能并且由[功能开关](/docs/reference/command-line-tools-reference/feature-gates/) 控制， -请确保将其作为 PR 的一部分添加到功能开关。 -如果您的功能要移出 Alpha，请确保将其从该文件中删除。 - - -## 贡献其他仓库 - - -该 Kubernetes 项目包含超过 50 个仓库。 -这些存储库中许多都包含可以视为文档的代码或内容，例如面向用户的帮助文本，错误消息， -API 参考中的面向用户的文本，甚至是代码注释。 - - -如果您看到文本并且不确定其来源，则可以在 Kubernetes 组织级别使用 GitHub 的搜索工具在所有存储库中搜索该文本。 -这可以帮助您确定将 issue 或 PR 提交到哪里。 - - -每个存储库可能都有自己的流程和过程。 -在您提交的 issue 或提交 PR，查看存储库的 `README.md`、`CONTRIBUTING.md` 以及 `code-of-conduct.md`。 - - -大多数存储库使用 issue 和 PR 模板。 -浏览一些未解决的 issues 和 PR，以了解该团队的流程。 -提交 issues 或 PR 时，​​请确保尽可能详细地填写模板。 - - -## 本地化内容 - - -Kubernetes 文档首先是用英语编写的，但是我们希望人们能够使用他们选择的语言来阅读它。 -如果您愿意用另一种语言编写，尤其是在软件领域，则可以帮助本地化 Kubernetes 文档 -或提供有关现有本地化内容的反馈。 -如果您有兴趣提供帮助，请参阅 [本地化](/docs/contribute/localization/)， -并在 [kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) 或者 Slack 的 `#sig-docs` 群组内咨询。 - - -### 参与本地化工作 - - -请遵循以下准则来使用本地化内容： - - -- 将 PR 限制为一种语言。 - - 每种语言都有其自己的审阅者和批准者。 - -- 审阅者，请验证 PR 是否仅对一种语言进行了更改。 - - 如果 PR 包含对一种以上源语言的更改，请 PR 贡献者为每种语言打开单独的 PR。 - - - -## {{% heading "whatsnext" %}} - - - -如果您熟悉本主题中讨论的所有任务，并且想与 Kubernetes 文档小组进行更深入的接触， -请阅读[文档高级贡献者](/docs/contribute/advanced/)主题。 - diff --git a/content/zh/docs/contribute/localization.md b/content/zh/docs/contribute/localization.md index bad833c974..efd57dbdbf 100644 --- a/content/zh/docs/contribute/localization.md +++ b/content/zh/docs/contribute/localization.md @@ -1,24 +1,24 @@ --- title: 本地化 Kubernetes 文档 content_type: concept +weight: 50 card: - name: contribute - weight: 30 + name: 贡献 + weight: 50 title: 翻译文档 --- @@ -26,9 +26,8 @@ card: -此页面显示了如何为其他语言的文档提供[本地化](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/)。 - - +此页面描述如何为其他语言的文档提供 +[本地化](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/)版本。 @@ -39,11 +38,11 @@ Because contributors can't approve their own pull requests, you need at least tw All localization teams must be self-sustaining with their own resources. We're happy to host your work, but we can't translate it for you. --> -## 入门 +## 起步 由于贡献者无法批准他们自己的请求，因此您至少需要两个贡献者才能开始本地化。 -所有本地化团队必须使用自身的资源独立工作。我们很高兴支持你的工作，但无法为你翻译。 +所有本地化团队必须使用自身的资源持续工作。我们很高兴托管你的产出，但无法为你翻译。 ### 找到两个字母的语言代码 -首先，有关本地化的两个字母的国家代码，请参考 [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)。例如，韩国的两个字母代码是 `ko`。 +首先，有关本地化的两个字母的国家代码，请参考 +[ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)。 +例如，韩国的两个字母代码是 `ko`。 -### fork 并且克隆仓库 {#fork-and-clone-the-repo} +### 派生（fork）并且克隆仓库 {#fork-and-clone-the-repo} -首先，在 [kubernetes/website](https://github.com/kubernetes/website) 仓库中的 [fork 你自己的分支](/docs/contribute/start/#improve-existing-content)。 +首先，为 [kubernetes/website](https://github.com/kubernetes/website) 仓库 +[创建你自己的副本](/zh/docs/contribute/new-content/new-content/#fork-the-repo)。 -然后，克隆 website 仓库并通过 `cd` 命令进入 website 目录： +然后，克隆你的 website 仓库副本并通过 `cd` 命令进入 website 目录： ```shell git clone https://github.com//website @@ -81,46 +83,53 @@ The PR must include all of the [minimum required content](#minimum-required-cont For an example of adding a new localization, see the PR to enable [docs in French](https://github.com/kubernetes/website/pull/12548). --> -### 发起 pr +### 发起拉取请求（PR）{#open-a-pull-request} -接下来，[提交 PR 请求](https://kubernetes.io/docs/contribute/start/#submit-a-pull-request)，将本地化添加到 `kubernetes/website` 仓库。 +接下来，[提交 PR 请求](/zh/docs/contribute/new-content/open-a-pr/#open-a-pr)， +将本地化添加到 `kubernetes/website` 仓库。 -PR 必须包含所有[最低要求的内容](#minimum-required-content)，然后才能被批准。 +该 PR 必须包含所有[最低要求的内容](#minimum-required-content)，然后才能被批准。 有关添加新本地化的示例，请参见添加[法语文档](https://github.com/kubernetes/website/pull/12548) 的 PR。 -### Join the Kubernetes GitHub organization - -提交本地化 PR 后，您可以成为 Kubernetes GitHub 组织的成员。团队中的每个人都需要在 `kubernetes/org` 仓库中创建自己的[组织成员资格申请](https://github.com/kubernetes/org/issues/new/choose)。 +### 加入到 Kubernetes GitHub 组织 + +提交本地化 PR 后，你可以成为 Kubernetes GitHub 组织的成员。 +团队中的每个人都需要在 `kubernetes/org` 仓库中创建自己的 +[组织成员申请](https://github.com/kubernetes/org/issues/new/choose)。 -### 在 GitHub 中添加您的本地化团队 +### 在 GitHub 中添加你的本地化团队 {#add-your-localization-team-in-github} -接下来，将您的 Kubernetes 本地化团队添加到[`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml)。有关添加本地化团队的示例，请参见添加[西班牙本地化团队](https://github.com/kubernetes/org/pull/685) 的 PR。 +接下来，将你的 Kubernetes 本地化团队添加到 +[`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml)。 +有关添加本地化团队的示例，请参见添加[西班牙本地化团队](https://github.com/kubernetes/org/pull/685) 的 PR。 -`sig-docs-**-owners` 成员可以批准更改对应本地化目录 `/content/**/` 中内容的 PR，并仅限这类 PR。 +`@kubernetes/sig-docs-**-owners` 成员可以批准更改对应本地化目录 `/content/**/` 中内容的 PR，并仅限这类 PR。 -`sig-docs-**-reviews` 团队自动分派新 PR 的审阅任务。 +`@kubernetes/sig-docs-**-reviews` 团队被自动分派新 PR 的审阅任务。 -`sig-docs-l10n-admins` 成员可以创建新的开发分支来协调翻译工作。 +`@kubernetes/website-maintainers` 成员可以创建新的开发分支来协调翻译工作。 -`website-milestone-maintainers` 成员可以使用 `/milestone` [Prow 命令](https://prow.k8s.io/command-help) 为 issues 或 PR 设定里程碑。 +`@kubernetes/website-milestone-maintainers` 成员可以使用 `/milestone` +[Prow 命令](https://prow.k8s.io/command-help) 为 issues 或 PR 设定里程碑。 -### 配置工作流程 +### 配置工作流程 {#configure-the-workflow} -接下来，在 `kubernetes/test-infra` 仓库中为您的本地化添加一个 GitHub 标签。标签可让您过滤 issues 并提出针对特定语言的 pr。 +接下来，在 `kubernetes/test-infra` 仓库中为您的本地化添加一个 GitHub 标签。 +标签可让您过滤 issues 和针对特定语言的 PR。 有关添加标签的示例，请参见添加[意大利语标签](https://github.com/kubernetes/test-infra/pull/11316)的 PR。 @@ -144,9 +154,12 @@ You can also create a Slack channel for your localization in the `kubernetes/com --> ### 寻找社区 -让 Kubernetes SIG Docs 知道您对创建本地化感兴趣！ 加入[SIG Docs Slack 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)。其他本地化团队很乐意帮助您入门并回答您的任何问题。 +让 Kubernetes SIG Docs 知道你对创建本地化感兴趣！ +加入[SIG Docs Slack 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)。 +其他本地化团队很乐意帮助你起步并回答你的任何问题。 -您还可以在 `kubernetes/community` 存储库中为本地化创建一个 Slack 频道。有关添加 Slack 频道的示例，请参见[为印尼语和葡萄牙语添加频道](https://github.com/kubernetes/community/pull/3605)的 PR。 +你还可以在 `kubernetes/community` 仓库中为你的本地化创建一个 Slack 频道。 +有关添加 Slack 频道的示例，请参见[为印尼语和葡萄牙语添加频道](https://github.com/kubernetes/community/pull/3605)的 PR。 -为您的块分配一个 `weight` 参数时，找到权重最高的语言块并将其加 1。 +为你的语言块分配一个 `weight` 参数时，找到权重最高的语言块并将其加 1。 有关 Hugo 多语言支持的更多信息，请参阅"[多语言模式](https://gohugo.io/content-management/multilingual/)"。 @@ -190,7 +206,9 @@ Add a language-specific subdirectory to the [`content`](https://github.com/kuber --> ### 添加一个新的本地化目录 -将特定语言的子目录添加到仓库中的 [`content`](https://github.com/kubernetes/website/tree/master/content) 文件夹下。例如，德语的两个字母的代码是 `de`： +将特定语言的子目录添加到仓库中的 +[`content`](https://github.com/kubernetes/website/tree/master/content) 文件夹下。 +例如，德语的两个字母的代码是 `de`： ```shell mkdir content/de @@ -201,15 +219,15 @@ mkdir content/de Open a PR against the [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages) repository to add the code of conduct in your language. -### Add a localized README --> ### 本地化社区行为准则 -针对 [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages) 仓库提交 PR，添加您所用语言版本的行为准则。 - -### 添加本地化的 README 文件 +在 [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages) +仓库提交 PR，添加你所用语言版本的行为准则。 -为了指导其他本地化贡献者，请在 k/website 的根目录添加一个新的 [`README-**.md`](https://help.github.com/articles/about-readmes/)，其中 `**` 是两个字母的语言代码。例如，德语 README 文件为 `README-de.md`。 +### 添加本地化的 README 文件 + +为了指导其他本地化贡献者，请在 k/website 的根目录添加一个新的 +[`README-**.md`](https://help.github.com/articles/about-readmes/)， +其中 `**` 是两个字母的语言代码。例如，德语 README 文件为 `README-de.md`。 在本地化的 `README-**.md` 文件中为本地化贡献者提供指导。包含 `README.md` 中包含的相同信息，以及： - 本地化项目的联系人 -- 任何有关本地化的信息 +- 任何特定于本地化的信息 -创建本地化的 README 文件后，请在英语版文件 `README.md` 中添加指向该文件的链接，并给出英文形式的联系信息。您可以提供 GitHub ID、电子邮件地址、[Slack 频道](https://slack.com/)或其他联系方式。您还必须提供指向本地化的社区行为准则的链接。 +创建本地化的 README 文件后，请在英语版文件 `README.md` 中添加指向该文件的链接， +并给出英文形式的联系信息。你可以提供 GitHub ID、电子邮件地址、 +[Slack 频道](https://slack.com/)或其他联系方式。你还必须提供指向本地化的社区行为准则的链接。 有关 `OWNERS` 文件的更多信息，请访问[go.k8s.io/owners](https://go.k8s.io/owners)。 -带有语言代码 `es` 的[西班牙 OWNERS 文件](https://git.k8s.io/website/content/es/OWNERS)看起来像： +语言代码为 `es` 的[西班牙语 OWNERS 文件](https://git.k8s.io/website/content/es/OWNERS)看起来像： + - -```yaml -# 在 https://go.k8s.io/owners 地址查看 OWNERS 文档 - -# 这是西班牙语的本地化项目。 -# 团队和成员位于 https://github.com/orgs/kubernetes/teams。 - -reviewers: -- sig-docs-es-reviews - -approvers: -- sig-docs-es-owners - -labels: -- language/es -``` -添加了特定语言的 OWNERS 文件之后，使用新的 Kubernetes 团队更新 [根目录下的 OWNERS_ALIAES](https://git.k8s.io/website/OWNERS_ALIASES) 文件进行本地化，即 `sig-docs-**-owners` 和 `sig-docs-**-reviews`。 +添加了特定语言的 OWNERS 文件之后，使用新的 Kubernetes 本地化团队、 +`sig-docs-**-owners` 和 `sig-docs-**-reviews` 列表更新 +[根目录下的 OWNERS_ALIAES](https://git.k8s.io/website/OWNERS_ALIASES) 文件。 -对于每个团队，请按字母顺序添加[在 GitHub 中添加您的本地化团队](#add-your-localization-team-in-github) 中请求的 GitHub 用户列表。 +对于每个团队，请按字母顺序添加 +[在 GitHub 中添加您的本地化团队](#add-your-localization-team-in-github) +中所请求的 GitHub 用户列表。 ```diff --- a/OWNERS_ALIASES @@ -340,15 +357,17 @@ Site strings | [All site strings in a new localized TOML file](https://github.co --> 描述 | 网址 -----|----- -主页 | [所有标题和副标题网址](/docs/home/) -安装 | [所有标题和副标题网址](/docs/setup/) -教程 | [Kubernetes 基础](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/stateless-application/hello-minikube/) +主页 | [所有标题和副标题网址](/zh/docs/home/) +安装 | [所有标题和副标题网址](/zh/docs/setup/) +教程 | [Kubernetes 基础](/zh/docs/tutorials/kubernetes-basics/), [Hello Minikube](/zh/docs/tutorials/stateless-application/hello-minikube/) 网站字符串 | [新的本地化 TOML 文件中的所有网站字符串](https://github.com/kubernetes/website/tree/master/i18n) -翻译后的文档必须保存在自己的 `content/**/` 子目录中，否则将遵循与英文源相同的 URL 路径。例如，要准备将 [Kubernetes 基础](/docs/tutorials/kubernetes-basics/) 教程翻译为德语，请在 `content/de/` 文件夹下创建一个子文件夹并复制英文源： +翻译后的文档必须保存在自己的 `content/**/` 子目录中，否则将遵循与英文源相同的 URL 路径。 +例如，要准备将 [Kubernetes 基础](/zh/docs/tutorials/kubernetes-basics/) 教程翻译为德语， +请在 `content/de/` 文件夹下创建一个子文件夹并复制英文源： ```shell mkdir -p content/de/docs/tutorials @@ -391,32 +410,31 @@ The latest version is {{< latest-version >}}, so the most recent release branch 要查找最新版本的源文件： 1. 导航到 Kubernetes website 仓库，网址为 https://github.com/kubernetes/website。 -2. 选择最新版本的 `release-1.X` 分支。 +1. 选择最新版本的 `release-1.X` 分支。 -最新版本是 {{< latest-version >}}，所以最新的发行分支是 [`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}})。 +最新版本是 {{< latest-version >}}，所以最新的发行分支是 +[`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}})。 ### i18n/ 中的网站字符串 - -本地化必须在新的语言特定文件中包含 [`i18n/en.toml`](https://github.com/kubernetes/website/blob/master/i18n/en.toml) 的内容。以德语为例：`i18n/de.toml`。 +本地化必须在新的语言特定文件中包含 +[`i18n/en.toml`](https://github.com/kubernetes/website/blob/master/i18n/en.toml) +的内容。以德语为例：`i18n/de.toml`。 - 将新的本地化文件添加到 `i18n/`。例如德语 (`de`)： ```shell cp i18n/en.toml i18n/de.toml ``` - 然后翻译每个字符串的值： ```TOML @@ -436,22 +454,20 @@ Some language teams have their own language-specific style guide and glossary. F --> ### 特定语言的样式指南和词汇表 -一些语言团队有自己的特定语言风格指南和词汇表。例如，请参见[韩语本地化指南](/ko/docs/contribute/localization_ko/)。 +一些语言团队有自己的特定语言样式指南和词汇表。 +例如，请参见[韩语本地化指南](/ko/docs/contribute/localization_ko/)。 -### 分支策略 - -因为本地化项目是高度协同的工作，所以我们鼓励团队基于共享的开发分支工作。 - -在开发分支上协作： +### 分支策略 +因为本地化项目是高度协同的工作，所以我们鼓励团队基于共享的开发分支工作。 + +在开发分支上协作需要： -1. [@kubernetes/sig-docs-l10n-admins](https://github.com/orgs/kubernetes/teams/sig-docs-l10n-admins) 中的团队成员从 https://github.com/kubernetes/website 原有分支新建一个开发分支。 - 当您给 `kubernetes/org` 存储库[添加您的本地化团队](#add-your-localization-team-in-github)时，您的团队 approvers 便加入了 `sig-docs-l10n-admins`。 +1. [@kubernetes/website-maintainers](https://github.com/orgs/kubernetes/teams/website-maintainers) + 中的团队成员从 https://github.com/kubernetes/website 原有分支新建一个开发分支。 + 当你给 `kubernetes/org` 仓库[添加你的本地化团队](#add-your-localization-team-in-github)时， + 你的团队批准人便加入了 `@kubernetes/website-maintainers` 团队。 - 我们推荐以下分支命名方案： + 我们推荐以下分支命名方案： - `dev--.` + `dev--.` - 例如，一个德语本地化团队的 approvers 基于 Kubernetes v1.12 版本的源分支直接新建了 k/website 仓库的开发分支 `dev-1.12-de.1`。 + 例如，一个德语本地化团队的批准人基于 Kubernetes v1.12 版本的源分支， + 直接新建了 k/website 仓库的开发分支 `dev-1.12-de.1`。 -2. 个人贡献者基于开发分支新建特性分支。 +2. 个人贡献者基于开发分支创建新的特性分支 - 例如，一个德国贡献者新建了一个拉取请求，并将 `username:local-branch-name` 更改为 `kubernetes:dev-1.12-de.1`。 + 例如，一个德语贡献者新建了一个拉取请求，并将 `username:local-branch-name` 更改为 `kubernetes:dev-1.12-de.1`。 -3. Approvers 审查功能分支并将其合并到开发分支中。 +3. 批准人审查功能分支并将其合并到开发分支中。 -4. approver 会定期打开并批准新的 pr，将开发分支合并到其源分支。在批准 pr 之前，请确保先 squash 提交。 +4. 批准人会定期发起并批准新的 PR，将开发分支合并到其源分支。在批准 PR 之前，请确保先 squash commits。 -根据需要重复步骤 1-4，直到完成本地化工作。例如，随后的德语开发分支将是：`dev-1.12-de.2`、`dev-1.12-de.3`，等等。 +根据需要重复步骤 1-4，直到完成本地化工作。例如，随后的德语开发分支将是： +`dev-1.12-de.2`、`dev-1.12-de.3`，等等。 -团队必须将本地化内容合入到发布分支中，该发布分支也正是内容的来源。例如，源于 {{< release-branch >}} 的开发分支必须基于 {{< release-branch >}}。 - -approver 必须通过使开发分支与源分支保持最新并解决合并冲突来维护开发分支。开发分支的存在时间越长，通常需要的维护工作就越多。考虑定期合并开发分支并新建分支，而不是维护一个持续时间很长的开发分支。 +团队必须将本地化内容合入到发布分支中，该发布分支也正是内容的来源。 +例如，源于 {{< release-branch >}} 的开发分支必须基于 {{< release-branch >}}。 + +approver 必须通过使开发分支与源分支保持最新并解决合并冲突来维护开发分支。 +开发分支的存在时间越长，通常需要的维护工作就越多。 +考虑定期合并开发分支并新建分支，而不是维护一个持续时间很长的开发分支。 -在每个团队里程碑的起点，打开一个 issue 来比较先前的开发分支和当前的开发分支之间的上游变化很有帮助。 - - 虽然只有 approver 才能开启新的开发分支并合并 pr，但任何人都可以为新的开发分支提交一个拉取请求（PR）。不需要特殊权限。 + +在团队每个里程碑的起点，创建一个 issue 来比较先前的开发分支和当前的开发分支之间的上游变化很有帮助。 +虽然只有批准人才能创建新的开发分支并合并 PR，但任何人都可以为新的开发分支提交一个拉取请求（PR）。 +不需要特殊权限。 -有关基于 fork 或直接从仓库开展工作的更多信息，请参见 ["fork 和克隆"](#fork-and-clone-the-repo)。 +有关基于派生或直接从仓库开展工作的更多信息，请参见 ["派生和克隆"](#fork-and-clone-the-repo)。 -### 上游贡献 - -Sig Docs 欢迎[上游贡献和修正](/docs/contribute/intermediate#localize-content) 到英文原文。 +### 上游贡献 {#upstream-contributions} + +Sig Docs 欢迎对英文原文的[上游贡献和修正](/zh/docs/contribute/intermediate#localize-content)。 ## 帮助现有的本地化 - -您还可以向现有本地化添加或改进内容提供帮助。加入 [Slack 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)进行本地化，然后开始新建 PR 来提供帮助。 - - +您还可以向现有本地化添加或改进内容提供帮助。 +加入本地化团队的 [Slack 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)， +然后开始新建 PR 来提供帮助。 +请限制每个 PR 只涉及一种语言，这是因为更改多种语言版本内容的 PR +可能非常难审阅。 ## {{% heading "whatsnext" %}} - -本地化满足工作流程和最低输出要求后，SIG 文档将： - +本地化满足工作流程和最低输出要求后，SIG 文档将： + - 在网站上启用语言选择 -- 通过[Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF) 频道, 包括[ Kubernetes 博客](https://kubernetes.io/blog/)公开本地化的可用性。 - +- 通过[Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF) 频道, + 包括[ Kubernetes 博客](https://kubernetes.io/blog/)公开本地化的可用性。 diff --git a/content/zh/docs/contribute/participate/_index.md b/content/zh/docs/contribute/participate/_index.md new file mode 100644 index 0000000000..0c263dd8a8 --- /dev/null +++ b/content/zh/docs/contribute/participate/_index.md @@ -0,0 +1,225 @@ +--- +title: 参与 SIG Docs +content_type: concept +weight: 60 +card: + name: contribute + weight: 60 +--- + + + + + +SIG Docs 是 Kubernetes 项目 +[特别兴趣小组](https://github.com/kubernetes/community/blob/master/sig-list.md) +中的一个，负责编写、更新和维护 Kubernetes 的总体文档。 +参见[社区 GitHub 仓库中 SIG Docs](https://github.com/kubernetes/community/tree/master/sig-docs) +以进一步了解该 SIG。 + + +SIG Docs 欢迎所有贡献者提供内容和审阅。任何人可以提交拉取请求（PR）。 +欢迎所有人对文档内容创建 Issue 和对正在处理中的 PR 进行评论。 + + +你也可以成为[成员（member）](/docs/contribute/participating/roles-and-responsibilities/#members)、 +[评阅人（reviewer）](/docs/contribute/participating/roles-and-responsibilities/#reviewers) 或者 +[批准人（approver）](/docs/contribute/participating/roles-and-responsibilities/#approvers)。 +这些角色拥有更高的权限，且需要承担批准和提交变更的责任。 +有关 Kubernetes 社区中的成员如何工作的更多信息，请参见 +[社区成员身份](https://github.com/kubernetes/community/blob/master/community-membership.md)。 + +本文档的其余部分概述了这些角色在 SIG Docs 中发挥作用的一些独特方式。 +SIG Docs 负责维护 Kubernetes 最面向公众的方面之一 —— Kubernetes 网站和文档。 + + + + +## SIG Docs 主席 + +每个 SIG，包括 SIG Docs，都会选出一位或多位成员作为主席。 +主席会成为 SIG Docs 和其他 Kubernetes 组织的联络接口人。 +他们需要了解整个 Kubernetes 项目的架构，并明白 SIG Docs 如何在其中运作。 +如需查询当前的主席名单，请查阅 +[领导人员](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)。 + + +## SIG Docs 团队和自动化 {#sig-docs-teams-and-automation} + +SIG 文档中的自动化服务依赖于两种不同的自动化机制: +GitHub 组和 OWNERS 文件。 + + +### GitHub 团队 {#github-teams} + +GitHub 上有两类 SIG Docs 团队： + +- `@sig-docs-{language}-owners` 包含批准人和牵头人 +- `@sig-docs-{language}-reviewers` 包含评阅人 + +可以在 GitHub 的评论中使用团队的名称 `@name` 来与团队成员沟通。 + +有时候 Prow 所定义的团队和 GitHub 团队有所重叠，并不完全一致。 +对于指派 Issue、PR 和批准 PR，自动化工具使用来自 `OWNERS` 文件的信息。 + + +### OWNERS 文件和扉页 + +Kubernetes 项目使用名为 prow 的自动化工具来自动处理 GitHub issue 和 PR。 +[Kubernetes website 仓库](https://github.com/kubernetes/website) 使用了两个 +[prow 插件](https://github.com/kubernetes/test-infra/blob/master/prow/plugins)： + +- blunderbuss +- approve + + +这两个插件使用位于 `kubernetes/website` 仓库顶层的 +[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) 文件和 +[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES) +文件来控制 prow 在仓库范围的工作方式。 + + +OWNERS 文件包含 SIG Docs 评阅人和批准人的列表。 +OWNERS 文件也可以存在于子目录中，可以在子目录层级重新设置哪些人可以作为评阅人和 +批准人，并将这一设定传递到下层子目录。 +关于 OWNERS 的更多信息，请参考 +[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md) +文档。 + + +此外，每个独立的 Markdown 文件都可以在其前言部分列出评阅人和批准人， +每一项可以是 GitHub 用户名，也可以是 GitHub 组名。 + +结合 OWNERS 文件及 Markdown 文件的前言信息，自动化系统可以给 PR 作者可以就应该 +向谁请求技术和文字评阅给出建议。 + + +## PR 是怎样被合并的 {#how-merging-works} + +当某个拉取请求（PR）被合并到用来发布内容的分支，对应的内容就会被发布到 http://kubernetes.io。 +为了确保我们所发布的内容的质量足够好，合并 PR 的权限仅限于 +SIG Docs 批准人。下面是合并的工作机制： + +- 当某个 PR 同时具有 `lgtm` 和 `approve` 标签，没有 `hold` 标签且通过所有测试时， + 该 PR 会被自动合并。 +- Kubernetes 组织的成员和 SIG Docs 批准人可以添加评论以阻止给定 PR 的自动合并， + 即通过 `/hold` 评论或者收回某个 `/lgtm` 评论实现这点。 +- 所有 Kubernetes 成员可以通过 `/lgtm` 评论添加 `lgtm` 标签。 +- 只有 SIG Docs 批准人可以通过评论 `/approve` 合并 PR。 + 某些批准人还会执行一些其他角色，例如 + [PR 管理者](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week) 或 + [SIG Docs 主席](#sig-docs-chairperson)等。 + +## {{% heading "whatsnext" %}} + + +关于贡献 Kubernetes 文档的更多信息，请参考： + +- [贡献新内容](/docs/contribute/overview/) +- [评阅内容](/docs/contribute/review/reviewing-prs) +- [文档样式指南](/docs/contribute/style/) diff --git a/content/zh/docs/contribute/participate/roles-and-responsibilties.md b/content/zh/docs/contribute/participate/roles-and-responsibilties.md new file mode 100644 index 0000000000..388029030e --- /dev/null +++ b/content/zh/docs/contribute/participate/roles-and-responsibilties.md @@ -0,0 +1,409 @@ +--- +title: 角色与责任 +content_type: concept +weight: 10 +--- + + + + +任何人都可以为 Kubernetes 作出贡献。随着你对 SIG Docs 的贡献增多，你可以申请 +社区内不同级别的成员资格。 +这些角色使得你可以在社区中承担更多的责任。 +每个角色都需要更多的时间和投入。具体包括： + +- 任何人（Anyone）：为 Kubernetes 文档作出贡献的普通贡献者。 +- 成员（Members）：可以对 Issue 进行分派和判别，对 PR 提出无约束性的评审意见。 +- 评审人（Reviewers）：可以领导对文档 PR 的评审，可以对变更的质量进行判别。 +- 批准人（Approvers）：可以领导对文档的评审并合并变更。 + + + + +## 任何人（Anyone） {#anyone} + +任何拥有 GitHub 账号的人都可以对 Kubernetes 作出贡献。SIG Docs +欢迎所有新的贡献者。 + +任何人都可以： + +- 在任何 [Kubernetes](https://github.com/kubernetes/) 仓库，包括 + [`kubernetes/website`](https://github.com/kubernetes/website) 上报告 Issue。 +- 对某 PR 给出无约束力的反馈信息 +- 为本地化提供帮助 +- 在 [Slack](http://slack.k8s.io/) 或 + [SIG Docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) + 上提出改进建议。 + +在[签署了 CLA](/zh/docs/contribute/new-content/overview/#sign-the-cla) 之后，任何人还可以： + +- 发起拉取请求（PR），改进现有内容、添加新内容、撰写博客或者案例分析 +- 创建示意图、图形资产或者嵌入式的截屏和视频内容 + +进一步的详细信息，可参见[贡献新内容](/zh/docs/contribute/new-content/)。 + + +## 成员（Members） {#members} + +成员是指那些对 `kubernetes/website` 提交很多拉取请求（PR）的人。 +成员都要加入 [Kubernetes GitHub 组织](https://github.com/kubernetes)。 + +成员可以： + +- 执行[任何人](#anyone)节区所列举操作 +- 使用 `/lgtm` 评论添加 LGTM (looks good to me（我觉得可以）) 标签到某个 PR + + {{< note >}} + 使用 `/lgtm` 会触发自动化机制。如果你希望提供不拘约束力的批准意见， + 直接回复 "LGTM" 也是可以的。 + {{< /note >}} +- 利用 `/hold` 评论来阻止某个 PR 被合并 +- 使用 `/assign` 评论为某个 PR 指定评审人 +- 对 PR 提供非约束性的评审意见 +- 使用自动化机制来对 Issue 进行判别和分类 +- 为新功能特性撰写文档 + + +### 成为一个成员 {#becoming-a-member} + +在你成功地提交至少 5 个 PR 并满足 +[相关条件](https://github.com/kubernetes/community/blob/master/community-membership.md#member) +之后： + + +1. 找到两个[评审人](#reviewers)或[批准人](#approvers)为你的成员身份提供 + [担保](/docs/contribute/advanced#sponsor-a-new-contributor)。 + + 通过 [Kubernetes Slack 上的 #sig-docs 频道](https://kubernetes.slack.com) 或者 + [SIG Docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) + 来寻找为你担保的人。 + + {{< note >}} + 不要单独发送邮件给某个 SIG Docs 成员或在 Slack 中与其私聊。 + 在提交申请之前，一定要先确定担保人。 + {{< /note >}} + +2. 在 [`kubernetes/org`](https://github.com/kubernetes/org/) 仓库 + 使用 **Organization Membership Request** Issue 模版登记一个 Issue。 + + +3. 告知你的担保人你所创建的 Issue，你可以： + + - 在 Issue 中 `@` 提及他们的 GitHub 用户名 + - 通过 Slack 或 email 直接发送给他们 Issue 链接 + + 担保人会通过 `+1` 投票来批准你的请求。一旦你的担保人批准了该请求， + 某个 Kubernetes GitHub 管理员会将你添加为组织成员。恭喜！ + + 如果你的成员请求未被接受，你会收到一些反馈。 + 当处理完反馈意见之后，可以再次发起申请。 + +4. 在你的邮件账户中接受来自 Kubernetes GitHub 组织发出的成员邀请。 + + {{< note >}} + GitHub 会将邀请发送到你的账户中所设置的默认邮件地址。 + {{< /note >}} + + +## 评审人（Reviewers） {#reviewers} + +评审人负责评审悬决的 PR。 +与成员所给的反馈不同，你必须处理评审人的反馈。 +评审人是 [@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) GitHub 团队的成员。 + +评审人可以： + +- 执行[任何人](#anyone)和[成员](#members)节所列举的操作 +- 评审 PR 并提供具约束性的反馈信息 + + {{< note >}} + 要提供非约束性的反馈，可以在你的评语之前添加 "Optionally: " 这样的说法。 + {{< /note >}} + +- 编辑代码中用户可见的字符串 +- 改进代码注释 + +你可以是 SIG Docs 的评审人，也可以是某个主题领域的文档的评审人。 + + +### 为 PR 指派评审人 {#assigning-reviewers-to-pull-requests} + +自动化引擎会为每个 PR 自动指派评审人。 +你可以通过为 PR 添加评论 `/assign [@_github_handle]` 来请求某个特定评审人来评审。 + +如果所指派的评审人未能及时评审，其他的评审人也可以参与进来。 +你可以根据需要指派技术评审人。 + +### 使用 `/lgtm` + +LGTM 代表的是 “Looks Good To Me （我觉得可以）”，用来标示某个 PR +在技术上是准确的，可以被合并。 +所有 PR 都需要来自某评审人的 `/lgtm` 评论和来自某批准人的 `/approve` +评论。 + +来自评审人的 `/lgtm` 评论是具有约束性的，会触发自动化设施添加 `lgtm` 标签。 + + +### 成为评审人 {#becoming-a-reviewer} + +当你满足[相关条件](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer)时， +你可以成为一个 SIG Docs 评审人。 +来自其他 SIG 的评审人必须为 SIG Docs 单独申请评审人资格。 + +申请过程如下： + + +1. 发起 PR，将你的 GitHub 用户名添加到 `kubernetes/website` 仓库中 + [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) + 文件的特定节。 + + {{ note }} + 如果你不确定要添加到哪个位置，可以将自己添加到 `sig-docs-en-reviews`。 + {{ /note }} + +2. 将 PR 指派给一个或多个 SIG Docs 批准人（`sig-docs-{language}-owners` + 下列举的用户名）。 + +请求被批准之后，SIG Docs Leads 之一会将你添加到合适的 GitHub 团队。 +一旦添加完成， [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) +会在处理未来的 PR 时，将 PR 指派给你或者建议你来评审某 PR。 + + +## 批准人（Approvers） {#approvers} + +批准人负责评审和批准 PR 以将其合并。 +批准人是 [@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) GitHub 团队的成员。 + + +批准人可以执行以下操作： + +- 执行列举在[任何人](#anyone)、[成员](#members)和[评审人](#reviewers)节区的操作 +- 通过使用 `/approve` 评论来批准、合并 PRs，发布贡献者所贡献的内容。 +- 就样式指南给出改进建议 +- 对文档测试给出改进建议 +- 对 Kubernetes 网站或其他工具给出改进建议 + +如果某个 PR 已有 `/lgtm` 标签，或者批准人再回复一个 `/lgtm` ，则这个 PR 会自动合并。 +SIG Docs 批准人应该只在不需要额外的技术评审的情况下才可以标记 `/lgtm`。 + + +### 批准 PR {#approving-pull-requests} + +只有批准人和 SIG Docs Leads 可以将 PR 合并到网站仓库。 +这意味着以下责任： + +- 批准人可以使用 `/approve` 命令将 PR 合并到仓库中。 + + {{< warning >}} + 不小心的合并可能会破坏整个站点。在执行合并操作时，务必小心。 + {{< /warning >}} + +- 确保所提议的变更满足[贡献指南](/docs/contribute/style/content-guide/#contributing-content)要求 + + 如果有问题或者疑惑，可以根据需要请他人帮助评审。 + +- 在 `/approve` PR 之前，须验证 Netlify 测试是否正常通过。 + + 批准之前必须通过 Netlify 测试 + +- 在批准之前，请访问 Netlify 的页面预览来确保变更内容可正常显示。 + +- 参与 [PR 管理者轮值排班](https://github.com/kubernetes/website/wiki/PR-Wranglers) + 执行时长为一周的 PR 管理。SIG Docs 期望所有批准人都参与到此轮值工作中。 + 更多细节可参见[做一周的 PR 管理者](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week)。 + + +### 成为批准人 {#becoming-an-approver} + +当你满足[一定条件](https://github.com/kubernetes/community/blob/master/community-membership.md#approver)时，可以成为一个 SIG Docs 批准人。 +来自其他 SIGs 的批准人也必须在 SIG Docs 独立申请批准人资格。 + + +申请流程如下： + +1. 发起一个 PR，将自己添加到 `kubernetes/website` 仓库中 + [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) + 文件的对应节区。 + + {{ note }} + 如果你不确定要添加到哪个位置，可以将自己添加到 `sig-docs-en-owners` 中。 + {{ /note }} + +2. 将 PR 指派给一个或多个 SIG Docs 批准人。 + +请求被批准之后，SIG Docs Leads 之一会将你添加到对应的 GitHub 团队。 +一旦添加完成， [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) +会在处理未来的 PR 时，将 PR 指派给你或者建议你来评审某 PR。 + diff --git a/content/zh/docs/contribute/participating.md b/content/zh/docs/contribute/participating.md deleted file mode 100644 index 5be3a872c8..0000000000 --- a/content/zh/docs/contribute/participating.md +++ /dev/null @@ -1,533 +0,0 @@ ---- -title: 参与 SIG Docs -content_type: concept -card: - name: contribute - weight: 40 ---- - - - - -SIG Docs 是 Kubernetes 项目中的一个 [special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md)， -总的来说，它负责编写、更新和维护 Kubernetes 文档。 - - -SIG Docs 欢迎所有贡献者提供内容和检视。任何人可以提交拉取请求（PR）， -欢迎对文档内容提交 issue 和 对正在进行中的 PR 进行评论。 - - -在 SIG Docs，你可以成为 [member](#members)、[reviewer](#reviewers) 或者 [approver](#approvers)。 -这些角色拥有更高的权限，并且需要承担批准和提交更改的责任。 -有关 Kubernetes 社区中的成员如何工作的更多信息，请参见 [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md)。 -本文档的其余部分概述了这些角色在 SIG Docs 中发挥作用的一些独特方式， -SIG Docs 负责维护 Kubernetes 最面向公众的方面之一 —— Kubernetes 网站和文档。 - - - - - -## 角色和责任 - - - -当一个 pull 请求被合并到用于发布内容的分支(当前为“master”)，该内容将发布并向全世界开放。 -为了确保发布内容的质量较高，每个 pull 请求需要 SIG Docs 的 approver 审批。 -它是这样工作的。 - - -- 当某个 pull request 拥有 `lgtm` 和 `approve` 标签， 并且没有 `hold` 标签时，这个 pull request 会自动合入。 -- Kubernetes 组织成员 和 SIG Docs 的 approvers 可以通过评论的方式阻止某个 pull request 自动合入（评论中包含 `/hold` 或 取消 `/lgtm` 的内容）。 -- 任何 Kubernetes 成员都可以通过在评论回复 `/lgtm` 来增加 `/lgtm` 标签。 -- 只有 SIG Docs 的 approver 可以在评论中回复 `/approve` 并触发合并。 - 某些 approver 还兼具其他角色，比如 [PR Wrangler](#pr-wrangler) 或 [SIG Docs chairperson](#sig-docs-chairperson)。 - - -关于 Kubernetes 组织成员和 SIG Docs approver 的区别，请参考 [Types of contributor](/docs/contribute#types-of-contributor)。 -以下部分将详细介绍这些角色及其内部的工作方式。 - -### Anyone - - -任何人可以针对 Kubernetes 的任何内容（包括文档）提交 issue。 - - -任何人想到提交 pull request，必须要签署 CLA。 否则 Kubernetes 项目则不能接受你的贡献。 - -### Members - - -任何 [Kubernetes 组织成员](https://github.com/kubernetes) 都可以检视 pull request。 -SIG Docs 组成员经常需要检视来自其他 SIG 的 pull request，以确保技术上的准确性。 - - -作何 Kubernetes 组织成员都可以在评论中增加 `/hold` 标签来阻止 PR 被合入。 -任何 Kubernetes 组织成员都可以移除 `/hold` 标签来让PR 合入（必须此前已有 `/lgtm` 和 `/approve` 标签）。 - - -#### 成为一个 member - - -在你成功的提交至少 5 个PR后，你就可以向 Kubernetes 组织提交申请 [membership](https://github.com/kubernetes/community/blob/master/community-membership.md#member)。 -按照如下流程： - - -1. 找到两个 reviewer 或 approver 为你提名。 - - 通过 [#sig-docs channel on the Kubernetes Slack instance](https://kubernetes.slack.com) 或者 - [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) - 来寻找为你提名的人。 - {{< note >}} - 不要单独发送邮件给某个人或在 Slack 中私聊。 - {{< /note >}} - -2. 在 `kubernetes/org` 仓库中提交一个 issue 发起请求。 - 按照[指导模板](https://github.com/kubernetes/community/blob/master/community-membership.md)填写请求。 - -3. 告知你的提名人，可以通过在 issue 中 `@` 或者直接发送给他们 issue 链接， - 这样他们可以过来投票（`+1`）。 - -4. 当请求被批准后，github 管理员团队成员会告诉你批准加入并且关闭 issue："Congratulations, you are now a member!"。 - - -如果因为某些原因你的申请没有被批准，会员委员会成员会告诉你原因并指导你如何继续申请。 - -### Reviewers - - -Reviewers 是 [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews) 成员。 - - -Reviewers 负责检视文档的 PR 并提供反馈。 - - -每个 PR 都会自动分配 reviewer，任何贡献者都可以在评论中回复 `/assign [@_github_handle]` - 来请求某个 reviewer 来检视。 -如果 reviewer 觉得没有问题且不需要进一步更改时，reviewer 会在评论中回复 `/lgtm` 。 - - -如果自动分配的 reviewer 未能及时检视，其他的 reviewer 也会参与。 -此外，你可以指定某个 reviewer 或者等他们回复 `/lgtm`。 - - -对于不重要的更改或者非技术性的检视，SIG Docs 的 [approver](#approvers) 也可以提供 `/lgtm` 标签。 - - -如果一个 reviewer 在评论中回复 `/approve` 会被自动忽略。 - - -关于如何成为 SIG Docs reviewer 以及其责任、时间承诺等更多内容，请参照 -[Becoming a reviewer or approver](#becoming-an-approver-or-reviewer)。 - - -#### 成为 reviewer - - -当你满足[需求](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer)时， -你就可以成为 SIG Docs 的 reviewer。 -其他 SIG 的 reviewer 也需要单独向 SIG Docs 申请。 - - -通过提交一个 PR 并把自己加到位于 `kubernetes/website` 仓库顶层的 [top-level OWNERS file](https://github.com/kubernetes/website/blob/master/OWNERS) 文件中的 `reviewers` 部分，指定一个或多个当前 SIG Docs 的 approver。 - - -如果你的 PR 被批准，你就成为了 SIG Docs reviewer 了。 -[K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) 会在接下来的 PR 中请求你检视。 - - -如果您的 PR 被批准，你就会加入 [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews) 组。只有 `kubernetes-website-admins` 组的成员才可以加入新成员。 - -### Approvers - - -approver 是 GitHub [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers) 组织成员。 -参考 [Teams and groups within SIG Docs](#teams-and-groups-within-sig-docs)。 - - -approver 有权限合入 PR，这意味着他们可以发布内容到 Kubernetes 网站。 -如果一个 approver 留下 `/approve` 评论，则代表他批准了 PR。 -如果非 approver 成员尝试批准，则会被自动忽略。 - - -如果某个 PR 已有 `/lgtm` 标签，approver 再回复一个 `/lgtm` ，则这个 PR 会自动合入。 -SIG Docs approver 应该只在不需要额外的技术检视的情况下才可以标记 `/lgtm`。 - - -关于如何成为 SIG Docs 的 approver 及其责任和时间承诺等信息，请参考 [Becoming a reviewer or approver](#becoming-an-approver-or-reviewer)。 - - -#### 成为 approver - - -当满足[要求](https://github.com/kubernetes/community/blob/master/community-membership.md#approver) 时，你可以成为 SIG Docs 的 approver。其他的 SIG 的 approver 要想成为 SIG Docs 的 approver 需要单独申请。 - - -通过提交一个 PR 并把自己加到位于 `kubernetes/website` 仓库顶层的 [top-level OWNERS file](https://github.com/kubernetes/website/blob/master/OWNERS) 文件中的 `approvers` 部分，指定一个或多个当前 SIG Docs 的 approver。 - - -一旦你的 PR 被批准，你就是一个 SIG Docs 的 approver 了。 - - -如果您的 PR 被批准，你就会加入[@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers) 组。只有 `kubernetes-website-admins` 组的成员才可以加入新成员。 - - -#### Approver 职责 - - -Approvers 通过查看拉取请求（pr）并将其合并到网站仓库中来完善文档。因为此角色具有其他特权，所以 approvers 还具有其他职责： - - -- Approvers 可以使用 `/approve` 命令将 PR 合并到仓库中。 - - 粗心的合并会破坏站点，因此请确保在合并某些内容时，您是清楚的。 - -- 确保建议的更改符合贡献准则。 - - 如果您有任何疑问，或者不确定某个问题，请随时联系他人进行审核。 - -- 在 `/approve` PR 之前，请验证 netlify 测试是否通过。 - - 批准之前必须确保 Netlify 测试通过 - -- 请访问 netlify 页面预览 PR，确保批准前一切正常。 - - -#### PR 协调者 - - -每个 SIG Docs approver 都会参与 [PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers)。 -所有 SIG Docs approver 都会参与轮值。 -更多信息，请参考[做一周的PR协调者](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week)。 - - -#### SIG Docs 主席 - - -每个 SIG，包括 SIG Docs，都会选出 1 位或多位成员作为主席。 -主席会成为 SIG Docs 和其他 Kubernetes 组织的联络接口人。 -他们需要了解整个 Kubernetes 项目，并明白 SIG Docs 如何运作。 -如需查询当前的主席，请查阅 [Leadership](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)。 - - -## SIG Docs 团队和自动化 - - -SIG 文档中的自动化依赖于两种不同的自动化机制: -GitHub 组和 OWNERS 文件。 - -### GitHub groups - - -SIG Docs 组定义了两个 GitHub 组： - - - [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers) - - [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews) - - -可以在 GitHub 的评论中 `@name` 他们来与他们沟通。 - - -这些团队与自动化工具使用的组有所重叠，但并不完全匹配。 -对于分配 issue、拉请求和批准 PR，自动化使用来自 OWNERS 文件的信息。 - - -### OWNERS 文件和扉页 - - -Kubernetes 项目使用名为 prow 的自动化工具来处理 GitHub issue 和 PR。 -[Kubernetes website repository](https://github.com/kubernetes/website) 使用了两个 -[prow 插件](https://github.com/kubernetes/test-infra/blob/master/prow/plugins.yaml#L210)： - -- blunderbuss -- approve - - -这两个插件使用位于 `kubernetes/website` 仓库顶层的 -[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) 和 -[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES) 来控制工作流程。 - - -OWNERS 文件包含 SIG Docs reviewer 和 approver 的列表。 -OWNERS 文件也可以存在于子目录中中，可以重写 reviewer 和 approver，并且它自动继承上级。 -关于 OWNERS 的更多信息，请参考 [OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md)。 - - -此外，一个单独的 Markdown 格式的文件将会列出 reviewer 和 approver（扉页），或者列出 -其 GitHub 用户名 或者列出其组名。 - - -结合 OWNERS 文件及扉页可以给 PR 作者提供向谁请求检视的建议。 - - - -## {{% heading "whatsnext" %}} - - - -关于贡献 Kubernetes 的更多文档，请参考： - -- [Start contributing](/docs/contribute/start/) -- [Documentation style](/docs/contribute/style/) - - - - diff --git a/content/zh/docs/contribute/start.md b/content/zh/docs/contribute/start.md deleted file mode 100644 index 4e3e65136b..0000000000 --- a/content/zh/docs/contribute/start.md +++ /dev/null @@ -1,639 +0,0 @@ ---- -title: 开始贡献 -slug: start -content_type: concept -weight: 10 -card: - name: contribute - weight: 10 ---- - - - - - -如果您想要为 Kubernetes 文档做贡献，本页面的内容和链接的主题能够给您帮助。您不必是一位开发者或者技术作者，也同样可以为 Kubernetes 文档及其用户体验带来巨大的影响！您只需要有一个 [Github 账号](https://github.com/join) 和一个浏览器。 - -如果您在寻找有关如何开始向 Kubernetes 仓库贡献代码的信息，请参考 [Kubernetes 社区指南](https://github.com/kubernetes/community/blob/master/governance.md)。 - - - - - - - -## 关于我们文档的基础知识 - - -Kubernetes 文档是以 Markdown 形式编写的，使用 Hugo 进行部署。源码位于 Github 的 [https://github.com/kubernetes/website](https://github.com/kubernetes/website)。大部分文档源码位于 `/content/en/docs/`。有些参考文档是由 `update-imported-docs/` 目录内的脚本自动生产的。 - -您可以提交 issue、编辑内容或者对其他人的提交内容进行复审，这些都可以在 Github 网站上完成。您也可以使用 Github 内置的历史功能和查询工具。 - - -并非所有的任务都可以通过 Github UI 完成，这些任务会在[中级](/docs/contribute/intermediate/)和[高级](/docs/contribute/advanced/)文档贡献指南中讨论 - -### 参与文档特别兴趣小组（SIG Docs） - - -Kubernetes 文档是由 {{< glossary_tooltip text="特别兴趣小组" term_id="sig" >}} (SIG) 维护的，该小组名为 SIG Docs。我们通过 Slack 频道、邮件列表和网络视频周会进行[交流](#参与-sig-docs-讨论)。欢迎新的参与者加入。更多信息，请参考[参与 SIG Docs](/docs/contribute/participating/)。 - - -### 内容指南 - -SIG Docs 社区创建了有关 Kubernetes 文档中允许哪种内容的指南。查看[文档内容指南](/docs/contribute/style/content-guide/)确定是否允许您要进行的内容贡献。您可以在 [#sig-docs](#参与-sig-docs-讨论) 频道中询问有关允许内容的问题。 - - -### 风格指南 - -我们维护了一个[风格指南](/docs/contribute/style/style-guide/)页面，上面有关于 SIG Docs 社区对于语法、句法、源格式和排版的约定。在您做首次贡献前或者在有疑问的时候请先查阅风格指南。 - - -风格的变化是由 SIG Docs 组共同决定的。如您想提交变更或增加内容，请将内容[添加到议题](https://docs.google.com/document/d/1zg6By77SGg90EVUrhDIhopjZlSDg2jCebU-Ks9cYx0w/edit#)并参与会议讨论。更多信息，参见[进阶贡献](/docs/contribute/advanced/)主题。 - - -### 页面模板 - -我们使用页面模板来控制文档页面。需要确保您理解这些模版是如何工作的，请阅读[使用页面模板](/docs/contribute/style/page-templates/)。 - -### Hugo 短代码 - - -Kubernetes 文档使用 Hugo 将 Markdown 转换成 HTML。我们使用标准的 Hugo 短代码，同时也会有部分为 Kubernetes 定制化的代码。有关如何使用短代码的信息，请参见[自定义 Hugo 短代码](/docs/contribute/style/hugo-shortcodes/)。 - -### 多语言 - - -在 `/content/` 目录中有文档源码的多语言版本。每个语言拥有其自己的目录，采用 [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php) 的两位编码命名。例如，英文文档源码位于 `/content/en/docs/` 目录。 - -更多关于对多语言文档做贡献的信息，请参考中级贡献指南中的["本地化内容"](/docs/contribute/intermediate#localize-content)。 - - -如果您有兴趣开始一个新的本地化语言项目，请参考["本地化"](/docs/contribute/localization/)。 - -## 提出可操作的 issues - - -任何拥有 Github 账号的人都能对于 Kubernetes 提出可行的 issue（或者 bug report）。如果发现问题，即便您不知道如何修复它，请[提出 issue](#how-to-file-an-issue)。除非您发现微小的错误的情况，例如发现了一个拼写错误，您想自己进行修复。在这种情况下，您可以[修复它](#improve-existing-content)，而不用先提出一个 bug。 - -### 如何提出 issue - - -- **对于已有页面** - - 如果您在已有的 [Kubernetes 文档](/docs/)页面，在页面底部直接点击 **创建 Issue** 按钮。如果您当前未登录 Github，那么请登录。Github 文档表单会带着预填的信息出现。 - - 使用 Markdown 格式，填写尽可能多的详细信息。在方括号 (`[ ]`) 中，使用 `x` 代码选择了该选项。如果您提交了修复 issue 的方法，也填在里面。 - - -- **请求创建一个新页面** - - 如果认为有些内容应该存在，但您不知道应该将这些内容存放在哪里，或者任何不适合放在现有页面中，那么也可以提出一个 issue。您可以选择通过内容相近的页面创建 issue，或者直接在 [https://github.com/kubernetes/website/issues/new/](https://github.com/kubernetes/website/issues/new/)中记录 issue。 - - -### 如何记录好的 issues - -要确保我们能理解您的 issue，并能付诸行动，请谨记如下指南： - - -- 使用 issue 模板，尽可能填写详细的信息。 -- 清楚地描述该 issue 对用户造成的具体影响。 -- 限制 issue 的范围，以提交给合理的工作组。如果问题范围很大，将其拆分成若干个 issues。 - - 例如，“修复安全文档”就是一个不可执行的 issue，但 “为'限制网络访问'主题添加详细信息”就是可执行的。 -- 如果 issue 与另一个 issue 或者拉取请求（PR）有关，您可以通过 issue 的完整 URL 或者 PR 的序号（以 `#` 为前缀）进行关联。例如 `如 #987654`。 -- 保持尊重，避免发泄。例如，“关于 X 的文档很差”就是无用且不可执行的反馈。[行为准测](/community/code-of-conduct/) 也适用于 Kubernetes Github 仓库的交互。 - - -## 参与 SIG Docs 讨论 - -SIG Docs 团队交流采用如下机制： - -- [加入 Kubernetes 的 Slack 工作组](http://slack.k8s.io/)，然后加入 `#sig-docs` 频道，在那里我会实时讨论文档的 issues。一定要做自我介绍！ -- [加入 `kubernetes-sig-docs` 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)，在这里会有广泛的讨论以及官方决策的记录。 -- 参与 [SIG Docs 视频周例会](https://github.com/kubernetes/community/tree/master/sig-docs)，会通过 Slack 频道和邮件列表通知。 - 目前通过 Zoom 进行会议，所以您需要下载 [Zoom 客户端](https://zoom.us/download)，或者通过手机拨入。 - - - -{{< note >}} -您也可以查看 [Kubernetes 社区会议日历](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles)。 -{{< /note >}} - - -## 改进现有内容 - -要改进现有的内容，您可以在创建 _fork_ 之后起草一个 _拉取请求（PR）_ 。这两个术语是 [Github 专用的](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/)。 -出于本主题的目的，您无需了解有关它们的所有信息，因为您可以通过浏览器做所有的事情。当您继续阅读[贡献者中级指南](/docs/contribute/intermediate/)，您会需要更多 Git 术语的背景知识。 - - - -{{< note >}} -**Kubernetes 代码开发者**：如果您在撰写 Kubernetes 新版本的新功能文档，流程会稍有不同。 -关于流程指南和最后期限的信息，请参阅[编写功能文档](/docs/contribute/intermediate/#sig-members-documenting-new-features)。 -{{< /note >}} - - -## 签署 CNCF CLA {#sign-the-cla} - -在贡献 Kubernetes 的代码或文档前，您 **必须** 阅读[贡献者指南](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md)，并[签署贡献者许可协议（CLA）](https://github.com/kubernetes/community/blob/master/CLA.md)。 -别担心 -- 不需要太多时间！ - -### 开始贡献 - - -如果您发现了一些想要马上修复的问题，只需要遵循如下指南。您不需要[提出一个 issue](#file-actionable-issues)（尽管你当然可以这么做）。 - -如果您想从处理现有的 issue 开始，前往 [https://github.com/kubernetes/website/issues](https://github.com/kubernetes/website/issues) 找一些有 `good first issue` 标签的 issue （您可以使用[这个](https://github.com/kubernetes/website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 快捷方式)。阅读评论，确保针对此 issue 没有打开的 PR，并且没有人留言说他们最近正在解决这个 issue （3 天是个很好的规则）。留言说您会去解决这个 issue。 - - -### 选择使用的 Git 分支 - -提交 PR 最重要的方面就是选择您工作所基于的基础分支。使用如下指南来做决定： - - -- 用 `master` 来解决以及发布的内容中的问题，或者对于已经存在的内容进行改进。 -- 使用 release 分支（比如 `dev-{{< release-branch >}}` 用于 {{< release-branch >}} 发布）来撰写新的特性或者下个版本还未发布的变更说明。 -- 使用 SIG Docs 已经同意的 feature 分支来协作对现有文档进行重大改进或更改，包括内容重组或网站外观的更改。 - -如果您还不确定应该使用哪个分支，在 Slack 上询问 `#sig-docs` 或者参与 SIG Docs 周例会来确认。 - - -### 提交 PR - - - -按照如下步骤提交 PR 来改善 Kubernetes 文档。 - -1. 在您提交 issue 的页面上，点击右上角的铅笔图标。新的页面就会出现，上面会有一些帮助信息。 -2. 如果您从未创建过 Kubernetes 文档仓库的 fork，会提示您需要创建。请在您的 Github 账号下创建 fork，而不是在您所在的组织下创建。fork URL 通常是这样的 `https://github.com//website`，除非您已经有一个同名的仓库，那样会造成冲突。 - 您创建 fork 的原因是您无权直接将分支推送到确定的 Kubernetes 仓库。 - -3. Github Markdown 编辑器会载入着文档源码一起出现。根据实际情况撰写变化内容。在编辑器下方填写 **Propose file change（建议修改文件）** 表格。第一个区域需要填写提交说明消息，不能超过 50 个字符。第二个区域是可选的，也能够填写更多详细信息。 - - {{< note >}} -不要把 Github issues 或者 PR 的关联信息放在您的提交说明消息中。您可以之后把这些内容添加到 PR 的描述中。 -{{< /note >}} - - - 点击 **建议修改文件（Propose file change）** 按钮。变更会保存为您 fork 新分支（通常会自动命名为 `patch-1`）中的一个提交内容。 - - -4. 接下来屏幕会总结您的变更，将您的新分支（**head fork** 和 **compare** 选择框）与 **base fork** - 和 **base** 分支(默认是 `kubernetes/website` 的 `master` 分支)进行比较。您可以更改选择框，但现在请不要这么做。看一下屏幕底部显示的变化内容，如果看起来没问题，点击 **创建 PR（Create pull request）** 按钮。 - - {{< note >}} -如果您现在还不想创建 PR，也可以稍后再做，通过浏览 Kubernetes 网站代码仓库或者您 fork 仓库的网站主页 URL。Github 网站会检查到您推送了一个新分支到 fork，并提示创建 PR。 -{{< /note >}} - - -5. **Open a pull request（打开一个 PR）** 屏幕出现了。PR 的主题和提交说明的内容一致， - 如有需要您也可以修改。主体内容会自动填充您的扩展提交消息（如果存在）和一些模板文本。 - 阅读模板文本并填写要求的详细信息，然后删除额外的模板文本。 - 如果在描述中添加 `fixes #<000000>` 或者 `closes #<000000>`，其中 `#<000000>` 是相关问题的编号，则当PR合并时，GitHub 将自动关闭该问题。 - 保留选中 **Allow edits from maintainers（允许维护者编辑）** 复选框。 - 单击 **Create pull request（创建拉取请求）** 按钮。 - - - 祝贺您！您的 PR 就出现在了[拉取请求](https://github.com/kubernetes/website/pulls) 中。 - - 几分钟后，您可以预览 PR 所带来的变化。前往您 PR 的 **Conversation（对话）** 标签页， - 点击 `deploy/netlify` 测试的 **Details（详细信息）** 链接，它在页面底部附件。 - 默认会在同一个浏览器窗口中打开。 - - {{< note >}} - 请将 PR 请求限制为每种 PR 只能使用一种语言。例如，如果您需要对多种语言的同一代码示例进行相同的更改，请为每种语言打开一个单独的 PR。 - {{< /note >}} - - -6. 等待复审。通常，复审人员会由 `k8s-ci-robot` 建议指定。如果复审人员建议您修改，您可以 - 前往 **Files changed（改变的文件内容）** 标签页，点击任意 PR 中改变的文件页面上的铅笔图标。 - 保存更改的文件时，将在 PR 监视的分支中创建新的提交。如果您正在等待复审者审核更改， - 请每 7 天主动与复审者联系一次。您也可以进入 #sig-docs Slack 频道，这是寻求有关 PR 审查的帮助的好地方。 - -7. 如果修改被接受，复审人员会合并您的 PR，修改就会在几分钟后在 Kubernetes 网站上生效。 - - -这是提交 PR 的唯一方式。如果您已经是一名 Git 和 Github 的高级用户，您也可以使用本地 GUI 或者 -Git 命令行。关于使用 Git 客户端的基础会在[中级](/docs/contribute/intermediate/) 贡献者指南中讨论。 - - -## 复审文档 PR - -就算不是批注者或者复审者，也同样可以复审 PR。复审人员并不是"固定"的，意味着您单独的评审并不会让 PR 合并。然而，这依然对我们是很有帮助的。即使您没有留下任何评审意见，您可以了解 PR 的规范和礼仪，并习惯工作流程。 - - -1. 前往 [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls)。 - 请会看到一个列表，里面包含了所有对于 Kubernetes 网站和文档提的 PR。 - - -2. 默认情况下，使用的筛选器是 `open`，所以您不会看见已经关闭或合并的 PR。 - 最好使用 `cncf-cla: yes` 筛选器，并且对于第一次复审来说，最好加上 `size/S` - 或者 `size/XS`。`size` 标签会根据 PR 修改的代码行数自动生成。 - 您可以通过页面顶端的选择框应用筛选器，或者使用 - [快捷方式](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+yes%22+label%3Asize%2FS) - 来查找所有小型 PR。所有筛选条件都是 `与` 的，所以您不能在一次查询中同时查找 `size/XS` 和 `size/S` 的结果。 - - -3. 前往 **Files changed（文件修改）** 标签页。查看 PR 中的变化部分，如果适用，也看一下关联的问题。如果您发现问题或者可以改进的空间， - 将鼠标悬浮在那一行并点击前面出现的 `+` 加号。 - - 你可以留下评论，选择 **Add single comment（仅添加评论）** 或者也可以 **Start a review（开始复审）**。典型来说，开始复审更好，因为这样您就可以在多行下留下评论，并且只有在完成复审后统一提交并通知 PR 的作者，而不是每一条评论都发送通知。 - - -4. 完成后，点击页面顶端但 **Review changes（复审修改）** 按钮。您可以总结复审，并且可以选择comment（评论），approve（批准），或者 request changes（请求变更）。新的贡献者应该选择 **Comment（评论）**。 - - -感谢您对于 PR 的复审工作！当您对于项目还是新人时，最好在拉取请求评论中征求反馈意见。Slack 的 `#sig-docs` 频道就是一个征求意见好去处。 - -## 撰写博客文章 - - -任何人都可以撰写博客并提交复审。博客文章不应具有商业性质，而应包含广泛适用于 Kubernetes 社区的内容。 - -要提交博客文章，您可以选择使用 [Kubernetes 博客提交表单](https://docs.google.com/forms/d/e/1FAIpQLSdMpMoSIrhte5omZbTE7nB84qcGBy8XnnXhDFoW0h7p2zwXrw/viewform)或者按如下步骤进行： - - -1. 如果您还未签署 CLA，请[签署 CLA](#sign-the-cla)。 -2. 查看现有博客文章的 Markdown 格式，位于[网站代码仓库](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts)。 -3. 在您选择的文本编辑器中写下您的博客文章。 -4. 在步骤 2 的相同链接中，点击 **Create new file（创建新文件）** 按钮。 - 将您的内容粘贴到编辑器中。将文件命名为与博客文章的标题的名称， - 但不要将日期放在文件名中。博客复审人员将与您一起确定最终文件名和博客发布日期。 -5. 保存文件时，Github 将引导您完成 PR 过程。 -6. 博客复审人员会对您的提交对内容进行复审，并与您一起完成反馈意见和最终的详细信息。 - 博客文章获得批准后，博客将会安排时间进行发布。 - - -## 提交案例研究 - -案例研究强调组织如何使用 Kubernetes 解决实际问题。它们是由 Kubernetes 市场团队共同撰写的，由 {{< glossary_tooltip text="CNCF" term_id="cncf" >}} 进行处理。 - -看一下[现有案例研究](https://github.com/kubernetes/website/tree/master/content/en/case-studies)的源码。 -使用 [Kubernetes 案例研究提交表](https://www.cncf.io/people/end-user-community/)提交您的提案。 - - - -## {{% heading "whatsnext" %}} - - - -当您对本主题中讨论的所有任务感到满意，并且您希望以更深入的方式与 Kubernetes 文档团队合作，请阅读[中级贡献者指南](/docs/contribute/intermediate/)。 - - diff --git a/content/zh/docs/contribute/suggesting-improvements.md b/content/zh/docs/contribute/suggesting-improvements.md new file mode 100644 index 0000000000..63383e5637 --- /dev/null +++ b/content/zh/docs/contribute/suggesting-improvements.md @@ -0,0 +1,120 @@ +--- +title: 提出内容改进建议 +slug: suggest-improvements +content_type: concept +weight: 10 +card: + name: 贡献 + weight: 20 +--- + + + + + +如果你发现 Kubernetes 文档中存在问题，或者你有一个关于新内容的想法，可以考虑 +提出一个问题（issue）。你只需要具有 [GitHub 账号](https://github.com/join)和 Web +浏览器就可以完成这件事。 + +在大多数情况下，Kubernetes 文档的新工作都是开始于 GitHub 上的某个问题。 +Kubernetes 贡献者会审阅这些问题并根据需要对其分类、打标签。 +接下来，你或者别的 Kubernetes 社区成员就可以发起一个带有变更的拉取请求， +以解决这一问题。 + + + + +## 创建问题 {#opening-an-issue} + +如果你希望就改进已有内容提出建议，或者在文档中发现了错误，请创建一个问题（issue）。 + +1. 滚动到页面底部，点击“报告问题”按钮。浏览器会重定向到一个 GitHub 问题页面，其中 + 包含了一些预先填充的内容。 +1. 请描述遇到的问题或关于改进的建议。尽可能提供细节信息。 +1. 点击 **提交新问题**. + +提交之后，偶尔查看一下你所提交的问题，或者开启 GitHub 通知。 +评审人（reviewers）和其他社区成员可能在针对所提问题采取行动之前，问一些问题。 + + +## 关于新内容的建议 + +如果你对新内容有想法，但是你有不确定这些内容应该放在哪里，你仍可以提出问题。 + +- 在预期的节区中选择一个现有页面，点击 **创建 issue**. +- 前往 [GitHub Issues 页面](https://github.com/kubernetes/website/issues/new/)， + 直接记录问题。 + + + +## 如何更好地记录问题 + +在记录问题时，请注意以下事项： + +- 提供问题的清晰描述，描述具体缺失的内容、过期的内容、错误的内容或者需要改进的文字。 +- 解释该问题对用户的特定影响。 +- 将给定问题的范围限定在一个工作单位范围内。如果问题牵涉的领域较大，可以将其分解为多个 + 小一点的问题。例如："Fix the security docs" 是一个过于宽泛的问题，而 + "Add details to the 'Restricting network access' topic" + 就是一个足够具体的、可操作的问题。 +- 搜索现有问题的列表，查看是否已经有相关的或者类似的问题已被记录。 +- 如果新问题与某其他问题或 PR 有关联，可以使用其完整 URL 或带 `#` 字符的 PR 编号 + 来引用之。例如：`Introduced by #987654`。 +- 遵从[行为准则](/community/code-of-conduct/)。尊重同行贡献者。 + 例如，"The docs are terrible" 就是无用且无礼的反馈。 +