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 dc8f7e40f0..cdc033d966 100644 --- a/content/zh/docs/contribute/suggesting-improvements.md +++ b/content/zh/docs/contribute/suggesting-improvements.md @@ -26,7 +26,7 @@ In most cases, new work on Kubernetes documentation begins with an issue in GitH then review, categorize and tag issues as needed. Next, you or another member of the Kubernetes community open a pull request with changes to resolve the issue. --> -如果你发现 Kubernetes 文档中存在问题,或者你有一个关于新内容的想法,可以考虑 +如果你发现 Kubernetes 文档中存在问题或者你有一个关于新内容的想法,可以考虑 提出一个问题(issue)。你只需要具有 [GitHub 账号](https://github.com/join)和 Web 浏览器就可以完成这件事。 @@ -53,7 +53,7 @@ they can take action on your issue. --> ## 创建问题 {#opening-an-issue} -如果你希望就改进已有内容提出建议,或者在文档中发现了错误,请创建一个问题(issue)。 +如果你希望就改进已有内容提出建议或者在文档中发现了错误,请创建一个问题(issue)。 1. 滚动到页面底部,点击“报告问题”按钮。浏览器会重定向到一个 GitHub 问题页面,其中 包含了一些预先填充的内容。