From b9c0f40175db22526d525cc8f86a43fb23e35361 Mon Sep 17 00:00:00 2001 From: Michael Date: Thu, 12 May 2022 13:24:04 +0800 Subject: [PATCH] updated 3 files in content/zh/docs/contribute/new-content --- .../zh/docs/contribute/new-content/_index.md | 196 ++++++++++++++++++ .../docs/contribute/new-content/overview.md | 122 ----------- .../contribute/participate/pr-wranglers.md | 84 ++++++-- 3 files changed, 263 insertions(+), 139 deletions(-) delete mode 100644 content/zh/docs/contribute/new-content/overview.md diff --git a/content/zh/docs/contribute/new-content/_index.md b/content/zh/docs/contribute/new-content/_index.md index e498891fa9..d9136f1631 100644 --- a/content/zh/docs/contribute/new-content/_index.md +++ b/content/zh/docs/contribute/new-content/_index.md @@ -1,4 +1,200 @@ --- title: 贡献新内容 +content_type: 概念 +main_menu: true weight: 20 --- + + + + + + +本节包含你在贡献新内容之前需要知晓的信息。 + + + + +{{< mermaid >}} +flowchart LR + subgraph second[开始之前] + direction TB + S[ ] -.- + A[签署 CNCF CLA] --> B[选择 Git 分支] + B --> C[每个 PR 一种语言] + C --> F[检查贡献者工具] + end + subgraph first[基本知识] + direction TB + T[ ] -.- + D[用 markdown 编写文档
并用 Hugo 构建网站] --- E[GitHub 源代码] + E --- G['/content/../docs' 文件夹包含
多语言文档] + G --- H[评审 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,C,D,E,F,G,H grey +class S,T spacewhite +class first,second white +{{}} + + + +***插图 - 贡献新内容准备工作*** + +上图描述了你在提交新内容之前需要知晓的信息。 +详细信息见下文。 + + + + +## 基本知识 + +- 使用 Markdown 编写 Kubernetes 文档并使用 [Hugo](https://gohugo.io/) 构建网站。 +- Kubernetes 文档使用 [CommonMark](https://commonmark.org/) 作为 Markdown 的风格。 +- 源代码位于 [GitHub](https://github.com/kubernetes/website) 仓库中。 + 你可以在 `/content/zh/docs/` 目录下找到 Kubernetes 文档。 + 某些参考文档是使用位于 `update-imported-docs/` 目录下的脚本自动生成的。 +- [页面内容类型](/zh/docs/contribute/style/page-content-types/)使用 Hugo 描述文档内容的呈现。 + + + +- 你可以使用 [Docsy 短代码](https://www.docsy.dev/docs/adding-content/shortcodes/) + 或[定制的 Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/)贡献 Kubernetes 文档。 +- 除了标准的 Hugo 短代码外, + 我们还在文档中使用一些[定制的 Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/)来控制内容的呈现。 +- 文档的源代码有多种语言形式,位于 `/content/` 目录下。 + 每种语言都有一个自己的目录,用两个字母表示,这两个字母是基于 + [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)来确定的。 + 例如,英语文档的源代码位于 `/content/en/docs/` 目录下。 +- 关于为多语言文档做贡献以及如何开始新翻译的详细信息, + 可参考[本地化文档](/zh/docs/contribute/localization)。 + + + +## 开始之前 {#before-you-begin} + +### 签署 CNCF CLA {#sign-the-cla} + +所有 Kubernetes 贡献者**必须**阅读[贡献者指南](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md) +并[签署贡献者授权同意书 (Contributor License Agreement, CLA)](https://github.com/kubernetes/community/blob/master/CLA.md)。 + +若贡献者尚未签署 CLA,其发起的 PR 将无法通过自动化测试。 +你所提供的姓名和邮件地址必须与 `git config` 中配置的完全相同, +而且你的 git 用户名和邮件地址必须与用来签署 CNCF CLA 的信息一致。 + + + +### 选择要使用的 Git 分支 + +在发起 PR 时,你需要预先知道基于哪个分支来开展工作。 + +场景 | 分支 +:---------|:------------ +针对当前发行版本的,对现有英文内容的修改或新的英文内容 | `main` + 针对功能特性变更的内容 | 分支对应于功能特性变更的主要和次要版本,分支名称采用 `dev-` 的模式。例如,如果某功能特性在 `v{{< skew nextMinorVersion >}}` 版本发生变化,则对应的文档变化要添加到 `dev-{{< skew nextMinorVersion >}}` 分支。 + 其他语言的内容(本地化) | 基于本地化团队的约定。参见[本地化分支策略](/zh/docs/contribute/localization/#branching-strategy)了解更多信息。 + +如果你仍不能确定要选择哪个分支,请在 Slack 的 `#sig-docs` 频道上提出问题。 + + + +{{< note >}} +如果你已经提交了 PR,并且发现所针对的分支选错了,你(且只有作为提交人的你)可以更改分支。 +{{< /note >}} + + + +### 每个 PR 牵涉的语言 + +请确保每个 PR 仅涉及一种语言。 +如果你需要对多种语言下的同一代码示例进行相同的修改,也请为每种语言发起一个独立的 PR。 + + + +## 为贡献者提供的工具 + +`kubernetes/website` 仓库的[文档贡献者工具](https://github.com/kubernetes/website/tree/main/content/zh/docs/doc-contributor-tools)目录中包含了一些工具, +有助于使你的贡献过程更为顺畅。 diff --git a/content/zh/docs/contribute/new-content/overview.md b/content/zh/docs/contribute/new-content/overview.md deleted file mode 100644 index 76dd64c211..0000000000 --- a/content/zh/docs/contribute/new-content/overview.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: 贡献新内容概述 -linktitle: 概述 -content_type: concept -main_menu: true -weight: 5 ---- - - - - -本节包含贡献新内容之前你需要知晓的一些信息。 - - - - -## 基本知识 - -- 使用 Markdown 来编写 Kubernetes 文档并使用 [Hugo](https://gohugo.io/) 来构建网站 -- 源代码位于 [GitHub](https://github.com/kubernetes/website) 仓库中。 - 你可以在 `/content/en/docs/` 目录下找到 Kubernetes 文档。 - 某些参考文档是使用位于 `update-imported-docs/` 目录下的脚本自动生成的。 -- [页面内容类型](/zh/docs/contribute/style/page-content-types/)使用 Hugo 描述文档内容的表现。 -- 除了基本的 Hugo 短代码(shortcodes)外,我们还在文档中使用一些 - [定制的 Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/)以控制内容的表现。 -- 文档的源代码有多种语言形式,位于`/content/` 目录下。 - 每种语言都有自己的由两个字母代表的目录,这两个字母是基于 - [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)来确定的。 - 例如,英语文档源码位于`/content/en/docs/` 目录下。 -- 关于在多种语言中为文档做贡献的详细信息,以及如何启动一种新的语言翻译, - 可参考[本地化](/zh/docs/contribute/localization)文档。 - - -## 开始之前 {#before-you-begin} - -### 签署 CNCF CLA {#sign-the-cla} - -所有 Kubernetes 贡献者 **必须** 阅读 -[贡献者指南](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md) -并[签署贡献者授权同意书(Contributor License Agreement,CLA)](https://github.com/kubernetes/community/blob/master/CLA.md)。 - -来自尚未签署 CLA 的贡献者的 PR 无法通过自动化服务的测试。 -你所提供的姓名和邮件地址必须与 `git config` 中所找到的完全相同, -而且你的 git 用户名和邮件地址必须与用来签署 CNCF CLA 的一致。 - - -### 选择要使用的分支 - -在发起拉取请求时,你需要预先知道要基于哪个分支来开展工作。 - -场景 | 分支 -:---------|:------------ -针对当前发行版本的,对现有英文内容的修改或新的英文内容 | `main` -针对功能特性变更的内容 | 功能特性所对应的版本所对应的分支,分支名字模式为 `dev-`。例如,如果某功能特性在 `v{{< skew nextMinorVersion >}}` 版本发生变化,则对应的文档变化要添加到 ``dev-{{< skew nextMinorVersion >}}`` 分支。 -其他语言的内容(本地化)| 基于本地化团队的约定。参见[本地化分支策略](/zh/docs/contribute/localization/#branching-strategy)了解更多信息。 - -如果你仍不能确定要选择哪个分支,请在 `#sig-docs` Slack 频道上提问。 - - -{{< note >}} -如果你已经提交了你的 PR,并且你发现所针对的分支选错了,你(且只能是你)可以重新选择分支。 -{{< /note >}} - - -### 每个 PR 牵涉的语言 - -请限制每个 PR 仅涉及一种语言。 -如果你需要对多种语言下的同一代码示例进行相同的修改,也请为每种语言发起一个独立的 PR。 - - - -## 为贡献者提供的工具 - -`kubernetes/website` 仓库的 -[文档贡献者工具](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools) -目录中包含了一些工具,能够助你的贡献过程更为顺畅。 - diff --git a/content/zh/docs/contribute/participate/pr-wranglers.md b/content/zh/docs/contribute/participate/pr-wranglers.md index bf08aa770a..d9af8cc1d3 100644 --- a/content/zh/docs/contribute/participate/pr-wranglers.md +++ b/content/zh/docs/contribute/participate/pr-wranglers.md @@ -16,10 +16,10 @@ SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilites/#app This section covers the duties of a PR wrangler. For more information on giving good reviews, see [Reviewing changes](/docs/contribute/review/). --> SIG Docs 的[批准人(Approvers)](/zh/docs/contribute/participate/roles-and-responsibilites/#approvers)们每周轮流负责 -[管理仓库的 PRs](https://github.com/kubernetes/website/wiki/PR-Wranglers)。 +[管理仓库的 PR](https://github.com/kubernetes/website/wiki/PR-Wranglers)。 -本节介绍 PR 管理者的职责。关于如何提供较好的评审意见,可参阅 -[评审变更](/zh/docs/contribute/review/). +本节介绍 PR 管理者的职责。关于如何提供较好的评审意见, +可参阅[评审变更](/zh/docs/contribute/review/)。 @@ -31,16 +31,6 @@ Each day in a week-long shift as PR Wrangler: - Triage and tag incoming issues daily. See [Triage and categorize issues](/docs/contribute/review/for-approvers/#triage-and-categorize-issues) for guidelines on how SIG Docs uses metadata. - Review [open pull requests](https://github.com/kubernetes/website/pulls) for quality and adherence to the [Style](/docs/contribute/style/style-guide/) and [Content](/docs/contribute/style/content-guide/) guides. - Start with the smallest PRs (`size/XS`) first, and end with the largest (`size/XXL`). Review as many PRs as you can. -- Make sure PR contributors sign the [CLA](https://github.com/kubernetes/community/blob/master/CLA.md). - - Use [this](https://github.com/zparnold/k8s-docs-pr-botherer) script to remind contributors that haven’t signed the CLA to do so. -- Provide feedback on changes and ask for technical reviews from members of other SIGs. - - Provide inline suggestions on the PR for the proposed content changes. - - If you need to verify content, comment on the PR and request more details. - - Assign relevant `sig/` label(s). - - If needed, assign reviewers from the `reviewers:` block in the file's front matter. -- Use the `/approve` comment to approve a PR for merging. Merge the PR when ready. - - PRs should have a `/lgtm` comment from another member before merging. - - Consider accepting technically accurate content that doesn't meet the [style guidelines](/docs/contribute/style/style-guide/). Open a new issue with the label `good first issue` to address style concerns. --> ## 职责 {#duties} 在为期一周的轮值期内,PR 管理者要: @@ -54,19 +44,44 @@ Each day in a week-long shift as PR Wrangler: - 首先查看最小的 PR(`size/XS`),然后逐渐扩展到最大的 PR(`size/XXL`),尽可能多地评审 PR。 + - 确保贡献者完成 [CLA](https://github.com/kubernetes/community/blob/master/CLA.md) 签署。 - 使用[此脚本](https://github.com/zparnold/k8s-docs-pr-botherer)自动提醒尚未签署 CLA 的贡献者签署 CLA。 - 针对提供提供反馈,请求其他 SIG 的成员进行技术审核。 - 为 PR 所建议的内容更改提供就地反馈。 - - 如果您需要验证内容,请在 PR 上发表评论并要求贡献者提供更多细节。 + - 如果你需要验证内容,请在 PR 上发表评论并要求贡献者提供更多细节。 - 设置相关的 `sig/` 标签。 - - 如果需要,从文件开头的 `reviewers:` 块中指派评阅人。 + - 如果需要,根据文件开头的 `reviewers:` 块来指派评审人。 + - 你也可以通过在 PR 上作出 `@kubernetes/-pr-reviews` 的评论以标记需要某个 + [SIG](https://github.com/kubernetes/community/blob/master/sig-list.md) 来评审。 + - 使用 `/approve` 评论来批准可以合并的 PR,在 PR 就绪时将其合并。 - PR 在被合并之前,应该有来自其他成员的 `/lgtm` 评论。 - 可以考虑接受那些技术上准确,但文风上不满足 [风格指南](/zh/docs/contribute/style/style-guide/)要求的 PR。 - 可以登记一个新的 Issue 来解决文档风格问题,并将其标记为 `good first issue`。 + 批准变更时,可以登记一个新的 Issue 来解决文档风格问题。 + 你通常可以将这些风格修复问题标记为 `good first issue`。 + - 将风格修复事项标记为 `good first issue` 可以很好地确保向新加入的贡献者分派一些比较简单的任务, + 这有助于接纳新的贡献者。 -### 对于管理人有用的 GitHub 查询 +### 对管理者有用的 GitHub 查询 执行管理操作时,以下查询很有用。完成以下这些查询后,剩余的要审阅的 PR 列表通常很小。 这些查询都不包含本地化的 PR,并仅包含主分支上的 PR(除了最后一个查询)。 @@ -172,3 +187,38 @@ The [`fejta-bot`](https://github.com/fejta-bot) bot marks issues as stale after PR 管理者应该在 issues 处于无人过问状态 14-30 天后关闭它们。 {{< /note >}} + +## PR 管理者影子计划 + +2021 下半年,SIG Docs 推出了 PR 管理者影子计划(PR Wrangler Shadow Program)。 +该计划旨在帮助新的贡献者们了解 PR 管理流程。 + + +### 成为一名影子 + +- 如果你有兴趣成为一名 PR 管理者的影子,请访问 [PR 管理者维基页面](https://github.com/kubernetes/website/wiki/PR-Wranglers)查看今年的 + PR 管理轮值表,然后注册报名。 + +- Kubernetes 组织成员可以编辑 [PR 管理者维基页面](https://github.com/kubernetes/website/wiki/PR-Wranglers), + 注册成为一名现有 PR 管理者一周内的影子。 + +- 其他人可以通过 [#sig-docs Slack 频道](https://kubernetes.slack.com/messages/sig-docs)申请成为指定 + PR 管理者某一周的影子。可以随时咨询 (`@bradtopol`) 或某一位 + [SIG Docs 联席主席/主管](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)。 + +- 注册成为一名 PR 管理者的影子时, + 请你在 [Kubernetes Slack](slack.k8s.io) 向这名 PR 管理者做一次自我介绍。