From 742824d491bba243cc99a1d261e0771c06a40a60 Mon Sep 17 00:00:00 2001 From: howieyuen Date: Fri, 20 Aug 2021 15:26:01 +0800 Subject: [PATCH] [zh]sync contribution files for 1.22(Part-2) --- .../generate-ref-docs/contribute-upstream.md | 62 ++++++++++--------- .../contribute/generate-ref-docs/kubectl.md | 36 ++++++----- .../generate-ref-docs/quickstart.md | 36 +++++------ .../contribute/style/hugo-shortcodes/index.md | 4 +- .../zh/docs/contribute/style/style-guide.md | 12 ++-- .../contribute/suggesting-improvements.md | 8 +-- 6 files changed, 84 insertions(+), 74 deletions(-) diff --git a/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md b/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md index cf7b51cbaf..d16879d7e7 100644 --- a/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md +++ b/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md @@ -159,12 +159,12 @@ will be different in your situation. 以下在 Kubernetes 源代码中编辑注释的示例。 -在您本地的 kubernetes/kubernetes 代码仓库中，检出 master 分支，并确保它是最新的： +在您本地的 kubernetes/kubernetes 代码仓库中，检出默认分支，并确保它是最新的： ```shell cd @@ -173,9 +173,9 @@ git pull https://github.com/kubernetes/kubernetes master ``` -假设 master 分支中的下面源文件中包含拼写错误 "atmost"： +假设默认分支中的下面源文件中包含拼写错误 "atmost"： [kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/apps/v1/types.go) @@ -228,7 +228,6 @@ Go to `` and run these scripts: hack/update-generated-swagger-docs.sh hack/update-openapi-spec.sh hack/update-generated-protobuf.sh -hack/update-api-reference-docs.sh ``` @@ -238,8 +237,6 @@ hack/update-api-reference-docs.sh On branch master ... modified: api/openapi-spec/swagger.json - modified: api/swagger-spec/apps_v1.json - modified: docs/api-reference/apps/v1/definitions.html modified: staging/src/k8s.io/api/apps/v1/generated.proto modified: staging/src/k8s.io/api/apps/v1/types.go modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go @@ -310,24 +307,27 @@ In the preceding section, you edited a file in the master branch and then ran sc to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request to the master branch of the kubernetes/kubernetes repository. Now suppose you want to backport your change into a release branch. For example, suppose the master branch is being used to develop -Kubernetes version 1.10, and you want to backport your change into the release-1.9 branch. +Kubernetes version {{< skew latestVersion >}}, and you want to backport your change into the +release-{{< skew prevMinorVersion >}} branch. --> ### 将你的提交 Cherrypick 到发布分支 在上一节中，你在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。 然后用 PR 将你的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支中。 现在，需要将你的更改反向移植到已经发布的分支。 -例如，假设 master 分支被用来开发 Kubernetes 1.10 版，并且你想将更改反向移植到 release-1.9 分支。 +例如，假设 master 分支被用来开发 Kubernetes {{< skew latestVersion >}} 版， +并且你想将更改反向移植到 release-{{< skew prevMinorVersion >}} 分支。 回想一下，您的 PR 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。 -下一步是将你的第一次提交 cherrypick 到 release-1.9 分支。这样做的原因是仅 cherrypick 编辑了 types.go 的提交， +下一步是将你的第一次提交 cherrypick 到 release-{{< skew prevMinorVersion >}} 分支。 +这样做的原因是仅 cherrypick 编辑了 types.go 的提交， 而不是具有脚本运行结果的提交。 有关说明，请参见[提出 Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。 @@ -337,16 +337,17 @@ pull request. If you don't have those permissions, you will need to work with so and milestone for you. --> {{< note >}} -提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果您没有这些权限， +提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果你没有这些权限， 则需要与可以为你设置标签和里程碑的人员合作。 {{< /note >}} -当你发起 PR 将你的一个提交 cherry pick 到 release-1.9 分支中时，下一步是在本地环境的 release-1.9 -分支中运行如下脚本。 +当你发起 PR 将你的一个提交 cherry pick 到 release-{{< skew prevMinorVersion >}} 分支中时， +下一步是在本地环境的 release-{{< skew prevMinorVersion >}} 分支中运行如下脚本。 ```shell hack/update-generated-swagger-docs.sh @@ -357,24 +358,29 @@ hack/update-api-reference-docs.sh 现在将提交添加到您的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。 -关注你的 PR，直到其合并到 release-1.9 分支中为止。 +关注你的 PR，直到其合并到 release-{{< skew prevMinorVersion >}} 分支中为止。 -此时，master 分支和 release-1.9 分支都具有更新的 `types.go` 文件和一组生成的文件， +此时，master 分支和 release-{{< skew prevMinorVersion >}} +分支都具有更新的 `types.go` 文件和一组生成的文件， 这些文件反映了对 `types.go` 所做的更改。 -请注意，生成的 OpenAPI 规范和其他 release-1.9 分支中生成的文件不一定与 master 分支中生成的文件相同。 -release-1.9 分支中生成的文件仅包含来自 Kubernetes 1.9 的 API 元素。 -master 分支中生成的文件可能包含不在 1.9 中但正在为 1.10 开发的 API 元素。 +请注意，生成的 OpenAPI 规范和其他 release-{{< skew prevMinorVersion >}} +分支中生成的文件不一定与 master 分支中生成的文件相同。 +release-{{< skew prevMinorVersion >}} 分支中生成的文件仅包含来自 +Kubernetes {{< skew prevMinorVersion >}} 的 API 元素。 +master 分支中生成的文件可能包含不在 {{< skew prevMinorVersion >}} +中但正在为 {{< skew latestVersion >}} 开发的 API 元素。 在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如， -如果你想要生成 Kubernetes 1.17 的文档，可以使用以下命令： +如果你想要生成 Kubernetes {{< skew prevMinorVersion >}}.0 的文档，可以使用以下命令： ```shell cd -git checkout v1.17.0 -git pull https://github.com/kubernetes/kubernetes v1.17.0 +git checkout v{{< skew prevMinorVersion >}}.0 +git pull https://github.com/kubernetes/kubernetes {{< skew prevMinorVersion >}}.0 ``` [PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl 源码中的笔误进行修复的 PR 示例。 -跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的 master 分支中。 +跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的目标分支中。 -例如，假设 master 分支正用于开发 Kubernetes 1.16 版本，而你希望将修改合入到已发布的 1.15 版本分支。 +例如，假设 master 分支正用于开发 Kubernetes {{< skew currentVersion >}} 版本， +而你希望将修改合入到 release-{{< skew prevMinorVersion >}} 版本分支。 相关的操作指南，请参见 [提议一个 cherry-pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。 @@ -233,21 +235,22 @@ Go to ``, and open the `Makefile` for editing: * Set `K8S_ROOT` to ``. * Set `K8S_WEBROOT` to ``. * Set `K8S_RELEASE` to the version of the docs you want to build. - For example, if you want to build docs for Kubernetes 1.17, set `K8S_RELEASE` to 1.17. + For example, if you want to build docs for Kubernetes {{< skew prevMinorVersion >}}, set `K8S_RELEASE` to {{< skew prevMinorVersion >}}. For example, update the following variables: --> * 设置 `K8S_ROOT` 为 ``。 * 设置 `K8S_WEBROOT` 为 ``。 * 设置 `K8S_RELEASE` 为要构建文档的版本。 - 例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。 + 例如，如果您想为 Kubernetes {{< skew prevMinorVersion >}} 构建文档， + 请将 `K8S_RELEASE` 设置为 {{< skew prevMinorVersion >}}。 例如： ``` export K8S_WEBROOT=$(GOPATH)/src/github.com//website export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes -export K8S_RELEASE=1.17 +export K8S_RELEASE={{< skew prevMinorVersion >}} ``` ## 从 kubernetes/kubernetes 检出一个分支 在本地 `` 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。 -例如，如果希望为 Kubernetes 1.17 版本生成文档，请检出 `v1.17.0` 标记。 +例如，如果希望为 Kubernetes {{< skew prevMinorVersion >}}.0 版本生成文档， +请检出 `v{{< skew prevMinorVersion >}}` 标记。 确保本地分支是最新的。 ```shell cd -git checkout v1.17.0 -git pull https://github.com/kubernetes/kubernetes v1.17.0 +git checkout v{{< skew prevMinorVersion >}}.0 +git pull https://github.com/kubernetes/kubernetes v{{< skew prevMinorVersion >}}.0 ``` -本页讨论如何使用 `update-imported-docs` 脚本来生成 Kubernetes 参考文档。 +本页讨论如何使用 `update-imported-docs.py` 脚本来生成 Kubernetes 参考文档。 此脚本将构建的配置过程自动化，并为某个发行版本生成参考文档。 ## {{% heading "prerequisites" %}} @@ -27,13 +27,13 @@ the build setup and generates the reference documentation for a release. ## 获取文档仓库 {#getting-the-docs-repository} -确保你的 `website` 派生仓库与 `kubernetes/website` 主分支一致，并克隆 -你的派生仓库。 +确保你的 `website` 派生仓库与 GitHub 上的 `kubernetes/website` 远程仓库（`main` 分支）保持同步， +并克隆你的派生仓库。 ```shell mkdir github.com @@ -63,7 +63,7 @@ see the [contributing upstream guide](/docs/contribute/generate-ref-docs/contrib ## update-imported-docs 的概述 -脚本 `update-imported-docs` 位于 `/update-imported-docs/` 目录下， +脚本 `update-imported-docs.py` 位于 `/update-imported-docs/` 目录下， 能够生成以下参考文档： * Kubernetes 组件和工具的参考页面 @@ -82,7 +82,7 @@ The script builds the following references: * Kubernetes API 参考文档 -脚本 `update-imported-docs` 基于 Kubernetes 源代码生成参考文档。 +脚本 `update-imported-docs.py` 基于 Kubernetes 源代码生成参考文档。 过程中会在你的机器的 `/tmp` 目录下创建临时目录，克隆所需要的仓库 `kubernetes/kubernetes` 和 `kubernetes-sigs/reference-docs` 到此临时目录。 脚本会将 `GOPATH` 环境变量设置为指向此临时目录。 @@ -124,7 +124,7 @@ determines the version of the release. 变量 `K8S_RELEASE` 用来确定所针对的发行版本。 -脚本 `update-imported-docs` 执行以下步骤： +脚本 `update-imported-docs.py` 执行以下步骤： 1. 克隆配置文件中所指定的相关仓库。就生成参考文档这一目的而言，要克隆的 仓库默认为 `kubernetes-sigs/reference-docs`。 @@ -260,22 +260,22 @@ For example: ## 运行 update-imported-docs 工具 -你可以用如下方式运行 `update-imported-docs` 工具： +你可以用如下方式运行 `update-imported-docs.py` 工具： ```shell cd /update-imported-docs -./update-imported-docs +./update-imported-docs.py ``` 例如： ```shell -./update-imported-docs reference.yml 1.17 +./update-imported-docs.py reference.yml 1.17 ``` @@ -284,13 +284,13 @@ cd /update-imported-docs The `release.yml` configuration file contains instructions to fix relative links. To fix relative links within your imported files, set the`gen-absolute-links` property to `true`. You can find an example of this in -[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml). +[`release.yml`](https://github.com/kubernetes/website/blob/main/update-imported-docs/release.yml). --> ## 修复链接 配置文件 `release.yml` 中包含用来修复相对链接的指令。 若要修复导入文件中的相对链接，将 `gen-absolute-links` 属性设置为 `true`。 -你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml) +你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/main/update-imported-docs/release.yml) 文件中找到示例。 -词汇术语的原始数据保存在 [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary)，每个内容文件对应相应的术语解释。 +词汇术语的原始数据保存在 [https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary)，每个内容文件对应相应的术语解释。 ### 避免使用隐含用户对某技术有一定理解的词汇 @@ -1261,8 +1261,8 @@ These simple steps ... | These steps ... :--| :----- 在 ... 中包含一个命令 | 只需要在... 中包含一个命令 运行容器 ... | 只需运行该容器... -你可以很容易地移除... | 你可以移除... -这些简单的步骤... | 这些步骤... +你可以移除... | 你可以很容易地移除... +这些步骤... | 这些简单的步骤... {{< /table >}} ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/contribute/suggesting-improvements.md b/content/zh/docs/contribute/suggesting-improvements.md index fe5b469f84..cdc033d966 100644 --- a/content/zh/docs/contribute/suggesting-improvements.md +++ b/content/zh/docs/contribute/suggesting-improvements.md @@ -20,13 +20,13 @@ card: -如果你发现 Kubernetes 文档中存在问题，或者你有一个关于新内容的想法，可以考虑 +如果你发现 Kubernetes 文档中存在问题或者你有一个关于新内容的想法，可以考虑 提出一个问题（issue）。你只需要具有 [GitHub 账号](https://github.com/join)和 Web 浏览器就可以完成这件事。 @@ -40,7 +40,7 @@ Kubernetes 贡献者会审阅这些问题并根据需要对其分类、打标签 ## 创建问题 {#opening-an-issue} -如果你希望就改进已有内容提出建议，或者在文档中发现了错误，请创建一个问题（issue）。 +如果你希望就改进已有内容提出建议或者在文档中发现了错误，请创建一个问题（issue）。 1. 滚动到页面底部，点击“报告问题”按钮。浏览器会重定向到一个 GitHub 问题页面，其中 包含了一些预先填充的内容。