Switch language name 'zh' to 'zh-cn'
This is the first step to rename 'zh' to 'zh-cn'. There are several reasons why we rename the language name.
- The upstream docsy theme changed the language name, leading to many warnings during site build;
The side-effect is that the i18n strings are no longer working.
- We believe renaming the language is the right thing to do, because this move can make room for other variants of Chinese language, such as 'zh-tw', 'zh-sg' etc.
There would be several follow-ups to this PR, such as fixing the intra-site links, adding redirects etc.
We will lock up changes to zh/zh-cn pages for the moment, until this one gets in.
This PR is based on commit cdad0a7342.
This commit is contained in:
Qiming Teng
@@ -0,0 +1,315 @@
|
||||
---
|
||||
content_type: concept
|
||||
title: 为 Kubernetes 文档出一份力
|
||||
linktitle: 贡献
|
||||
main_menu: true
|
||||
no_list: true
|
||||
weight: 80
|
||||
card:
|
||||
name: contribute
|
||||
weight: 10
|
||||
title: 开始为 Kubernetes 做贡献
|
||||
---
|
||||
<!--
|
||||
---
|
||||
content_type: concept
|
||||
title: Contribute to Kubernetes docs
|
||||
linktitle: Contribute
|
||||
main_menu: true
|
||||
no_list: true
|
||||
weight: 80
|
||||
card:
|
||||
name: contribute
|
||||
weight: 10
|
||||
title: Start contributing to K8s
|
||||
---
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
*Kubernetes welcomes improvements from all contributors, new and experienced!*
|
||||
-->
|
||||
*Kubernetes 欢迎来自所有贡献者的改进，无论你是新人和有经验的贡献者！*
|
||||
|
||||
<!--
|
||||
{{< note >}}
|
||||
To learn more about contributing to Kubernetes in general, see the
|
||||
[contributor documentation](https://www.kubernetes.dev/docs/).
|
||||
|
||||
You can also read the
|
||||
{{< glossary_tooltip text="CNCF" term_id="cncf" >}}
|
||||
[page](https://contribute.cncf.io/contributors/projects/#kubernetes)
|
||||
about contributing to Kubernetes.
|
||||
{{< /note >}}
|
||||
-->
|
||||
{{< note >}}
|
||||
要了解有关为 Kubernetes 做出贡献的更多信息，请参阅
|
||||
[贡献者文档](https://www.kubernetes.dev/docs/)。
|
||||
|
||||
你还可以阅读
|
||||
{{< glossary_tooltip text="CNCF" term_id="cncf" >}}
|
||||
关于为 Kubernetes 做贡献的[页面](https://contribute.cncf.io/contributors/projects/#kubernetes)。
|
||||
|
||||
<!--
|
||||
This website is maintained by [Kubernetes SIG Docs](/docs/contribute/#get-involved-with-sig-docs).
|
||||
|
||||
Kubernetes documentation contributors:
|
||||
|
||||
- Improve existing content
|
||||
- Create new content
|
||||
- Translate the documentation
|
||||
- Manage and publish the documentation parts of the Kubernetes release cycle
|
||||
-->
|
||||
本网站由 [Kubernetes SIG（特别兴趣小组）Docs](/zh/docs/contribute/#get-involved-with-SIG-Docs) 维护。
|
||||
|
||||
Kubernetes 文档项目的贡献者：
|
||||
|
||||
- 改进现有内容
|
||||
- 创建新内容
|
||||
- 翻译文档
|
||||
- 管理并发布 Kubernetes 周期性发行版的文档
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Getting started
|
||||
|
||||
Anyone can open an issue about documentation, or contribute a change with a
|
||||
pull request (PR) to the
|
||||
[`kubernetes/website` GitHub repository](https://github.com/kubernetes/website).
|
||||
You need to be comfortable with
|
||||
[git](https://git-scm.com/) and
|
||||
[GitHub](https://lab.github.com/)
|
||||
to work effectively in the Kubernetes community.
|
||||
-->
|
||||
## 入门 {#getting-started}
|
||||
|
||||
任何人都可以提出文档方面的问题（issue），或贡献一个变更，用拉取请求（PR）的方式提交到
|
||||
[GitHub 上的 `kubernetes/website` 仓库](https://github.com/kubernetes/website)。
|
||||
当然你需要熟练使用 [git](https://git-scm.com/) 和 [GitHub](https://lab.github.com/) 才能在 Kubernetes 社区中有效工作。
|
||||
|
||||
<!--
|
||||
To get involved with documentation:
|
||||
|
||||
1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md).
|
||||
2. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website)
|
||||
and the website's [static site generator](https://gohugo.io).
|
||||
3. Make sure you understand the basic processes for
|
||||
[opening a pull request](/docs/contribute/new-content/open-a-pr/) and
|
||||
[reviewing changes](/docs/contribute/review/reviewing-prs/).
|
||||
-->
|
||||
如何参与文档编制：
|
||||
|
||||
1. 签署 CNCF 的[贡献者许可协议](https://github.com/kubernetes/community/blob/master/CLA.md)。
|
||||
2. 熟悉[文档仓库](https://github.com/kubernetes/website)和网站的[静态站点生成器](https://gohugo.io)。
|
||||
3. 确保理解[发起 PR](/zh/docs/contribute/new-content/open-a-pr/) 和[审查变更](/zh/docs/contribute/review/reviewing-prs/)的基本流程。
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart TB
|
||||
subgraph third[发起 PR]
|
||||
direction TB
|
||||
U[ ] -.-
|
||||
Q[改进现有内容] --- N[创建新内容]
|
||||
N --- O[翻译文档]
|
||||
O --- P[管理并发布 K8s<br>周期性发行版的文档]
|
||||
|
||||
end
|
||||
|
||||
subgraph second[评审]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
D[仔细查看<br>K8s/website<br>仓库] --- E[下载安装 Hugo<br>静态站点<br>生成器]
|
||||
E --- F[了解基本的<br>GitHub 命令]
|
||||
F --- G[评审待处理的 PR<br>并遵从变更审查<br>流程]
|
||||
end
|
||||
|
||||
subgraph first[注册]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
B[签署 CNCF<br>贡献者<br>许可协议] --- C[加入 sig-docs<br>Slack 频道]
|
||||
C --- V[加入 kubernetes-sig-docs<br>邮件列表]
|
||||
V --- M[参加每周的<br>sig-docs 电话会议<br>或 slack 会议]
|
||||
end
|
||||
|
||||
A([fa:fa-user 新的<br>贡献者]) --> first
|
||||
A --> second
|
||||
A --> third
|
||||
A --> H[提出问题!!!]
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,C,D,E,F,G,H,M,Q,N,O,P,V grey
|
||||
class S,T,U spacewhite
|
||||
class first,second,third white
|
||||
{{</ mermaid >}}
|
||||
|
||||
<!--
|
||||
Figure 1. Getting started for a new contributor.
|
||||
|
||||
Figure 1 outlines a roadmap for new contributors. You can follow some or all of the steps for `Sign up` and `Review`. Now you are ready to open PRs that achieve your contribution objectives with some listed under `Open PR`. Again, questions are always welcome!
|
||||
-->
|
||||
图 1. 新手入门指示。
|
||||
|
||||
图 1 概述了新贡献者的路线图。
|
||||
你可以遵从`注册`和`评审`所述的某些或全部步骤。
|
||||
至此，你完成了发起 PR 的准备工作，
|
||||
可以通过`发起 PR`列出的事项实现你的贡献目标。
|
||||
再次重申，欢迎随时提出问题！
|
||||
|
||||
<!--
|
||||
Some tasks require more trust and more access in the Kubernetes organization.
|
||||
See [Participating in SIG Docs](/docs/contribute/participate/) for more details about
|
||||
roles and permissions.
|
||||
-->
|
||||
有些任务要求 Kubernetes 组织内更高的信任级别和访问权限。
|
||||
阅读[参与 SIG Docs 工作](/zh/docs/contribute/participate/) ，获取角色和权限的更多细节。
|
||||
|
||||
<!--
|
||||
## Your first contribution
|
||||
|
||||
You can prepare for your first contribution by reviewing several steps beforehand. Figure 2 outlines the steps and the details follow.
|
||||
-->
|
||||
## 第一次贡献 {#your-first-contribution}
|
||||
|
||||
你可以提前查阅几个步骤，来准备你的第一次贡献。
|
||||
图 2 概述了后续的步骤和细节。
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph second[第一次贡献]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
G[查阅其他 K8s<br>成员发起的 PR] -->
|
||||
A[检索 K8s/website<br>问题列表是否有<br>good first 一类的 PR] --> B[发起一个 PR!!]
|
||||
end
|
||||
subgraph first[建议的准备工作]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
D[阅读贡献概述] -->E[阅读 K8s 内容<br>和风格指南]
|
||||
E --> F[了解 Hugo 页面<br>内容类型<br>和短代码]
|
||||
end
|
||||
|
||||
|
||||
first ----> second
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,D,E,F,G grey
|
||||
class S,T spacewhite
|
||||
class first,second white
|
||||
{{</ mermaid >}}
|
||||
|
||||
<!--
|
||||
Figure 2. Preparation for your first contribution.
|
||||
-->
|
||||
图 2. 第一次贡献的准备工作。
|
||||
|
||||
<!--
|
||||
- Read the [Contribution overview](/docs/contribute/new-content/overview/) to
|
||||
learn about the different ways you can contribute.
|
||||
- Check [`kubernetes/website` issues list](https://github.com/kubernetes/website/issues/)
|
||||
for issues that make good entry points.
|
||||
- [Open a pull request using GitHub](/docs/contribute/new-content/open-a-pr/#changes-using-github)
|
||||
to existing documentation and learn more about filing issues in GitHub.
|
||||
- [Review pull requests](/docs/contribute/review/reviewing-prs/) from other
|
||||
Kubernetes community members for accuracy and language.
|
||||
- Read the Kubernetes [content](/docs/contribute/style/content-guide/) and
|
||||
[style guides](/docs/contribute/style/style-guide/) so you can leave informed comments.
|
||||
- Learn about [page content types](/docs/contribute/style/page-content-types/)
|
||||
and [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/).
|
||||
-->
|
||||
- 通读[贡献概述](/zh/docs/contribute/new-content/overview/)，了解参与贡献的不同方式。
|
||||
- 查看 [`kubernetes/website` 问题列表](https://github.com/kubernetes/website/issues/)
|
||||
，检索最适合作为切入点的问题。
|
||||
- 在现有文档上，[使用 GitHub 提交 PR](/zh/docs/contribute/new-content/open-a-pr/#changes-using-github)，
|
||||
掌握在 GitHub 上登记 Issue 的方法。
|
||||
- Kubernetes 社区其他成员会[评审 PR ](/zh/docs/contribute/review/reviewing-prs/)，
|
||||
以确保文档精准和语言流畅。
|
||||
- 阅读 kubernetes 的[内容指南](/zh/docs/contribute/style/content-guide/)和
|
||||
[风格指南](/zh/docs/contribute/style/style-guide/)，以发表有见地的评论。
|
||||
- 了解[页面内容类型](/zh/docs/contribute/style/page-content-types/)和
|
||||
[Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/)。
|
||||
|
||||
<!--
|
||||
## Next steps
|
||||
|
||||
- Learn to [work from a local clone](/docs/contribute/new-content/open-a-pr/#fork-the-repo)
|
||||
of the repository.
|
||||
- Document [features in a release](/docs/contribute/new-content/new-features/).
|
||||
- Participate in [SIG Docs](/docs/contribute/participate/), and become a
|
||||
[member or reviewer](/docs/contribute/participate/roles-and-responsibilities/).
|
||||
|
||||
- Start or help with a [localization](/docs/contribute/localization/).
|
||||
-->
|
||||
## 下一步 {#next-teps}
|
||||
|
||||
- 学习在仓库的[本地克隆中工作](/zh/docs/contribute/new-content/open-a-pr/#fork-the-repo)。
|
||||
- 为[发行版的特性](/zh/docs/contribute/new-content/new-features/)编写文档。
|
||||
- 加入 [SIG Docs](/zh/docs/contribute/participate/)，并成为[成员或评审者](/zh/docs/contribute/participate/roles-and-responsibilities/)。
|
||||
|
||||
- 开始或帮助[本地化](/zh/docs/contribute/localization/) 工作。
|
||||
|
||||
<!--
|
||||
## Get involved with SIG Docs
|
||||
|
||||
[SIG Docs](/docs/contribute/participate/) is the group of contributors who
|
||||
publish and maintain Kubernetes documentation and the website. Getting
|
||||
involved with SIG Docs is a great way for Kubernetes contributors (feature
|
||||
development or otherwise) to have a large impact on the Kubernetes project.
|
||||
|
||||
SIG Docs communicates with different methods:
|
||||
-->
|
||||
## 参与 SIG Docs 工作 {#get-involved-with-SIG-Docs}
|
||||
|
||||
[SIG Docs](/zh/docs/contribute/participate/) 是负责发布、维护 Kubernetes 文档的贡献者团体。
|
||||
参与 SIG Docs 是 Kubernetes 贡献者（开发者和其他人员）对 Kubernetes 项目产生重大影响力的好方式。
|
||||
|
||||
SIG Docs 的几种沟通方式：
|
||||
<!--
|
||||
- [Join `#sig-docs` on the Kubernetes Slack instance](https://slack.k8s.io/). Make sure to
|
||||
introduce yourself!
|
||||
- [Join the `kubernetes-sig-docs` mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs),
|
||||
where broader discussions take place and official decisions are recorded.
|
||||
- Join the [SIG Docs video meeting](https://github.com/kubernetes/community/tree/master/sig-docs) held every two weeks. Meetings are always announced on `#sig-docs` and added to the [Kubernetes community meetings calendar](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles). You'll need to download the [Zoom client](https://zoom.us/download) or dial in using a phone.
|
||||
- Join the SIG Docs async Slack standup meeting on those weeks when the in-person Zoom video meeting does not take place. Meetings are always announced on `#sig-docs`. You can contribute to any one of the threads up to 24 hours after meeting announcement.
|
||||
-->
|
||||
- [加入 Kubernetes 在 Slack 上的`#sig-docs` 频道](https://slack.k8s.io/)。
|
||||
一定记得自我介绍!
|
||||
- [加入 `kubernetes-sig-docs` 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs),
|
||||
这里有更广泛的讨论，和官方决策的记录。
|
||||
- 参加每两周召开一次的 [SIG Docs 视频会议](https://github.com/kubernetes/community/tree/master/sig-docs)。
|
||||
会议总是在 `#sig-docs` 上发出公告，同时添加到
|
||||
[Kubernetes 社区会议日历](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles)。
|
||||
你需要下载 [Zoom 客户端软件](https://zoom.us/download)，或电话拨号接入。
|
||||
- 如果有几周未召开实况 Zoom 视频会议，请参加 SIG Docs 异步 Slack 站会。
|
||||
会议总是在 `#sig-docs` 上发出公告。
|
||||
你可以在会议公告后 24 小时内为其中任一议题做贡献。
|
||||
|
||||
<!--
|
||||
## Other ways to contribute
|
||||
|
||||
- Visit the [Kubernetes community site](/community/). Participate on Twitter or Stack Overflow, learn about local Kubernetes meetups and events, and more.
|
||||
- Read the [contributor cheatsheet](https://www.kubernetes.dev/docs/contributor-cheatsheet/) to get involved with Kubernetes feature development.
|
||||
- Visit the contributor site to learn more about [Kubernetes Contributors](https://www.kubernetes.dev/) and [additional contributor resources](https://www.kubernetes.dev/resources/).
|
||||
- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/).
|
||||
-->
|
||||
## 其他贡献方式 {#other-ways-to-contribute}
|
||||
|
||||
- 访问 [Kubernetes 社区网站](/zh/community/)。
|
||||
参与 Twitter 或 Stack Overflow，了解当地的 Kubernetes 会议和活动等等。
|
||||
- 阅读[贡献者备忘单](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet)，
|
||||
参与 Kubernetes 功能开发。
|
||||
- 访问贡献者网站，进一步了解有关 [Kubernetes 贡献者](https://www.kubernetes.dev/)
|
||||
和[更多贡献者资源](https://www.kubernetes.dev/resources/)的信息。
|
||||
- 提交一篇[博客文章或案例研究](/zh/docs/contribute/new-content/blogs-case-studies/)。
|
||||
@@ -0,0 +1,377 @@
|
||||
---
|
||||
title: 进阶贡献
|
||||
slug: advanced
|
||||
content_type: concept
|
||||
weight: 98
|
||||
---
|
||||
<!--
|
||||
title: Advanced contributing
|
||||
slug: advanced
|
||||
content_type: concept
|
||||
weight: 98
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page assumes that you understand how to
|
||||
[contribute to new content](/docs/contribute/new-content/overview) and
|
||||
[review others' work](/docs/contribute/review/reviewing-prs/), and are ready
|
||||
to learn about more ways to contribute. You need to use the Git command line
|
||||
client and other tools for some of these tasks.
|
||||
-->
|
||||
|
||||
如果你已经了解如何[贡献新内容](/zh/docs/contribute/new-content/overview/)和
|
||||
[评阅他人工作](/zh/docs/contribute/review/reviewing-prs/)，并准备了解更多贡献的途径，
|
||||
请阅读此文。你需要使用 Git 命令行工具和其他工具做这些工作。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Propose improvements
|
||||
|
||||
SIG Docs [members](/docs/contribute/participate/roles-and-responsibilities/#members) can propose improvements.
|
||||
-->
|
||||
## 提出改进建议
|
||||
|
||||
SIG Docs 的 [成员](/zh/docs/contribute/participate/roles-and-responsibilities/#members) 可以提出改进建议。
|
||||
|
||||
<!--
|
||||
After you've been contributing to the Kubernetes documentation for a while, you
|
||||
may have ideas for improving the [Style Guide](/docs/contribute/style/style-guide/)
|
||||
, the [Content Guide](/docs/contribute/style/content-guide/), the toolchain used to build
|
||||
the documentation, the website style, the processes for reviewing and merging
|
||||
pull requests, or other aspects of the documentation. For maximum transparency,
|
||||
these types of proposals need to be discussed in a SIG Docs meeting or on the
|
||||
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
In addition, it can help to have some context about the way things
|
||||
currently work and why past decisions have been made before proposing sweeping
|
||||
changes. The quickest way to get answers to questions about how the documentation
|
||||
currently works is to ask in the `#sig-docs` Slack channel on
|
||||
[kubernetes.slack.com](https://kubernetes.slack.com)
|
||||
-->
|
||||
在对 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` 聊天群组。
|
||||
|
||||
<!--
|
||||
After the discussion has taken place and the SIG is in agreement about the desired
|
||||
outcome, you can work on the proposed changes in the way that is the most
|
||||
appropriate. For instance, an update to the style guide or the website's
|
||||
functionality might involve opening a pull request, while a change related to
|
||||
documentation testing might involve working with sig-testing.
|
||||
-->
|
||||
在进行了讨论并且 SIG 就期望的结果达成一致之后，你就能以最合理的方式处理改进建议了。例如，样式指南或网站功能的更新可能涉及 PR 的新增，而与文档测试相关的更改可能涉及 sig-testing。
|
||||
|
||||
<!--
|
||||
## Coordinate docs for a Kubernetes release
|
||||
|
||||
SIG Docs [approvers](/docs/contribute/participating/#approvers) can coordinate
|
||||
docs for a Kubernetes release.
|
||||
-->
|
||||
## 为 Kubernetes 版本发布协调文档工作
|
||||
|
||||
SIG Docs 的[批准者（approvers）](/zh/docs/contribute/participating/#approvers) 可以为
|
||||
Kubernetes 版本发布协调文档工作。
|
||||
|
||||
<!--
|
||||
Each Kubernetes release is coordinated by a team of people participating in the
|
||||
sig-release Special Interest Group (SIG). Others on the release team for a given
|
||||
release include an overall release lead, as well as representatives from
|
||||
sig-testing and others. To find out more about Kubernetes release processes,
|
||||
refer to
|
||||
[https://github.com/kubernetes/sig-release](https://github.com/kubernetes/sig-release).
|
||||
-->
|
||||
每一个 Kubernetes 版本都是由参与 sig-release 的 SIG（特别兴趣小组）的一个团队协调的。
|
||||
指定版本的发布团队中还包括总体发布牵头人，以及来自 sig-testing 的代表等。
|
||||
要了解更多关于 Kubernetes 版本发布的流程，请参考
|
||||
[https://github.com/kubernetes/sig-release](https://github.com/kubernetes/sig-release)。
|
||||
|
||||
<!--
|
||||
The SIG Docs representative for a given release coordinates the following tasks:
|
||||
|
||||
- Monitor the feature-tracking spreadsheet for new or changed features with an
|
||||
impact on documentation. If the documentation for a given feature won't be ready
|
||||
for the release, the feature may not be allowed to go into the release.
|
||||
- Attend sig-release meetings regularly and give updates on the status of the
|
||||
docs for the release.
|
||||
- Review and copyedit feature documentation drafted by the SIG responsible for
|
||||
implementing the feature.
|
||||
- Merge release-related pull requests and maintain the Git feature branch for
|
||||
the release.
|
||||
- Mentor other SIG Docs contributors who want to learn how to do this role in
|
||||
the future. This is known as "shadowing".
|
||||
- Publish the documentation changes related to the release when the release
|
||||
artifacts are published.
|
||||
-->
|
||||
|
||||
SIG Docs 团队的代表需要为一个指定的版本协调以下工作：
|
||||
|
||||
- 通过特性跟踪表来监视新功能特性或现有功能特性的修改。
|
||||
如果版本的某个功能特性的文档没有为发布做好准备，那么该功能特性不允许进入发布版本。
|
||||
- 定期参加 sig-release 会议并汇报文档的发布状态。
|
||||
- 评审和修改由负责实现某功能特性的 SIG 起草的功能特性文档。
|
||||
- 合入版本发布相关的 PR，并为对应发布版本维护 Git 特性分支。
|
||||
- 指导那些想学习并有意愿担当该角色的 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 批准人轮流承担。
|
||||
|
||||
<!--
|
||||
## Serve as a New Contributor Ambassador
|
||||
|
||||
SIG Docs [approvers](/docs/contribute/participating/#approvers) can serve as
|
||||
New Contributor Ambassadors.
|
||||
|
||||
New Contributor Ambassadors work together to welcome new contributors to SIG-Docs,
|
||||
suggest PRs to new contributors, and mentor new contributors through their first
|
||||
few PR submissions.
|
||||
|
||||
Responsibilities for New Contributor Ambassadors include:
|
||||
-->
|
||||
|
||||
## 担任新的贡献者大使
|
||||
|
||||
SIG Docs [批准人（Approvers）](/zh/docs/contribute/participating/#approvers)
|
||||
可以担任新的贡献者大使。
|
||||
|
||||
新的贡献者大使共同努力欢迎 SIG-Docs 的新贡献者，对新贡献者的 PR 提出建议，
|
||||
以及在前几份 PR 提交中指导新贡献者。
|
||||
|
||||
新的贡献者大使的职责包括：
|
||||
|
||||
<!--
|
||||
- Being available on the [Kubernetes #sig-docs channel](https://kubernetes.slack.com) to answer questions from new contributors.
|
||||
- Working with PR wranglers to identify [good first issues](https://kubernetes.dev/docs/guide/help-wanted/#good-first-issue) for new contributors.
|
||||
- Mentoring new contributors through their first few PRs to the docs repo.
|
||||
- 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.
|
||||
- Hosting a monthly meeting to help and mentor new contributors.
|
||||
-->
|
||||
- 监听 [Kubernetes #sig-docs 频道](https://kubernetes.slack.com) 上新贡献者的 Issue。
|
||||
- 与 PR 管理者合作为新参与者寻找[合适的第一个 issues](https://kubernetes.dev/docs/guide/help-wanted/#good-first-issue) 。
|
||||
- 通过前几个 PR 指导新贡献者为文档存储库作贡献。
|
||||
- 帮助新的贡献者创建成为 Kubernetes 成员所需的更复杂的 PR。
|
||||
- [为贡献者提供保荐](#sponsor-a-new-contributor)，使其成为 Kubernetes 成员。
|
||||
- 每月召开一次会议，帮助和指导新的贡献者。
|
||||
|
||||
<!--
|
||||
Current New Contributor Ambassadors are announced at each SIG-Docs meeting and in the [Kubernetes #sig-docs channel](https://kubernetes.slack.com).
|
||||
-->
|
||||
当前新贡献者大使将在每次 SIG 文档会议上以及 [Kubernetes #sig-docs 频道](https://kubernetes.slack.com)中宣布。
|
||||
|
||||
<!--
|
||||
## Sponsor a new contributor
|
||||
|
||||
SIG Docs [reviewers](/docs/contribute/participating/#reviewers) can sponsor
|
||||
new contributors.
|
||||
-->
|
||||
## 为新的贡献者提供保荐 {#sponsor-a-new-contributor}
|
||||
|
||||
SIG Docs 的[评审人（Reviewers）](/zh/docs/contribute/participating/#reviewers) 可以为新的贡献者提供保荐。
|
||||
|
||||
<!--
|
||||
After a new contributor has successfully submitted 5 substantive pull requests
|
||||
to one or more Kubernetes repositories, they are eligible to apply for
|
||||
[membership](/docs/contribute/participating#members) in the Kubernetes
|
||||
organization. The contributor's membership needs to be backed by two sponsors
|
||||
who are already reviewers.
|
||||
-->
|
||||
新的贡献者针对一个或多个 Kubernetes 项目仓库成功提交了 5 个实质性 PR 之后，
|
||||
就有资格申请 Kubernetes 组织的[成员身份](/zh/docs/contribute/participate/roles-and-responsibilities/#members)。
|
||||
贡献者的成员资格需要同时得到两位评审人的保荐。
|
||||
|
||||
<!--
|
||||
New docs contributors can request sponsors by asking in the #sig-docs channel
|
||||
on the [Kubernetes Slack instance](https://kubernetes.slack.com) or on the
|
||||
[SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
If you feel confident about the applicant's work, you volunteer to sponsor them.
|
||||
When they submit their membership application, reply to the application with a
|
||||
"+1" and include details about why you think the applicant is a good fit for
|
||||
membership in the Kubernetes organization.
|
||||
-->
|
||||
新的文档贡献者可以通过咨询 [Kubernetes Slack 实例](https://kubernetes.slack.com)
|
||||
上的 #sig-docs 频道或者 [SIG Docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
|
||||
来请求评审者保荐。如果你对申请人的工作充满信心，你自愿保荐他们。
|
||||
当他们提交成员资格申请时，回复 “+1” 并详细说明为什么你认为申请人适合加入 Kubernetes 组织。
|
||||
|
||||
<!--
|
||||
## Serve as a SIG Co-chair
|
||||
|
||||
SIG Docs [members](/docs/contribute/participate/roles-and-responsibilities/#members)
|
||||
can serve a term as a co-chair of SIG Docs.
|
||||
|
||||
### Prerequisites
|
||||
-->
|
||||
## 担任 SIG 联合主席
|
||||
|
||||
SIG Docs [成员（Members）](/zh/docs/contribute/participate/roles-and-responsibilities/#members)
|
||||
可以担任 SIG Docs 的联合主席。
|
||||
|
||||
### 前提条件
|
||||
|
||||
<!--
|
||||
A Kubernetes member must meet the following requirements to be a co-chair:
|
||||
|
||||
- Understand SIG Docs workflows and tooling: git, Hugo, localization, blog subproject
|
||||
- Understand how other Kubernetes SIGs and repositories affect the SIG Docs workflow, including: [teams in k/org](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml), the [process in k/community](https://github.com/kubernetes/community/tree/master/sig-docs), plugins in [k/test-infra](https://github.com/kubernetes/test-infra/), and the role of [SIG Architecture](https://github.com/kubernetes/community/tree/master/sig-architecture).
|
||||
In addition, understand how the [Kubernetes docs release process](/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) works.
|
||||
- Approved by the SIG Docs community either directly or via lazy consensus.
|
||||
- Commit at least 5 hours per week (and often more) to the role for a minimum of 6 months
|
||||
-->
|
||||
Kubernetes 成员必须满足以下要求才能成为联合主席：
|
||||
|
||||
- 理解 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 文档发布流程](/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) 的工作原理。
|
||||
- 由 SIG Docs 社区直接或通过惰性共识批准。
|
||||
- 在至少 6 个月的时段内，确保每周至少投入 5 个小时（通常更多）
|
||||
|
||||
<!--
|
||||
### Responsibilities
|
||||
|
||||
The role of co-chair is primarily one of service: co-chairs handle process and policy, schedule and run meetings, schedule PR wranglers, and generally do the things that no one else wants to do in order to build contributor capacity.
|
||||
|
||||
Responsibilities include:
|
||||
-->
|
||||
### 职责范围
|
||||
|
||||
联合主席主要提供以下服务：
|
||||
联合主席负责处理流程和政策、时间安排和召开会议、安排 PR 管理员、以及一些其他人不想做的事情，目的是增长贡献者团队。
|
||||
|
||||
职责范围包括：
|
||||
|
||||
<!--
|
||||
- Keep SIG Docs focused on maximizing developer happiness through excellent documentation
|
||||
- Exemplify the [community code of conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and hold SIG members accountable to it
|
||||
- Learn and set best practices for the SIG by updating contribution guidelines
|
||||
- Schedule and run SIG meetings: weekly status updates, quarterly retro/planning sessions, and others as needed
|
||||
- Schedule and run doc sprints at KubeCon events and other conferences
|
||||
- Recruit for and advocate on behalf of SIG Docs with the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} and its platinum partners, including Google, Oracle, Azure, IBM, and Huawei
|
||||
- Keep the SIG running smoothly
|
||||
-->
|
||||
- 保持 SIG Docs 专注于通过出色的文档最大限度地提高开发人员的满意度
|
||||
- 以身作则，践行[社区行为准则](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 的身份招募和宣传
|
||||
- 负责 SIG 正常运行
|
||||
|
||||
<!--
|
||||
### Running effective meetings
|
||||
|
||||
To schedule and run effective meetings, these guidelines show what to do, how to do it, and why.
|
||||
|
||||
**Uphold the [community code of conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)**:
|
||||
|
||||
- Hold respectful, inclusive discussions with respectful, inclusive language.
|
||||
-->
|
||||
### 召开高效的会议
|
||||
|
||||
为了安排和召开高效的会议，这些指南说明了如何做、怎样做以及原因。
|
||||
|
||||
**坚持[社区行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)**：
|
||||
|
||||
- 相互尊重地、包容地进行讨论。
|
||||
|
||||
<!--
|
||||
**Set a clear agenda**:
|
||||
|
||||
- Set a clear agenda of topics
|
||||
- Publish the agenda in advance
|
||||
|
||||
For weekly meetings, copypaste the previous week's notes into the "Past meetings" section of the notes
|
||||
-->
|
||||
**设定明确的议程**：
|
||||
|
||||
- 设定清晰的主题议程
|
||||
- 提前发布议程
|
||||
|
||||
对于每周一次的会议，请将前一周的笔记复制并粘贴到笔记的“过去的会议”部分中
|
||||
|
||||
<!--
|
||||
**Collaborate on accurate notes**:
|
||||
|
||||
- Record the meeting's discussion
|
||||
- Consider delegating the role of note-taker
|
||||
|
||||
**Assign action items clearly and accurately**:
|
||||
|
||||
- Record the action item, who is assigned to it, and the expected completion date
|
||||
-->
|
||||
**通过协作，完成准确的记录**：
|
||||
|
||||
- 记录会议讨论
|
||||
- 考虑委派笔记记录员的角色
|
||||
|
||||
**清晰准确地分配执行项目**：
|
||||
|
||||
- 记录操作项，分配给它的人员以及预期的完成日期
|
||||
|
||||
<!--
|
||||
**Moderate as needed**:
|
||||
|
||||
- If discussion strays from the agenda, refocus participants on the current topic
|
||||
- Make room for different discussion styles while keeping the discussion focused and honoring folks' time
|
||||
|
||||
**Honor folks' time**:
|
||||
|
||||
- Begin and end meetings punctually
|
||||
-->
|
||||
**根据需要来进行协调**：
|
||||
|
||||
- 如果讨论偏离议程，请让参与者重新关注当前主题
|
||||
- 为不同的讨论风格留出空间，同时保持讨论重点并尊重人们的时间
|
||||
|
||||
**尊重大家的时间**:
|
||||
|
||||
- 准时开始和结束会议
|
||||
|
||||
<!--
|
||||
**Use Zoom effectively**:
|
||||
|
||||
- Familiarize yourself with [Zoom guidelines for Kubernetes](https://github.com/kubernetes/community/blob/master/communication/zoom-guidelines.md)
|
||||
- Claim the host role when you log in by entering the host key
|
||||
|
||||
<img src="/images/docs/contribute/claim-host.png" width="75%" alt="Claiming the host role in Zoom" />
|
||||
-->
|
||||
**有效利用 Zoom**：
|
||||
|
||||
- 熟悉 [ Kubernetes Zoom 指南](https://github.com/kubernetes/community/blob/master/communication/zoom-guidelines.md)
|
||||
- 输入主持人密钥登录时声明主持人角色
|
||||
|
||||
<img src="/images/docs/contribute/claim-host.png" width="75%" alt="声明 Zoom 角色" />
|
||||
|
||||
<!--
|
||||
### Recording meetings on Zoom
|
||||
|
||||
When you're ready to start the recording, click Record to Cloud.
|
||||
|
||||
When you're ready to stop recording, click Stop.
|
||||
|
||||
The video uploads automatically to YouTube.
|
||||
-->
|
||||
### 录制 Zoom 会议
|
||||
|
||||
准备开始录制时，请单击“录制到云”。
|
||||
|
||||
准备停止录制时，请单击“停止”。
|
||||
|
||||
视频会自动上传到 YouTube。
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: 查看站点分析
|
||||
content_type: concept
|
||||
weight: 100
|
||||
card:
|
||||
name: contribute
|
||||
weight: 100
|
||||
---
|
||||
|
||||
<!--
|
||||
title: Viewing Site Analytics
|
||||
content_type: concept
|
||||
weight: 100
|
||||
card:
|
||||
name: contribute
|
||||
weight: 100
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page contains information about the kubernetes.io analytics dashboard.
|
||||
-->
|
||||
此页面包含有关 kubernetes.io 分析仪表板的信息。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
[View the dashboard](https://datastudio.google.com/reporting/fede2672-b2fd-402a-91d2-7473bdb10f04).
|
||||
|
||||
This dashboard is built using Google Data Studio and shows information collected on kubernetes.io using Google Analytics.
|
||||
-->
|
||||
[查看仪表板](https://datastudio.google.com/reporting/fede2672-b2fd-402a-91d2-7473bdb10f04)。
|
||||
|
||||
此仪表板使用 Google Data Studio 构建，显示使用 Google Analytics 在 kubernetes.io 上收集的信息。
|
||||
|
||||
<!--
|
||||
### Using the dashboard
|
||||
|
||||
By default, the dashboard shows all collected analytics for the past 30 days. Use the date selector to see data from a different date range. Other filtering options allow you to view data based on user location, the device used to access the site, the translation of the docs used, and more.
|
||||
|
||||
If you notice an issue with this dashboard, or would like to request any improvements, please [open an issue](https://github.com/kubernetes/website/issues/new/choose).
|
||||
-->
|
||||
### 使用仪表板
|
||||
|
||||
默认情况下，仪表板显示过去 30 天收集的所有分析。
|
||||
使用日期选择器查看来自不同日期范围的数据。
|
||||
其他过滤选项允许你根据用户位置、用于访问站点的设备、所用文档的翻译等查看数据。
|
||||
|
||||
如果你发现此仪表板存在问题，或者想要请求任何改进，
|
||||
请[开启一个问题](https://github.com/kubernetes/website/issues/new/choose)。
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 参考文档概述
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
|
||||
<!--
|
||||
title: Reference docs overview
|
||||
main_menu: true
|
||||
weight: 80
|
||||
-->
|
||||
|
||||
<!--
|
||||
The topics in this section document how to generate the Kubernetes
|
||||
reference guides.
|
||||
|
||||
To build the reference documentation, see the following guide:
|
||||
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
-->
|
||||
|
||||
本节的主题是描述如何生成 Kubernetes 参考指南。
|
||||
要生成参考文档，请参考下面的指南：
|
||||
|
||||
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
|
||||
|
||||
@@ -0,0 +1,423 @@
|
||||
---
|
||||
title: 为上游 Kubernetes 代码库做出贡献
|
||||
content_type: task
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: Contributing to the Upstream Kubernetes Code
|
||||
content_type: task
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to contribute to the upstream kubernetes/kubernetes project
|
||||
to fix bugs found in the Kubernetes API documentation or the `kube-*`
|
||||
components such as `kube-apiserver`, `kube-controller-manager`, etc.
|
||||
-->
|
||||
此页面描述如何为上游 `kubernetes/kubernetes` 项目做出贡献，如修复 Kubernetes API
|
||||
文档或 Kubernetes 组件（例如 `kubeadm`、`kube-apiserver`、`kube-controller-manager` 等）
|
||||
中发现的错误。
|
||||
|
||||
<!--
|
||||
If you instead want to regenerate the reference documentation for the Kubernetes
|
||||
API or the `kube-*` components from the upstream code, see the following instructions:
|
||||
|
||||
- [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
- [Generating Reference Documentation for the Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
-->
|
||||
如果你仅想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明：
|
||||
|
||||
- [生成 Kubernetes API 的参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
- [生成 Kubernetes 组件和工具的参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
<!--
|
||||
You need to have these tools installed:
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) version 1.13+
|
||||
- [Docker](https://docs.docker.com/engine/installation/)
|
||||
- [etcd](https://github.com/coreos/etcd/)
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
- [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
-->
|
||||
- 你需要安装以下工具：
|
||||
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) 的 1.13 版本或更高
|
||||
- [Docker](https://docs.docker.com/engine/installation/)
|
||||
- [etcd](https://github.com/coreos/etcd/)
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
- [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
|
||||
<!--
|
||||
- Your $GOPATH environment variable must be set, and the location of `etcd`
|
||||
must be in your $PATH environment variable.
|
||||
-->
|
||||
- 你必须设置 `GOPATH` 环境变量，并且 `etcd` 的位置必须在 `PATH` 环境变量中。
|
||||
|
||||
<!--
|
||||
- You need to know how to create a pull request to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository.
|
||||
For more information, see
|
||||
[Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) and
|
||||
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||||
-->
|
||||
- 你需要知道如何创建对 GitHub 代码仓库的拉取请求（Pull Request）。
|
||||
通常，这涉及创建代码仓库的派生副本。
|
||||
要获取更多的信息请参考[创建 PR](https://help.github.com/articles/creating-a-pull-request/) 和
|
||||
[GitHub 标准派生和 PR 工作流程](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## The big picture
|
||||
|
||||
The reference documentation for the Kubernetes API and the `kube-*` components
|
||||
such as `kube-apiserver`, `kube-controller-manager` are automatically generated
|
||||
from the source code in the [upstream Kubernetes](https://github.com/kubernetes/kubernetes/).
|
||||
|
||||
When you see bugs in the generated documentation, you may want to consider
|
||||
creating a patch to fix it in the upstream project.
|
||||
-->
|
||||
## 基本说明
|
||||
|
||||
Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档
|
||||
是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。
|
||||
|
||||
当你在生成的文档中看到错误时，你可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。
|
||||
|
||||
<!--
|
||||
## Cloning the Kubernetes repository
|
||||
|
||||
If you don't already have the kubernetes/kubernetes repository, get it now:
|
||||
-->
|
||||
## 克隆 Kubernetes 代码仓库
|
||||
|
||||
如果你还没有 kubernetes/kubernetes 代码仓库，请参照下列命令获取：
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/kubernetes
|
||||
```
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
-->
|
||||
确定你的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的根目录。
|
||||
例如，如果按照前面的步骤获取代码仓库，则你的根目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。
|
||||
接下来其余步骤将你的根目录称为 `<k8s-base>`。
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
-->
|
||||
确定你的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
代码仓库克隆的根目录。
|
||||
例如，如果按照前面的步骤获取代码仓库，则你的根目录为
|
||||
`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
接下来其余步骤将你的根目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
## Editing the Kubernetes source code
|
||||
|
||||
The Kubernetes API reference documentation is automatically generated from
|
||||
an OpenAPI spec, which is generated from the Kubernetes source code. If you
|
||||
want to change the API reference documentation, the first step is to change one
|
||||
or more comments in the Kubernetes source code.
|
||||
-->
|
||||
## 编辑 Kubernetes 源代码
|
||||
|
||||
Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。
|
||||
如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。
|
||||
|
||||
<!--
|
||||
The documentation for the `kube-*` components is also generated from the upstream
|
||||
source code. You must change the code related to the component
|
||||
you want to fix in order to fix the generated documentation.
|
||||
-->
|
||||
`kube-*` 组件的文档也是从上游源代码生成的。你必须更改与要修复的组件相关的代码，才能修复生成的文档。
|
||||
|
||||
<!--
|
||||
### Making changes to the upstream source code
|
||||
|
||||
The following steps are an example, not a general procedure. Details
|
||||
will be different in your situation.
|
||||
-->
|
||||
### 更改上游 Kubernetes 源代码
|
||||
|
||||
{{< note >}}
|
||||
以下步骤仅作为示例，不是通用步骤，具体情况因环境而异。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
Here's an example of editing a comment in the Kubernetes source code.
|
||||
|
||||
In your local kubernetes/kubernetes repository, check out the default branch,
|
||||
and make sure it is up to date:
|
||||
-->
|
||||
以下在 Kubernetes 源代码中编辑注释的示例。
|
||||
|
||||
在你本地的 kubernetes/kubernetes 代码仓库中，检出默认分支，并确保它是最新的：
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout master
|
||||
git pull https://github.com/kubernetes/kubernetes master
|
||||
```
|
||||
|
||||
<!--
|
||||
Suppose this source file in that default branch has the typo "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)
|
||||
|
||||
<!--
|
||||
In your local environment, open `types.go`, and change "atmost" to "at most".
|
||||
|
||||
Verify that you have changed the file:
|
||||
-->
|
||||
在你的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。
|
||||
|
||||
以下命令验证你已经更改了文件：
|
||||
|
||||
```shell
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output shows that you are on the master branch, and that the `types.go`
|
||||
source file has been modified:
|
||||
-->
|
||||
输出显示你在 master 分支上，`types.go` 源文件已被修改：
|
||||
|
||||
```shell
|
||||
On branch master
|
||||
...
|
||||
modified: staging/src/k8s.io/api/apps/v1/types.go
|
||||
```
|
||||
|
||||
<!--
|
||||
### Committing your edited file
|
||||
|
||||
Run `git add` and `git commit` to commit the changes you have made so far. In the next step,
|
||||
you will do a second commit. It is important to keep your changes separated into two commits.
|
||||
-->
|
||||
### 提交已编辑的文件
|
||||
|
||||
运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。
|
||||
在下一步中，你将进行第二次提交，将更改分成两个提交很重要。
|
||||
|
||||
<!--
|
||||
### Generating the OpenAPI spec and related files
|
||||
|
||||
Go to `<k8s-base>` and run these scripts:
|
||||
-->
|
||||
### 生成 OpenAPI 规范和相关文件
|
||||
|
||||
进入 `<k8s-base>` 目录并运行以下脚本：
|
||||
|
||||
```shell
|
||||
hack/update-generated-swagger-docs.sh
|
||||
hack/update-openapi-spec.sh
|
||||
hack/update-generated-protobuf.sh
|
||||
```
|
||||
|
||||
<!-- Run `git status` to see what was generated. -->
|
||||
运行 `git status` 命令查看生成的文件。
|
||||
|
||||
```none
|
||||
On branch master
|
||||
...
|
||||
modified: api/openapi-spec/swagger.json
|
||||
modified: api/openapi-spec/v3/apis__apps__v1_openapi.json
|
||||
modified: pkg/generated/openapi/zz_generated.openapi.go
|
||||
modified: staging/src/k8s.io/api/apps/v1/generated.proto
|
||||
modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go
|
||||
```
|
||||
|
||||
<!--
|
||||
View the contents of `api/openapi-spec/swagger.json` to make sure the typo is fixed.
|
||||
For example, you could run `git diff -a api/openapi-spec/swagger.json`.
|
||||
This is important, because `swagger.json` is the input to the second stage of
|
||||
the doc generation process.
|
||||
-->
|
||||
查看 `api/openapi-spec/swagger.json` 的内容，以确保拼写错误已经被修正。
|
||||
例如，你可以运行 `git diff -a api/openapi-spec/swagger.json` 命令。
|
||||
这很重要，因为 `swagger.json` 是文档生成过程中第二阶段的输入。
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit your changes. Now you have two commits:
|
||||
one that contains the edited `types.go` file, and one that contains the generated OpenAPI spec
|
||||
and related files. Keep these two commits separate. That is, do not squash your commits.
|
||||
-->
|
||||
运行 `git add` 和 `git commit` 命令来提交你的更改。现在你有两个提交（commits）：
|
||||
一种包含编辑的 `types.go` 文件，另一种包含生成的 OpenAPI 规范和相关文件。
|
||||
将这两个提交分开独立。也就是说，不要 squash 你的提交。
|
||||
|
||||
<!--
|
||||
Submit your changes as a
|
||||
[pull request](https://help.github.com/articles/creating-a-pull-request/) to the
|
||||
master branch of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
Monitor your pull request, and respond to reviewer comments as needed. Continue
|
||||
to monitor your pull request until it is merged.
|
||||
-->
|
||||
将你的更改作为 [PR](https://help.github.com/articles/creating-a-pull-request/)
|
||||
提交到 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库的 master 分支。
|
||||
关注你的 PR，并根据需要回复 reviewer 的评论。继续关注你的 PR，直到 PR 被合并为止。
|
||||
|
||||
<!--
|
||||
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758)
|
||||
is an example of a pull request that fixes a typo in the Kubernetes source code.
|
||||
-->
|
||||
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes
|
||||
源代码中的拼写错误的拉取请求的示例。
|
||||
|
||||
<!--
|
||||
It can be tricky to determine the correct source file to be changed. In the
|
||||
preceding example, the authoritative source file is in the `staging` directory
|
||||
in the `kubernetes/kubernetes` repository. But in your situation,the `staging` directory
|
||||
might not be the place to find the authoritative source. For guidance, check the
|
||||
`README` files in
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging)
|
||||
repository and in related repositories, such as
|
||||
[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md).
|
||||
-->
|
||||
{{< note >}}
|
||||
确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 `kubernetes/kubernetes`
|
||||
代码仓库的 `staging` 目录中。但是根据你的情况，`staging` 目录可能不是找到官方源文件的地方。
|
||||
如果需要帮助，请阅读
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging)
|
||||
代码仓库和相关代码仓库
|
||||
（例如 [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md)）
|
||||
中的 `README` 文件。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Cherry picking your commit into a release branch
|
||||
|
||||
In the preceding section, you edited a file in the master branch and then ran scripts
|
||||
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 {{< skew latestVersion >}}, and you want to backport your change into the
|
||||
release-{{< skew prevMinorVersion >}} branch.
|
||||
-->
|
||||
### 将你的提交 Cherrypick 到发布分支
|
||||
|
||||
在上一节中，你在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。
|
||||
然后用 PR 将你的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支中。
|
||||
现在，需要将你的更改反向移植到已经发布的分支。
|
||||
例如，假设 master 分支被用来开发 Kubernetes {{< skew latestVersion >}} 版，
|
||||
并且你想将更改反向移植到 release-{{< skew prevMinorVersion >}} 分支。
|
||||
|
||||
<!--
|
||||
Recall that your pull request has two commits: one for editing `types.go`
|
||||
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
|
||||
commit into the release-{{< skew prevMinorVersion >}} branch. The idea is to cherry pick the commit
|
||||
that edited `types.go`, but not the commit that has the results of running the scripts. For instructions, see
|
||||
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
|
||||
-->
|
||||
回想一下，你的 PR 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。
|
||||
下一步是将你的第一次提交 cherrypick 到 release-{{< skew prevMinorVersion >}} 分支。
|
||||
这样做的原因是仅 cherrypick 编辑了 types.go 的提交，
|
||||
而不是具有脚本运行结果的提交。
|
||||
有关说明，请参见[提出 Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
|
||||
|
||||
<!--
|
||||
Proposing a cherry pick requires that you have permission to set a label and a milestone in your
|
||||
pull request. If you don't have those permissions, you will need to work with someone who can set the label
|
||||
and milestone for you.
|
||||
-->
|
||||
{{< note >}}
|
||||
提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果你没有这些权限，
|
||||
则需要与可以为你设置标签和里程碑的人员合作。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
When you have a pull request in place for cherry picking your one commit into the
|
||||
release-{{< skew prevMinorVersion >}} branch, the next step is to run these scripts in the
|
||||
release-{{< skew prevMinorVersion >}} branch of your local environment.
|
||||
-->
|
||||
当你发起 PR 将你的一个提交 cherry pick 到 release-{{< skew prevMinorVersion >}} 分支中时，
|
||||
下一步是在本地环境的 release-{{< skew prevMinorVersion >}} 分支中运行如下脚本。
|
||||
|
||||
```shell
|
||||
hack/update-generated-swagger-docs.sh
|
||||
hack/update-openapi-spec.sh
|
||||
hack/update-generated-protobuf.sh
|
||||
hack/update-api-reference-docs.sh
|
||||
```
|
||||
|
||||
<!--
|
||||
Now add a commit to your cherry-pick pull request that has the recently generated OpenAPI spec
|
||||
and related files. Monitor your pull request until it gets merged into the
|
||||
release-{{< skew prevMinorVersion >}} branch.
|
||||
-->
|
||||
现在将提交添加到你的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。
|
||||
关注你的 PR，直到其合并到 release-{{< skew prevMinorVersion >}} 分支中为止。
|
||||
|
||||
<!--
|
||||
At this point, both the master branch and the release-{{< skew prevMinorVersion >}} branch have your updated `types.go`
|
||||
file and a set of generated files that reflect the change you made to `types.go`. Note that the
|
||||
generated OpenAPI spec and other generated files in the release-{{< skew prevMinorVersion >}} branch are not necessarily
|
||||
the same as the generated files in the master branch. The generated files in the release-{{< skew prevMinorVersion >}} branch
|
||||
contain API elements only from Kubernetes {{< skew prevMinorVersion >}}. The generated files in the master branch might contain
|
||||
API elements that are not in {{< skew prevMinorVersion >}}, but are under development for {{< skew latestVersion >}}.
|
||||
-->
|
||||
此时，master 分支和 release-{{< skew prevMinorVersion >}}
|
||||
分支都具有更新的 `types.go` 文件和一组生成的文件，
|
||||
这些文件反映了对 `types.go` 所做的更改。
|
||||
请注意，生成的 OpenAPI 规范和其他 release-{{< skew prevMinorVersion >}}
|
||||
分支中生成的文件不一定与 master 分支中生成的文件相同。
|
||||
release-{{< skew prevMinorVersion >}} 分支中生成的文件仅包含来自
|
||||
Kubernetes {{< skew prevMinorVersion >}} 的 API 元素。
|
||||
master 分支中生成的文件可能包含不在 {{< skew prevMinorVersion >}}
|
||||
中但正在为 {{< skew latestVersion >}} 开发的 API 元素。
|
||||
|
||||
<!--
|
||||
## Generating the published reference docs
|
||||
|
||||
The preceding section showed how to edit a source file and then generate
|
||||
several files, including `api/openapi-spec/swagger.json` in the
|
||||
`kubernetes/kubernetes` repository.
|
||||
The `swagger.json` file is the OpenAPI definition file to use for generating
|
||||
the API reference documentation.
|
||||
-->
|
||||
## 生成已发布的参考文档
|
||||
|
||||
上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的
|
||||
`api/openapi-spec/swagger.json`。`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。
|
||||
|
||||
<!--
|
||||
You are now ready to follow the [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) guide to generate the
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
-->
|
||||
现在，你可以按照
|
||||
[生成 Kubernetes API 的参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
指南来生成
|
||||
[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
|
||||
-->
|
||||
* [生成 Kubernetes API 的参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [生成 kubectl 命令的参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
|
||||
|
||||
@@ -0,0 +1,431 @@
|
||||
---
|
||||
title: 为 kubectl 命令集生成参考文档
|
||||
content_type: task
|
||||
weight: 90
|
||||
---
|
||||
|
||||
<!--
|
||||
title: Generating Reference Documentation for kubectl Commands
|
||||
content_type: task
|
||||
weight: 90
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to generate the `kubectl` command reference.
|
||||
-->
|
||||
|
||||
本页面描述了如何生成 `kubectl` 命令参考。
|
||||
|
||||
<!--
|
||||
This topic shows how to generate reference documentation for
|
||||
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
|
||||
like
|
||||
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and
|
||||
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint).
|
||||
This topic does not show how to generate the
|
||||
[kubectl](/docs/reference/generated/kubectl/kubectl/)
|
||||
options reference page. For instructions on how to generate the kubectl options
|
||||
reference page, see
|
||||
[Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/).
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
本主题描述了如何为 [kubectl 命令](/docs/reference/generated/kubectl/kubectl-commands)
|
||||
生成参考文档，如 [kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) 和
|
||||
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint)。
|
||||
本主题没有讨论如何生成 [kubectl](/docs/reference/generated/kubectl/kubectl-commands/) 组件选项的参考页面。
|
||||
相关说明请参见[为 Kubernetes 组件和工具生成参考页面](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)。
|
||||
{{< /note >}}
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Setting up the local repositories
|
||||
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
-->
|
||||
## 配置本地仓库
|
||||
|
||||
创建本地工作区并设置你的 `GOPATH`。
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
export GOPATH=$HOME/<workspace>
|
||||
```
|
||||
|
||||
<!-- Get a local clone of the following repositories: -->
|
||||
获取以下仓库的本地克隆：
|
||||
|
||||
```shell
|
||||
go get -u github.com/spf13/pflag
|
||||
go get -u github.com/spf13/cobra
|
||||
go get -u gopkg.in/yaml.v2
|
||||
go get -u kubernetes-incubator/reference-docs
|
||||
```
|
||||
|
||||
<!--
|
||||
If you don't already have the kubernetes/website repository, get it now:
|
||||
-->
|
||||
如果你还没有获取过 `kubernetes/website` 仓库，现在获取之：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
|
||||
```
|
||||
|
||||
<!-- Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes: -->
|
||||
克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
```
|
||||
|
||||
<!--
|
||||
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
|
||||
-->
|
||||
从 `$GOPATH/src/k8s.io/kubernetes/vendor/github.com` 中移除 spf13 软件包。
|
||||
|
||||
```shell
|
||||
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
|
||||
```
|
||||
|
||||
<!-- The kubernetes/kubernetes repository provides access to the kubectl and kustomize source code. -->
|
||||
kubernetes/kubernetes 仓库提供对 kubectl 和 kustomize 源代码的访问。
|
||||
|
||||
<!--
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/k8s.io/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
-->
|
||||
* 确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。
|
||||
例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。
|
||||
下文将该目录称为 `<k8s-base>`。
|
||||
|
||||
<!--
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/<your-username>/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
-->
|
||||
* 确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。
|
||||
例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/<your-username>/website`。
|
||||
下文将该目录称为 `<web-base>`。
|
||||
|
||||
<!--
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`. -->
|
||||
* 确定 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是
|
||||
`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
下文将该目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
In your local k8s.io/kubernetes repository, check out the branch of interest,
|
||||
and make sure it is up to date. For example, if you want to generate docs for
|
||||
Kubernetes {{< skew prevMinorVersion >}}.0, you could use these commands:
|
||||
-->
|
||||
在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如，
|
||||
如果你想要生成 Kubernetes {{< skew prevMinorVersion >}}.0 的文档，可以使用以下命令：
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout v{{< skew prevMinorVersion >}}.0
|
||||
git pull https://github.com/kubernetes/kubernetes {{< skew prevMinorVersion >}}.0
|
||||
```
|
||||
|
||||
<!--
|
||||
If you do not need to edit the kubectl source code, follow the instructions to
|
||||
[Setting build variables](#setting-build-variables).
|
||||
-->
|
||||
如果不需要编辑 `kubectl`
|
||||
源码，请按照说明[配置构建变量](#setting-build-variables)。
|
||||
|
||||
<!--
|
||||
## Editing the kubectl source code
|
||||
|
||||
The kubectl command reference documentation is automatically generated from
|
||||
the kubectl source code. If you want to change the reference documentation, the first step
|
||||
is to change one or more comments in the kubectl source code. Make the change in your
|
||||
local kubernetes/kubernetes repository, and then submit a pull request to the master branch of
|
||||
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
||||
-->
|
||||
## 编辑 kubectl 源码
|
||||
|
||||
kubectl 命令的参考文档是基于 kubectl 源码自动生成的。如果想要修改参考文档，可以从修改
|
||||
kubectl 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向
|
||||
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 的 master
|
||||
分支提交 PR。
|
||||
|
||||
<!--
|
||||
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files)
|
||||
is an example of a pull request that fixes a typo in the kubectl source code.
|
||||
|
||||
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
|
||||
pull request until it is merged into the target branch of the kubernetes/kubernetes repository.
|
||||
-->
|
||||
|
||||
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl
|
||||
源码中的笔误进行修复的 PR 示例。
|
||||
|
||||
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的目标分支中。
|
||||
|
||||
<!--
|
||||
## Cherry picking your change into a release branch
|
||||
|
||||
Your change is now in the master branch, which is used for development of the next
|
||||
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
|
||||
version that has already been released, you need to propose that your change be
|
||||
cherry picked into the release branch.
|
||||
-->
|
||||
## 以 cherry-pick 方式将你的修改合入已发布分支
|
||||
|
||||
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。
|
||||
如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以
|
||||
cherry-pick 方式合入已发布分支。
|
||||
|
||||
<!--
|
||||
For example, suppose the master branch is being used to develop Kubernetes
|
||||
{{< skew currentVersion >}}
|
||||
and you want to backport your change to the release-{{< skew prevMinorVersion >}} branch. For instructions
|
||||
on how to do this, see
|
||||
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
|
||||
|
||||
Monitor your cherry-pick pull request until it is merged into the release branch.
|
||||
-->
|
||||
|
||||
例如，假设 master 分支正用于开发 Kubernetes {{< skew currentVersion >}} 版本，
|
||||
而你希望将修改合入到 release-{{< skew prevMinorVersion >}} 版本分支。
|
||||
相关的操作指南，请参见
|
||||
[提议一个 cherry-pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
|
||||
|
||||
跟踪你的 cherry-pick PR，直到它合入到已发布分支中。
|
||||
|
||||
<!--
|
||||
Proposing a cherry pick requires that you have permission to set a label and a
|
||||
milestone in your pull request. If you don’t have those permissions, you will
|
||||
need to work with someone who can set the label and milestone for you.
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
提议一个 cherry-pick 需要你有在 PR 中设置标签和里程碑的权限。
|
||||
如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Setting build variables
|
||||
|
||||
Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
||||
-->
|
||||
## 设置构建变量 {#setting-build-variables}
|
||||
|
||||
进入 `<rdocs-base>` 目录, 打开 `Makefile` 进行编辑：
|
||||
|
||||
<!--
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
* Set `K8S_WEBROOT` to `<web-base>`.
|
||||
* Set `K8S_RELEASE` to the version of the docs you want to build.
|
||||
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-base>`。
|
||||
* 设置 `K8S_WEBROOT` 为 `<web-base>`。
|
||||
* 设置 `K8S_RELEASE` 为要构建文档的版本。
|
||||
例如，如果你想为 Kubernetes {{< skew prevMinorVersion >}} 构建文档，
|
||||
请将 `K8S_RELEASE` 设置为 {{< skew prevMinorVersion >}}。
|
||||
|
||||
例如：
|
||||
|
||||
```
|
||||
export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
|
||||
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
|
||||
export K8S_RELEASE={{< skew prevMinorVersion >}}
|
||||
```
|
||||
|
||||
<!--
|
||||
## Creating a versioned directory
|
||||
|
||||
The `createversiondirs` build target creates a versioned directory
|
||||
and copies the kubectl reference configuration files to the versioned directory.
|
||||
The versioned directory name follows the pattern of `v<major>_<minor>`.
|
||||
|
||||
In the `<rdocs-base>` directory, run the following build target:
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make createversiondirs
|
||||
```
|
||||
-->
|
||||
## 创建版本目录
|
||||
|
||||
构建目标 `createversiondirs` 会生成一个版本目录并将 kubectl 参考配置文件复制到该目录中。
|
||||
版本目录的名字模式为 `v<major>_<minor>`。
|
||||
|
||||
在 `<rdocs-base>` 目录下，执行下面的命令：
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make createversiondirs
|
||||
```
|
||||
|
||||
<!--
|
||||
## Checking out a branch in k8s.io/kubernetes
|
||||
|
||||
In your local <k8s-base> repository, checkout the branch that has
|
||||
the version of Kubernetes that you want to document. For example, if you want
|
||||
to generate docs for Kubernetes {{< skew prevMinorVersion >}}.0, checkout the `v{{< skew prevMinorVersion >}}` tag. Make sure
|
||||
you local branch is up to date.
|
||||
-->
|
||||
## 从 kubernetes/kubernetes 检出一个分支
|
||||
|
||||
在本地 `<k8s-base>` 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。
|
||||
例如，如果希望为 Kubernetes {{< skew prevMinorVersion >}}.0 版本生成文档，
|
||||
请检出 `v{{< skew prevMinorVersion >}}` 标记。
|
||||
确保本地分支是最新的。
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout v{{< skew prevMinorVersion >}}.0
|
||||
git pull https://github.com/kubernetes/kubernetes v{{< skew prevMinorVersion >}}.0
|
||||
```
|
||||
|
||||
<!--
|
||||
## Running the doc generation code
|
||||
|
||||
In your local kubernetes-incubator/reference-docs repository, build and run the
|
||||
kubectl command reference generation code. You might need to run the command as root:
|
||||
-->
|
||||
## 运行文档生成代码
|
||||
|
||||
在本地的 `<rdocs-base>` 目录下，运行 `copycli` 构建目标。此命令以 `root` 账号运行：
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make copycli
|
||||
```
|
||||
|
||||
<!--
|
||||
The `copycli` command will clean the staging directories, generate the kubectl command files,
|
||||
and copy the collated kubectl reference HTML page and assets to `<web-base>`.
|
||||
-->
|
||||
`copycli` 命令将清理暂存目录，生成 kubectl 命令文件，并将整理后的 kubectl 参考 HTML 页面和
|
||||
文件复制到 `<web-base>`。
|
||||
|
||||
<!--
|
||||
## Locate the generated files
|
||||
|
||||
Verify that these two files have been generated:
|
||||
-->
|
||||
## 找到生成的文件
|
||||
|
||||
验证是否已生成以下两个文件：
|
||||
|
||||
```shell
|
||||
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
|
||||
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
|
||||
```
|
||||
|
||||
<!--
|
||||
## Locate the copied files
|
||||
|
||||
Verify that all generated files have been copied to your `<web-base>`:
|
||||
-->
|
||||
## 找到复制的文件
|
||||
|
||||
确认所有生成的文件都已复制到你的 `<web-base>`：
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!-- The output should include the modified files: -->
|
||||
输出应包括修改后的文件：
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/kubectl-commands.html
|
||||
static/docs/reference/generated/kubectl/navData.js
|
||||
```
|
||||
|
||||
<!-- Additionally, the output might show the modified files: -->
|
||||
|
||||
此外，输出可能还包含：
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/scroll.js
|
||||
static/docs/reference/generated/kubectl/stylesheet.css
|
||||
static/docs/reference/generated/kubectl/tabvisibility.js
|
||||
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
|
||||
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css
|
||||
```
|
||||
|
||||
<!--
|
||||
## Locally test the documentation
|
||||
|
||||
Build the Kubernetes documentation in your local `<web-base>`.
|
||||
-->
|
||||
## 在本地测试文档
|
||||
|
||||
在本地 `<web-base>` 中构建 Kubernetes 文档。
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git submodule update --init --recursive --depth 1 # if not already done
|
||||
make container-serve
|
||||
```
|
||||
|
||||
<!-- View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/). -->
|
||||
查看[本地预览](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/)。
|
||||
|
||||
<!--
|
||||
## Adding and committing changes in kubernetes/website
|
||||
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
-->
|
||||
## 在 kubernetes/website 中添加和提交更改
|
||||
|
||||
运行 `git add` 和 `git commit` 提交修改文件。
|
||||
|
||||
<!--
|
||||
## Creating a pull request
|
||||
|
||||
Create a pull request to the `kubernetes/website` repository. Monitor your
|
||||
pull request, and respond to review comments as needed. Continue to monitor
|
||||
your pull request until it is merged.
|
||||
|
||||
A few minutes after your pull request is merged, your updated reference
|
||||
topics will be visible in the
|
||||
[published documentation](/docs/home).
|
||||
-->
|
||||
## 创建 PR
|
||||
|
||||
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。
|
||||
继续跟踪你的 PR，直到它被合入。
|
||||
|
||||
在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/zh/docs/home/)中。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
-->
|
||||
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 Kubernetes API 生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
|
||||
@@ -0,0 +1,322 @@
|
||||
---
|
||||
title: 为 Kubernetes API 生成参考文档
|
||||
content_type: task
|
||||
weight: 50
|
||||
---
|
||||
<!--
|
||||
title: Generating Reference Documentation for the Kubernetes API
|
||||
content_type: task
|
||||
weight: 50
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to update the Kubernetes API reference documentation.
|
||||
|
||||
The Kubernetes API reference documentation is built from the
|
||||
[Kubernetes OpenAPI spec](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
|
||||
using the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) generation code.
|
||||
|
||||
If you find bugs in the generated documentation, you need to
|
||||
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
|
||||
|
||||
If you need only to regenerate the reference documentation from the [OpenAPI](https://github.com/OAI/OpenAPI-Specification)
|
||||
spec, continue reading this page.
|
||||
-->
|
||||
本页面显示了如何更新 Kubernetes API 参考文档。
|
||||
|
||||
Kubernetes API 参考文档是从
|
||||
[Kubernetes OpenAPI 规范](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
|
||||
构建的，
|
||||
且使用[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) 生成代码。
|
||||
|
||||
如果你在生成的文档中发现错误，则需要[在上游修复](/zh/docs/contribute/generate-ref-docs/contribute-upstream/)。
|
||||
|
||||
如果你只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Setting up the local repositories
|
||||
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
-->
|
||||
## 配置本地仓库
|
||||
|
||||
创建本地工作区并设置你的 `GOPATH`。
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
export GOPATH=$HOME/<workspace>
|
||||
```
|
||||
|
||||
<!--
|
||||
Get a local clone of the following repositories:
|
||||
-->
|
||||
获取以下仓库的本地克隆：
|
||||
|
||||
```shell
|
||||
go get -u github.com/kubernetes-sigs/reference-docs
|
||||
|
||||
go get -u github.com/go-openapi/loads
|
||||
go get -u github.com/go-openapi/spec
|
||||
```
|
||||
|
||||
<!--
|
||||
If you don't already have the kubernetes/website repository, get it now:
|
||||
-->
|
||||
如果你还没有下载过 `kubernetes/website` 仓库，现在下载：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
|
||||
```
|
||||
|
||||
<!--
|
||||
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
|
||||
-->
|
||||
克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
```
|
||||
|
||||
<!--
|
||||
* The base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is
|
||||
`$GOPATH/src/k8s.io/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
|
||||
* The base directory of your clone of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository is
|
||||
`$GOPATH/src/github.com/<your username>/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
|
||||
* The base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
repository is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
-->
|
||||
* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的根目录为
|
||||
`$GOPATH/src/k8s.io/kubernetes`。 后续步骤将此目录称为 `<k8s-base>`。
|
||||
* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的根目录为
|
||||
`$GOPATH/src/github.com/<your username>/website`。后续步骤将此目录称为 `<web-base>`。
|
||||
* [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`。
|
||||
后续步骤将此目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
## Generating the API reference docs
|
||||
|
||||
This section shows how to generate the
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
-->
|
||||
## 生成 API 参考文档
|
||||
|
||||
本节说明如何生成[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。
|
||||
|
||||
<!--
|
||||
### Setting build variables
|
||||
|
||||
Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
||||
-->
|
||||
### 设置构建变量 {#setting-build-variables}
|
||||
|
||||
<!--
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
* Set `K8S_WEBROOT` to `<web-base>`.
|
||||
* 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.0, set `K8S_RELEASE` to 1.17.0.
|
||||
-->
|
||||
* 设置 `K8S_ROOT` 为 `<k8s-base>`.
|
||||
* 设置 `K8S_WEBROOT` 为 `<web-base>`.
|
||||
* 设置 `K8S_RELEASE` 为要构建的文档的版本。
|
||||
例如，如果你想为 Kubernetes 1.17.0 构建文档，请将 `K8S_RELEASE` 设置为 1.17.0。
|
||||
|
||||
<!--
|
||||
For example:
|
||||
-->
|
||||
例如：
|
||||
|
||||
```shell
|
||||
export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
|
||||
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
|
||||
export K8S_RELEASE=1.17.0
|
||||
```
|
||||
|
||||
<!--
|
||||
### Creating versioned directory and fetching Open API spec
|
||||
|
||||
The `updateapispec` build target creates the versioned build directory.
|
||||
After the directory is created, the Open API spec is fetched from the
|
||||
`<k8s-base>` repository. These steps ensure that the version
|
||||
of the configuration files and Kubernetes Open API spec match the release version.
|
||||
The versioned directory name follows the pattern of `v<major>_<minor>`.
|
||||
-->
|
||||
### 创建版本目录并复制 OpenAPI 规范
|
||||
|
||||
构建目标 `updateapispec` 负责创建版本化的构建目录。
|
||||
目录创建了之后，从 `<k8s-base>` 仓库取回 OpenAPI 规范文件。
|
||||
这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。
|
||||
版本化目录的名称形式为 `v<major>_<minor>`。
|
||||
|
||||
<!--
|
||||
In the `<rdocs-base>` directory, run the following build target:
|
||||
-->
|
||||
在 `<rdocs-base>` 目录中，运行以下命令来构建：
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make updateapispec
|
||||
```
|
||||
|
||||
<!--
|
||||
### Building the API reference docs
|
||||
|
||||
The `copyapi` target builds the API reference and
|
||||
copies the generated files to directories in `<web-base>`.
|
||||
Run the following command in `<rdocs-base>`:
|
||||
|
||||
-->
|
||||
### 构建 API 参考文档
|
||||
|
||||
构建目标 `copyapi` 会生成 API 参考文档并将所生成文件复制到
|
||||
`<web-base` 中的目录下。
|
||||
在 `<rdocs-base>` 目录中运行以下命令：
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make copyapi
|
||||
```
|
||||
|
||||
<!--
|
||||
Verify that these two files have been generated:
|
||||
-->
|
||||
验证是否已生成这两个文件：
|
||||
|
||||
```shell
|
||||
[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
|
||||
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
|
||||
```
|
||||
|
||||
<!--
|
||||
Go to the base of your local `<web-base>`, and
|
||||
view which files have been modified:
|
||||
-->
|
||||
进入本地 `<web-base>` 目录，检查哪些文件被更改：
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output is similar to:
|
||||
-->
|
||||
输出类似于：
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js
|
||||
```
|
||||
|
||||
<!--
|
||||
## Updating the API reference index pages
|
||||
|
||||
When generating reference documentation for a new release, update the file,
|
||||
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` with the new
|
||||
version number.
|
||||
-->
|
||||
## 更新 API 参考索引页面
|
||||
|
||||
在为新发行版本生成参考文档时，需要更新下面的文件，使之包含新的版本号：
|
||||
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md`。
|
||||
|
||||
<!--
|
||||
* Open `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` for editing,
|
||||
and update the API reference version number. For example:
|
||||
|
||||
```
|
||||
title: v1.17
|
||||
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
|
||||
```
|
||||
-->
|
||||
* 打开并编辑 `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md`，
|
||||
API 参考的版本号。例如：
|
||||
|
||||
```
|
||||
title: v1.17
|
||||
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
|
||||
```
|
||||
<!--
|
||||
* Open `<web-base>/content/en/docs/reference/_index.md` for editing, and add a
|
||||
new link for the latest API reference. Remove the oldest API reference version.
|
||||
There should be five links to the most recent API references.
|
||||
-->
|
||||
* 打开编辑 `<web-base>/content/en/docs/reference/_index.md`，添加指向最新 API 参考
|
||||
的链接，删除最老的 API 版本。
|
||||
通常保留最近的五个版本的 API 参考的链接。
|
||||
|
||||
<!--
|
||||
## Locally test the API reference
|
||||
|
||||
Publish a local version of the API reference.
|
||||
Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/{{< param "version">}}/).
|
||||
-->
|
||||
## 在本地测试 API 参考
|
||||
|
||||
发布 API 参考的本地版本。
|
||||
检查[本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/{{< param "version">}}/)。
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git submodule update --init --recursive --depth 1 # if not already done
|
||||
make container-serve
|
||||
```
|
||||
|
||||
<!--
|
||||
## Commit the changes
|
||||
|
||||
In `<web-base>` run `git add` and `git commit` to commit the change.
|
||||
-->
|
||||
## 提交更改
|
||||
|
||||
在 `<web-base>` 中运行 `git add` 和 `git commit` 来提交更改。
|
||||
|
||||
<!--
|
||||
Submit your changes as a
|
||||
[pull request](/docs/contribute/new-content/open-a-pr/) to the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
Monitor your pull request, and respond to reviewer comments as needed. Continue
|
||||
to monitor your pull request until it has been merged.
|
||||
-->
|
||||
基于你所生成的更改[创建 PR](/zh/docs/contribute/new-content/open-a-pr/)，
|
||||
提交到 [kubernetes/website](https://github.com/kubernetes/website) 仓库。
|
||||
监视你提交的 PR，并根据需要回复 reviewer 的评论。继续监视你的 PR，直到合并为止。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
-->
|
||||
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 kubectl 命令集生成参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: 为 Kubernetes 组件和工具生成参考文档
|
||||
content_type: task
|
||||
weight: 120
|
||||
---
|
||||
<!--
|
||||
title: Generating Reference Pages for Kubernetes Components and Tools
|
||||
content_type: task
|
||||
weight: 120
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to build the Kubernetes component and tool reference pages.
|
||||
-->
|
||||
|
||||
本页面描述如何构造 Kubernetes 组件和工具的参考文档。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
<!--
|
||||
Start with the [Prerequisites section](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)
|
||||
in the Reference Documentation Quickstart guide.
|
||||
-->
|
||||
阅读参考文档快速入门指南中的[准备工作](/zh/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)节。
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
Follow the [Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
to generate the Kubernetes component and tool reference pages.
|
||||
-->
|
||||
按照[参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
|
||||
指引，生成 Kubernetes 组件和工具的参考文档。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/generate-ref-docs/contribute-upstream/)
|
||||
-->
|
||||
|
||||
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 kubectll 命令生成参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [为 Kubernetes API 生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [为上游 Kubernetes 项目做贡献以改进文档](/zh/docs/contribute/generate-ref-docs/contribute-upstream/)
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
<!--
|
||||
### Requirements:
|
||||
|
||||
- You need a machine that is running Linux or macOS.
|
||||
|
||||
- You need to have these tools installed:
|
||||
|
||||
- [Python](https://www.python.org/downloads/) v3.7.x
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) version 1.13+
|
||||
- [Pip](https://pypi.org/project/pip/) used to install PyYAML
|
||||
- [PyYAML](https://pyyaml.org/) v5.1.2
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
- [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
- [Docker](https://docs.docker.com/engine/installation/) (Required only for `kubectl` command reference)
|
||||
-->
|
||||
|
||||
### 需求 {#requirements}
|
||||
|
||||
- 你需要一台 Linux 或 macOS 机器。
|
||||
|
||||
- 你需要安装以下工具：
|
||||
|
||||
- [Python](https://www.python.org/downloads/) v3.7.x
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) 1.13+ 版本
|
||||
- 用来安装 PyYAML 的 [Pip](https://pypi.org/project/pip/)
|
||||
- [PyYAML](https://pyyaml.org/) v5.1.2
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
- [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
- [Docker](https://docs.docker.com/engine/installation/) （仅用于 `kubectl` 命令参考）
|
||||
|
||||
<!--
|
||||
- Your `PATH` environment variable must include the required build tools, such as the `Go` binary and `python`.
|
||||
|
||||
- You need to know how to create a pull request to a GitHub repository.
|
||||
This involves creating your own fork of the repository. For more
|
||||
information, see [Work from a local clone](/docs/contribute/new-content/open-a-pr/#fork-the-repo).
|
||||
-->
|
||||
- 你的 `PATH` 环境变量必须包含所需要的构建工具，例如 `Go` 程序和 `python`。
|
||||
|
||||
- 你需要知道如何为一个 GitHub 仓库创建拉取请求（PR）。
|
||||
这牵涉到创建仓库的派生（fork）副本。
|
||||
有关信息可进一步查看[基于本地副本开展工作](/zh/docs/contribute/new-content/open-a-pr/#fork-the-repo)。
|
||||
|
||||
@@ -0,0 +1,405 @@
|
||||
---
|
||||
title: 快速入门
|
||||
content_type: task
|
||||
weight: 40
|
||||
---
|
||||
<!--
|
||||
title: Quickstart
|
||||
content_type: task
|
||||
weight: 40
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to use the `update-imported-docs.py` script to generate
|
||||
the Kubernetes reference documentation. The script automates
|
||||
the build setup and generates the reference documentation for a release.
|
||||
-->
|
||||
本页讨论如何使用 `update-imported-docs.py` 脚本来生成 Kubernetes 参考文档。
|
||||
此脚本将构建的配置过程自动化，并为某个发行版本生成参考文档。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
<!-- steps -->
|
||||
<!--
|
||||
## Getting the docs repository
|
||||
|
||||
Make sure your `website` fork is up-to-date with the `kubernetes/website` remote on
|
||||
GitHub (`main` branch), and clone your `website` fork.
|
||||
-->
|
||||
## 获取文档仓库 {#getting-the-docs-repository}
|
||||
|
||||
确保你的 `website` 派生仓库与 GitHub 上的 `kubernetes/website` 远程仓库（`main` 分支）保持同步，
|
||||
并克隆你的派生仓库。
|
||||
|
||||
```shell
|
||||
mkdir github.com
|
||||
cd github.com
|
||||
git clone git@github.com:<your_github_username>/website.git
|
||||
```
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone. For example, if you followed the
|
||||
preceding step to get the repository, your base directory is
|
||||
`github.com/website.` The remaining steps refer to your base directory as
|
||||
`<web-base>`.
|
||||
|
||||
{{< note>}}
|
||||
If you want to change the content of the component tools and API reference,
|
||||
see the [contributing upstream guide](/docs/contribute/generate-ref-docs/contribute-upstream).
|
||||
{{< /note >}}
|
||||
-->
|
||||
确定你的克隆副本的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录
|
||||
会是 `github.com/website`。接下来的步骤中，`<web-base>` 用来指代你的根目录。
|
||||
|
||||
{{< note>}}
|
||||
如果你希望更改构建工具和 API 参考资料，可以阅读
|
||||
[上游贡献指南](/zh/docs/contribute/generate-ref-docs/contribute-upstream).
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Overview of update-imported-docs
|
||||
|
||||
The `update-imported-docs.py` script is located in the `<web-base>/update-imported-docs/`
|
||||
directory.
|
||||
|
||||
The script builds the following references:
|
||||
|
||||
* Component and tool reference pages
|
||||
* The `kubectl` command reference
|
||||
* The Kubernetes API reference
|
||||
-->
|
||||
## update-imported-docs 的概述
|
||||
|
||||
脚本 `update-imported-docs.py` 位于 `<web-base>/update-imported-docs/` 目录下，
|
||||
能够生成以下参考文档：
|
||||
|
||||
* Kubernetes 组件和工具的参考页面
|
||||
* `kubectl` 命令参考文档
|
||||
* Kubernetes API 参考文档
|
||||
|
||||
<!--
|
||||
The `update-imported-docs.py` script generates the Kubernetes reference documentation
|
||||
from the Kubernetes source code. The script creates a temporary directory
|
||||
under `/tmp` on your machine and clones the required repositories: `kubernetes/kubernetes` and
|
||||
`kubernetes-sigs/reference-docs` into this directory.
|
||||
The script sets your `GOPATH` to this temporary directory.
|
||||
Three additional environment variables are set:
|
||||
|
||||
* `K8S_RELEASE`
|
||||
* `K8S_ROOT`
|
||||
* `K8S_WEBROOT`
|
||||
-->
|
||||
脚本 `update-imported-docs.py` 基于 Kubernetes 源代码生成参考文档。
|
||||
过程中会在你的机器的 `/tmp` 目录下创建临时目录，克隆所需要的仓库
|
||||
`kubernetes/kubernetes` 和 `kubernetes-sigs/reference-docs` 到此临时目录。
|
||||
脚本会将 `GOPATH` 环境变量设置为指向此临时目录。
|
||||
此外，脚本会设置三个环境变量：
|
||||
|
||||
* `K8S_RELEASE`
|
||||
* `K8S_ROOT`
|
||||
* `K8S_WEBROOT`
|
||||
|
||||
<!--
|
||||
The script requires two arguments to run successfully:
|
||||
|
||||
* A YAML configuration file (`reference.yml`)
|
||||
* A release version, for example:`1.17`
|
||||
|
||||
The configuration file contains a `generate-command` field.
|
||||
The `generate-command` field defines a series of build instructions
|
||||
from `kubernetes-sigs/reference-docs/Makefile`. The `K8S_RELEASE` variable
|
||||
determines the version of the release.
|
||||
-->
|
||||
脚本需要两个参数才能成功运行：
|
||||
|
||||
* 一个 YAML 配置文件（`reference.yml`）
|
||||
* 一个发行版本字符串，例如：`1.17`
|
||||
|
||||
配置文件中包含 `generate-command` 字段，其中定义了一系列来自于
|
||||
`kubernetes-sigs/reference-docs/Makefile` 的构建指令。
|
||||
变量 `K8S_RELEASE` 用来确定所针对的发行版本。
|
||||
|
||||
<!--
|
||||
The `update-imported-docs.py` script performs the following steps:
|
||||
|
||||
1. Clones the related repositories specified in a configuration file. For the
|
||||
purpose of generating reference docs, the repository that is cloned by
|
||||
default is `kubernetes-sigs/reference-docs`.
|
||||
1. Runs commands under the cloned repositories to prepare the docs generator and
|
||||
then generates the HTML and Markdown files.
|
||||
1. Copies the generated HTML and Markdown files to a local clone of the `<web-base>`
|
||||
repository under locations specified in the configuration file.
|
||||
1. Updates `kubectl` command links from `kubectl`.md to the refer to
|
||||
the sections in the `kubectl` command reference.
|
||||
-->
|
||||
脚本 `update-imported-docs.py` 执行以下步骤：
|
||||
|
||||
1. 克隆配置文件中所指定的相关仓库。就生成参考文档这一目的而言，要克隆的
|
||||
仓库默认为 `kubernetes-sigs/reference-docs`。
|
||||
1. 在所克隆的仓库下运行命令，准备文档生成器，之后生成 HTML 和 Markdown 文件。
|
||||
1. 将所生成的 HTML 和 Markdown 文件复制到 `<web-base>` 本地克隆副本中，
|
||||
放在配置文件中所指定的目录下。
|
||||
1. 更新 `kubectl.md` 文件中对 `kubectl` 命令文档的链接，使之指向 `kubectl`
|
||||
命令参考中对应的节区。
|
||||
|
||||
<!--
|
||||
When the generated files are in your local clone of the `<web-base>`
|
||||
repository, you can submit them in a [pull request](/docs/contribute/start/)
|
||||
to `<web-base>`.
|
||||
-->
|
||||
当所生成的文件已经被放到 `<web-base>` 目录下，你就可以将其提交到你的派生副本中，
|
||||
并基于所作提交发起[拉取请求（PR）](/docs/contribute/start/)到 k/website 仓库。
|
||||
|
||||
<!--
|
||||
## Configuration file format
|
||||
|
||||
Each configuration file may contain multiple repos that will be imported together. When
|
||||
necessary, you can customize the configuration file by manually editing it. You
|
||||
may create new config files for importing other groups of documents.
|
||||
The following is an example of the YAML configuration file:
|
||||
-->
|
||||
## 配置文件格式 {#configuration-file-format}
|
||||
|
||||
每个配置文件可以包含多个被导入的仓库。当必要时，你可以通过手工编辑此文件进行定制。
|
||||
你也可以通过创建新的配置文件来导入其他文档集合。
|
||||
下面是 YAML 配置文件的一个例子：
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: community
|
||||
remote: https://github.com/kubernetes/community.git
|
||||
branch: master
|
||||
files:
|
||||
- src: contributors/devel/README.md
|
||||
dst: docs/imported/community/devel.md
|
||||
- src: contributors/guide/README.md
|
||||
dst: docs/imported/community/guide.md
|
||||
```
|
||||
|
||||
<!--
|
||||
Single page Markdown documents, imported by the tool, must adhere to
|
||||
the [Documentation Style Guide](/docs/contribute/style/style-guide/).
|
||||
-->
|
||||
通过工具导入的单页面的 Markdown 文档必须遵从
|
||||
[文档样式指南](/zh/docs/contribute/style/style-guide/)。
|
||||
|
||||
<!--
|
||||
## Customizing reference.yml
|
||||
|
||||
Open `<web-base>/update-imported-docs/reference.yml` for editing.
|
||||
Do not change the content for the `generate-command` field unless you understand
|
||||
how the command is used to build the references.
|
||||
You should not need to update `reference.yml`. At times, changes in the
|
||||
upstream source code, may require changes to the configuration file
|
||||
(for example: golang version dependencies and third-party library changes).
|
||||
If you encounter build issues, contact the SIG-Docs team on the
|
||||
[#sig-docs Kubernetes Slack channel](https://kubernetes.slack.com).
|
||||
-->
|
||||
|
||||
## 定制 reference.yml
|
||||
|
||||
打开 `<web-base>/update-imported-docs/reference.yml` 文件进行编辑。
|
||||
在不了解参考文档构造命令的情况下，不要更改 `generate-command` 字段的内容。
|
||||
你一般不需要更新 `reference.yml` 文件。不过也有时候上游的源代码发生变化，
|
||||
导致需要对配置文件进行更改（例如：Golang 版本依赖或者第三方库发生变化）。
|
||||
如果你遇到类似问题，请在 [Kubernetes Slack 的 #sig-docs 频道](https://kubernetes.slack.com)
|
||||
联系 SIG-Docs 团队。
|
||||
|
||||
<!--
|
||||
{{< note >}}
|
||||
The `generate-command` is an optional entry, which can be used to run a
|
||||
given command or a short script to generate the docs from within a repository.
|
||||
{{< /note >}}
|
||||
|
||||
In `reference.yml`, `files` contains a list of `src` and `dst` fields.
|
||||
The `src` field contains the location of a generated Markdown file in the cloned
|
||||
`kubernetes-sigs/reference-docs` build directory, and the `dst` field specifies
|
||||
where to copy this file in the cloned `kubernetes/website` repository.
|
||||
For example:
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
注意，`generate-command` 是一个可选项，用来运行指定命令或者短脚本以在仓库
|
||||
内生成文档。
|
||||
{{< /note >}}
|
||||
|
||||
在 `reference.yml` 文件中，`files` 属性包含了一组 `src` 和 `dst` 字段。
|
||||
`src` 字段给出在所克隆的 `kubernetes-sigs/reference-docs` 构造目录中生成的
|
||||
Markdown 文件的位置，而 `dst` 字段则给出了对应文件要复制到的、所克隆的
|
||||
`kubernetes/website` 仓库中的位置。例如：
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: reference-docs
|
||||
remote: https://github.com/kubernetes-sigs/reference-docs.git
|
||||
files:
|
||||
- src: gen-compdocs/build/kube-apiserver.md
|
||||
dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||||
...
|
||||
```
|
||||
|
||||
<!--
|
||||
Note that when there are many files to be copied from the same source directory
|
||||
to the same destination directory, you can use wildcards in the value given to
|
||||
`src`. You must provide the directory name as the value for `dst`.
|
||||
For example:
|
||||
-->
|
||||
注意，如果从同一源目录中有很多文件要复制到目标目录，你可以在为 `src` 所设置的
|
||||
值中使用通配符。这时，为 `dst` 所设置的值必须是目录名称。例如：
|
||||
|
||||
```yaml
|
||||
files:
|
||||
- src: gen-compdocs/build/kubeadm*.md
|
||||
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
|
||||
```
|
||||
|
||||
<!--
|
||||
## Running the update-imported-docs tool
|
||||
|
||||
You can run the `update-imported-docs.py` tool as follows:
|
||||
-->
|
||||
## 运行 update-imported-docs 工具
|
||||
|
||||
你可以用如下方式运行 `update-imported-docs.py` 工具：
|
||||
|
||||
```shell
|
||||
cd <web-base>/update-imported-docs
|
||||
./update-imported-docs.py <configuration-file.yml> <release-version>
|
||||
```
|
||||
|
||||
<!-- For example: -->
|
||||
例如：
|
||||
|
||||
```shell
|
||||
./update-imported-docs.py reference.yml 1.17
|
||||
```
|
||||
|
||||
<!-- Revisit: is the release configuration used -->
|
||||
<!-- ## Fixing Links
|
||||
|
||||
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/main/update-imported-docs/release.yml).
|
||||
-->
|
||||
## 修复链接
|
||||
|
||||
配置文件 `release.yml` 中包含用来修复相对链接的指令。
|
||||
若要修复导入文件中的相对链接，将 `gen-absolute-links` 属性设置为 `true`。
|
||||
你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/main/update-imported-docs/release.yml)
|
||||
文件中找到示例。
|
||||
|
||||
<!--
|
||||
## Adding and committing changes in kubernetes/website
|
||||
|
||||
List the files that were generated and copied to `<web-base>`:
|
||||
-->
|
||||
## 添加并提交 kubernetes/website 中的变更
|
||||
|
||||
枚举新生成并复制到 `<web-base>` 的文件：
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output shows the new and modified files. The generated output varies
|
||||
depending upon changes made to the upstream source code.
|
||||
|
||||
### Generated component tool files
|
||||
-->
|
||||
输出显示新生成和已修改的文件。取决于上游源代码的修改多少，
|
||||
所生成的输出也会不同。
|
||||
|
||||
### 生成的 Kubernetes 组件文档
|
||||
|
||||
```
|
||||
content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
|
||||
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
|
||||
content/en/docs/reference/kubectl/kubectl.md
|
||||
```
|
||||
|
||||
<!-- ### Generated kubectl command reference files -->
|
||||
### 生成的 kubectl 命令参考文件
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/kubectl-commands.html
|
||||
static/docs/reference/generated/kubectl/navData.js
|
||||
static/docs/reference/generated/kubectl/scroll.js
|
||||
static/docs/reference/generated/kubectl/stylesheet.css
|
||||
static/docs/reference/generated/kubectl/tabvisibility.js
|
||||
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
|
||||
static/docs/reference/generated/kubectl/css/font-awesome.min.css
|
||||
```
|
||||
|
||||
<!-- ### Generated Kubernetes API reference directories and files -->
|
||||
### 生成的 Kubernetes API 参考目录与文件
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/query.scrollTo.min.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2
|
||||
```
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
|
||||
## Creating a pull request
|
||||
|
||||
Create a pull request to the `kubernetes/website` repository. Monitor your
|
||||
pull request, and respond to review comments as needed. Continue to monitor
|
||||
your pull request until it is merged.
|
||||
|
||||
A few minutes after your pull request is merged, your updated reference
|
||||
topics will be visible in the
|
||||
[published documentation](/docs/home/).
|
||||
-->
|
||||
运行 `git add` 和 `git commit` 提交文件。
|
||||
|
||||
## 创建拉取请求 {#creating-a-pull-request}
|
||||
|
||||
接下来创建一个对 `kubernetes/website` 仓库的拉取请求（PR）。
|
||||
监视所创建的 PR，并根据需要对评阅意见给出反馈。
|
||||
继续监视该 PR 直到其被合并为止。
|
||||
|
||||
当你的 PR 被合并几分钟之后，你所做的对参考文档的变更就会出现
|
||||
[发布的文档](/zh/docs/home/)上。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
To generate the individual reference documentation by manually setting up the required build repositories and
|
||||
running the build targets, see the following guides:
|
||||
|
||||
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
-->
|
||||
要手动设置所需的构造仓库，执行构建目标，以生成各个参考文档，可参考下面的指南：
|
||||
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 kubectl 命令生成参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [为 Kubernetes API 生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
|
||||
@@ -0,0 +1,774 @@
|
||||
---
|
||||
title: 本地化 Kubernetes 文档
|
||||
content_type: concept
|
||||
weight: 50
|
||||
card:
|
||||
name: contribute
|
||||
weight: 50
|
||||
title: 翻译文档
|
||||
---
|
||||
<!--
|
||||
title: Localizing Kubernetes Documentation
|
||||
content_type: concept
|
||||
approvers:
|
||||
- remyleone
|
||||
- rlenferink
|
||||
- zacharysarah
|
||||
weight: 50
|
||||
card:
|
||||
name: contribute
|
||||
weight: 50
|
||||
title: Translating the docs
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows you how to [localize](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/) the docs for a different language.
|
||||
-->
|
||||
此页面描述如何为其他语言的文档提供
|
||||
[本地化](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/)版本。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Contribute to an existing localization
|
||||
|
||||
You can help add or improve content to an existing localization. In [Kubernetes Slack](https://slack.k8s.io/) you'll find a channel for each localization. There is also a general [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations) where you can say hello.
|
||||
-->
|
||||
## 为现有的本地化做出贡献 {#contribute-to-an-existing-localization}
|
||||
|
||||
你可以帮助添加或改进现有本地化的内容。在 [Kubernetes Slack](https://slack.k8s.io/) 中，
|
||||
你能找到每个本地化的频道。还有一个通用的
|
||||
[SIG Docs Localizations Slack 频道](https://kubernetes.slack.com/messages/sig-docs-localizations)，
|
||||
你可以在这里打个招呼。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
If you want to work on a localization that already exists, check
|
||||
this page in that localization (if it exists), rather than the
|
||||
English original. You might see extra details there.
|
||||
-->
|
||||
如果你想处理已经存在的本地化，请在该本地化（如果存在）中检查此页面，而不是英文原版。
|
||||
你可能会在那里看到额外的详细信息。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Find your two-letter language code
|
||||
|
||||
First, consult the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php) to find your localization's two-letter language code. For example, the two-letter code for Korean is `ko`.
|
||||
|
||||
### Fork and clone the repo
|
||||
|
||||
First, [create your own fork](/docs/contribute/new-content/open-a-pr/#fork-the-repo) of the [kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
|
||||
The website content directory includes sub-directories for each language. The localization you want to help out with is inside `content/<two-letter-code>`.
|
||||
-->
|
||||
### 找到两个字母的语言代码 {#find-your-two-letter-language-code}
|
||||
|
||||
首先，有关本地化的两个字母的语言代码，请参考
|
||||
[ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)。
|
||||
例如，韩国的两个字母代码是 `ko`。
|
||||
|
||||
### 派生（fork）并且克隆仓库 {#fork-and-clone-the-repo}
|
||||
|
||||
首先，为 [kubernetes/website](https://github.com/kubernetes/website) 仓库
|
||||
[创建你自己的副本](/zh/docs/contribute/new-content/open-a-pr/#fork-the-repo)。
|
||||
|
||||
<!--
|
||||
Then, clone your fork and `cd` into it:
|
||||
-->
|
||||
然后，克隆你的 website 仓库副本并通过 `cd` 命令进入 website 目录：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/<username>/website
|
||||
cd website
|
||||
```
|
||||
|
||||
<!--
|
||||
The website content directory includes sub-directories for each language. The localization you want to help out with is inside `content/<two-letter-code>`.
|
||||
-->
|
||||
网站内容目录包括每种语言的子目录。你想要助力的本地化位于 `content/<two-letter-code>` 中。
|
||||
|
||||
<!--
|
||||
### Suggest changes
|
||||
|
||||
Create or update your chosen localized page based on the English original. See
|
||||
[translating content](#translating-content) for more details.
|
||||
|
||||
If you notice a technical inaccuracy or other problem with the upstream (English)
|
||||
documentation, you should fix the upstream documentation first and then repeat the
|
||||
equivalent fix by updating the localization you're working on.
|
||||
|
||||
Please limit pull requests to a single localization, since pull requests that change
|
||||
content in multiple localizations could be difficult to review.
|
||||
|
||||
Follow [Suggesting Content Improvements](/docs/contribute/suggest-improvements/) to propose changes to
|
||||
that localization. The process is very similar to proposing changes to the upstream (English) content.
|
||||
-->
|
||||
### 建议更改 {#suggest-changes}
|
||||
|
||||
根据英文原件创建或更新你选择的本地化页面。
|
||||
有关更多详细信息，请参阅[翻译内容](#translating-content)。
|
||||
|
||||
如果你发现上游（英文）文档存在技术错误或其他问题，
|
||||
你应该先修复上游文档，然后通过更新你正在处理的本地化来重复等效的修复。
|
||||
|
||||
请将拉取请求限制为单个本地化，因为在多个本地化中更改内容的拉取请求可能难以审查。
|
||||
|
||||
按照[内容改进建议](/zh/docs/contribute/suggest-improvements/)提出对该本地化的更改。
|
||||
该过程与提议更改上游（英文）内容非常相似。
|
||||
|
||||
<!--
|
||||
## Start a new localization
|
||||
|
||||
If you want the Kubernetes documentation localized into a new language, here's what
|
||||
you need to do.
|
||||
|
||||
Because contributors can't approve their own pull requests, you need _at least two contributors_
|
||||
to begin a localization.
|
||||
|
||||
All localization teams must be self-sustaining. The Kubernetes website is happy to host your work, but
|
||||
it's up to you to translate it and keep existing localized content current.
|
||||
-->
|
||||
## 开始新的本地化 {#start-a-new-localization}
|
||||
|
||||
如果你希望将 Kubernetes 文档本地化为一种新语言，你需要执行以下操作。
|
||||
|
||||
因为贡献者不能批准他们自己的拉取请求，你需要 _至少两个贡献者_ 来开始本地化。
|
||||
|
||||
所有本地化团队都必须能够自我维持。
|
||||
Kubernetes 网站很乐意托管你的作品，但要由你来翻译它并使现有的本地化内容保持最新。
|
||||
|
||||
<!--
|
||||
You'll need to know the two-letter language code for your language. Consult the
|
||||
[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php) to find your
|
||||
localization's two-letter language code. For example, the two-letter code for Korean is
|
||||
`ko`.
|
||||
|
||||
When you start a new localization, you must localize all the
|
||||
[minimum required content](#minimum-required-content) before
|
||||
the Kubernetes project can publish your changes to the live
|
||||
website.
|
||||
|
||||
SIG Docs can help you work on a separate branch so that you
|
||||
can incrementally work towards that goal.
|
||||
-->
|
||||
你需要知道你的语言的两个字母的语言代码。
|
||||
请查阅 [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)
|
||||
以查找你的本地化的两字母语言代码。例如，韩语的两字母代码是`ko`。
|
||||
|
||||
当你开始新的本地化时，你必须先本地化所有[最少要求的内容](#minimum-required-content)，
|
||||
Kubernetes 项目才能将你的更改发布到当前网站。
|
||||
|
||||
SIG Docs 可以帮助你在单独的分支上工作，以便你可以逐步实现该目标。
|
||||
|
||||
<!--
|
||||
### Find community
|
||||
|
||||
Let Kubernetes SIG Docs know you're interested in creating a localization! Join the [SIG Docs Slack channel](https://kubernetes.slack.com/messages/sig-docs) and the [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations). Other localization teams are happy to help you get started and answer any questions you have.
|
||||
-->
|
||||
### 找到社区 {#find-community}
|
||||
|
||||
让 Kubernetes SIG Docs 知道你有兴趣创建本地化！
|
||||
加入 [SIG Docs Slack 频道](https://kubernetes.slack.com/messages/sig-docs)
|
||||
和 [SIG Docs Localizations Slack 频道](https://kubernetes.slack.com/messages/sig-docs-localizations)。
|
||||
其他本地化团队很乐意帮助你入门并回答你的任何问题。
|
||||
|
||||
<!--
|
||||
Please also consider participating in the [SIG Docs Localization Subgroup meeting](https://github.com/kubernetes/community/tree/master/sig-docs). The mission of the SIG Docs localization subgroup is to work across the SIG Docs localization teams to collaborate on defining and documenting the processes for creating localized contribution guides. In addition, the SIG Docs localization subgroup will look for opportunities for the creation and sharing of common tools across localization teams and also serve to identify new requirements to the SIG Docs Leadership team. If you have questions about this meeting, please inquire on the [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations).
|
||||
|
||||
You can also create a Slack channel for your localization in the `kubernetes/community` repository. For an example of adding a Slack channel, see the PR for [adding a channel for Persian](https://github.com/kubernetes/community/pull/4980).
|
||||
-->
|
||||
也请考虑参加
|
||||
[SIG Docs 本地化小组的会议](https://github.com/kubernetes/community/tree/master/sig-docs)。
|
||||
SIG Docs 本地化小组的任务是与 SIG Docs 本地化团队合作，
|
||||
共同定义和记录创建本地化贡献指南的流程。
|
||||
此外，SIG Docs 本地化小组将寻找机会在本地化团队中创建和共享通用工具，
|
||||
并为 SIG Docs 领导团队确定新要求。如果你对本次会议有任何疑问，
|
||||
请在 [SIG Docs Localizations Slack 频道](https://kubernetes.slack.com/messages/sig-docs-localizations)
|
||||
中提问。
|
||||
|
||||
你还可以在 `kubernetes/community` 仓库中为你的本地化创建一个 Slack 频道。
|
||||
有关添加 Slack 频道的示例，请参阅
|
||||
[为波斯语添加频道](https://github.com/kubernetes/community/pull/4980)的 PR。
|
||||
|
||||
<!--
|
||||
### Join the Kubernetes GitHub organization
|
||||
|
||||
Once you've opened a localization PR, you can become members of the Kubernetes GitHub organization. Each person on the team needs to create their own [Organization Membership Request](https://github.com/kubernetes/org/issues/new/choose) in the `kubernetes/org` repository.
|
||||
-->
|
||||
### 加入到 Kubernetes GitHub 组织 {#join-the-kubernetes-github-organization}
|
||||
|
||||
提交本地化 PR 后，你可以成为 Kubernetes GitHub 组织的成员。
|
||||
团队中的每个人都需要在 `kubernetes/org` 仓库中创建自己的
|
||||
[组织成员申请](https://github.com/kubernetes/org/issues/new/choose)。
|
||||
|
||||
<!--
|
||||
### Add your localization team in GitHub
|
||||
|
||||
Next, add your Kubernetes localization team to [`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/main/config/kubernetes/sig-docs/teams.yaml). For an example of adding a localization team, see the PR to add the [Spanish localization team](https://github.com/kubernetes/org/pull/685).
|
||||
|
||||
Members of `@kubernetes/sig-docs-**-owners` can approve PRs that change content within (and only within) your localization directory: `/content/**/`.
|
||||
|
||||
For each localization, The `@kubernetes/sig-docs-**-reviews` team automates review assignment for new PRs.
|
||||
-->
|
||||
### 在 GitHub 中添加你的本地化团队 {#add-your-localization-team-in-github}
|
||||
|
||||
接下来，将你的 Kubernetes 本地化团队添加到
|
||||
[`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/main/config/kubernetes/sig-docs/teams.yaml)。
|
||||
有关添加本地化团队的示例，请参见添加[西班牙本地化团队](https://github.com/kubernetes/org/pull/685) 的 PR。
|
||||
|
||||
`@kubernetes/sig-docs-**-owners` 成员可以批准更改对应本地化目录 `/content/**/` 中内容的 PR，并仅限这类 PR。
|
||||
|
||||
对于每个本地化，`@kubernetes/sig-docs-**-reviews` 团队被自动分派新 PR 的审阅任务。
|
||||
|
||||
<!--
|
||||
Members of `@kubernetes/website-maintainers` can create new localization branches to coordinate translation efforts.
|
||||
|
||||
Members of `@kubernetes/website-milestone-maintainers` can use the `/milestone` [Prow command](https://prow.k8s.io/command-help) to assign a milestone to issues or PRs.
|
||||
-->
|
||||
`@kubernetes/website-maintainers` 成员可以创建新的本地化分支来协调翻译工作。
|
||||
|
||||
`@kubernetes/website-milestone-maintainers` 成员可以使用 `/milestone`
|
||||
[Prow 命令](https://prow.k8s.io/command-help)为 issues 或 PR 设定里程碑。
|
||||
|
||||
<!--
|
||||
### Configure the workflow
|
||||
|
||||
Next, add a GitHub label for your localization in the `kubernetes/test-infra` repository. A label lets you filter issues and pull requests for your specific language.
|
||||
|
||||
For an example of adding a label, see the PR for adding the [Italian language label](https://github.com/kubernetes/test-infra/pull/11316).
|
||||
-->
|
||||
### 配置工作流程 {#configure-the-workflow}
|
||||
|
||||
接下来，在 `kubernetes/test-infra` 仓库中为你的本地化添加一个 GitHub 标签。
|
||||
标签可让你过滤 issues 和针对特定语言的 PR。
|
||||
|
||||
有关添加标签的示例，请参见添加[意大利语标签](https://github.com/kubernetes/test-infra/pull/11316)的 PR。
|
||||
|
||||
你还可以在 `kubernetes/community` 仓库中为你的本地化创建一个 Slack 频道。
|
||||
有关添加 Slack 频道的示例，请参见[为印尼语和葡萄牙语添加频道](https://github.com/kubernetes/community/pull/3605)的 PR。
|
||||
|
||||
<!--
|
||||
### Modify the site configuration
|
||||
|
||||
The Kubernetes website uses Hugo as its web framework. The website's Hugo configuration resides in the [`config.toml`](https://github.com/kubernetes/website/tree/main/config.toml) file. To support a new localization, you'll need to modify `config.toml`.
|
||||
|
||||
Add a configuration block for the new language to `config.toml`, under the existing `[languages]` block. The German block, for example, looks like:
|
||||
-->
|
||||
### 修改站点配置 {#configure-the-workflow}
|
||||
|
||||
Kubernetes 网站使用 Hugo 作为其 Web 框架。网站的 Hugo 配置位于
|
||||
[`config.toml`](https://github.com/kubernetes/website/tree/main/config.toml)文件中。
|
||||
为了支持新的本地化，你需要修改 `config.toml`。
|
||||
|
||||
在现有的 `[languages]` 下，将新语言的配置添加到 `config.toml` 中。
|
||||
例如，下面是德语的配置示例：
|
||||
|
||||
```toml
|
||||
[languages.de]
|
||||
title = "Kubernetes"
|
||||
description = "Produktionsreife Container-Verwaltung"
|
||||
languageName = "Deutsch (German)"
|
||||
languageNameLatinScript = "German"
|
||||
contentDir = "content/de"
|
||||
weight = 8
|
||||
```
|
||||
|
||||
<!--
|
||||
The value for `languageName` will be listed in language selection bar. Assign "language name in native script (language name in latin script)" to `languageName`, for example, `languageName = "한국어 (Korean)"`. `languageNameLatinScript` can be used to access the language name in latin script and use it in the theme. Assign "language name in latin script" to `languageNameLatinScript`, for example, `languageNameLatinScript ="Korean"`.
|
||||
-->
|
||||
`languageName` 的值将列在语言选择栏中。
|
||||
将 `languageName` 赋值为“本地脚本中的语言名称（拉丁脚本中的语言名称）”。
|
||||
例如，`languageName = "한국어 (Korean)"`。
|
||||
`languageNameLatinScript` 可用于访问拉丁脚本中的语言名称并在主题中使用。
|
||||
将 `languageNameLatinScript` 赋值为“拉丁脚本中的语言名称”。
|
||||
例如，`languageNameLatinScript ="Korean"`。
|
||||
|
||||
<!--
|
||||
When assigning a `weight` parameter for your block, find the language block with the highest weight and add 1 to that value.
|
||||
|
||||
For more information about Hugo's multilingual support, see "[Multilingual Mode](https://gohugo.io/content-management/multilingual/)".
|
||||
-->
|
||||
为你的语言块分配一个 `weight` 参数时，找到权重最高的语言块并将其加 1。
|
||||
|
||||
有关 Hugo 多语言支持的更多信息，请参阅"[多语言模式](https://gohugo.io/content-management/multilingual/)"。
|
||||
|
||||
<!--
|
||||
### Add a new localization directory
|
||||
|
||||
Add a language-specific subdirectory to the [`content`](https://github.com/kubernetes/website/tree/main/content) folder in the repository. For example, the two-letter code for German is `de`:
|
||||
-->
|
||||
### 添加一个新的本地化目录 {#add-a-new-localization-directory}
|
||||
|
||||
将特定语言的子目录添加到仓库中的
|
||||
[`content`](https://github.com/kubernetes/website/tree/main/content) 文件夹下。
|
||||
例如，德语的两个字母的代码是 `de`：
|
||||
|
||||
```shell
|
||||
mkdir content/de
|
||||
```
|
||||
|
||||
<!--
|
||||
You also need to create a directory inside `data/i18n` for
|
||||
[localized strings](#site-strings-in-i18n); look at existing localizations
|
||||
for an example. To use these new strings, you must also create a symbolic link
|
||||
from `i18n/<localization>.toml` to the actual string configuration in
|
||||
`data/i18n/<localization>/<localization>.toml` (remember to commit the symbolic
|
||||
link).
|
||||
|
||||
For example, for German the strings live in `data/i18n/de/de.toml`, and
|
||||
`i18n/de.toml` is a symbolic link to `data/i18n/de/de.toml`.
|
||||
-->
|
||||
你还需要在 `data/i18n` 中为 [localized strings](#site-strings-in-i18n) 创建一个目录；
|
||||
以现有的本地化为例。要使用这些新字符串，
|
||||
你还必须创建从 `i18n/<localization>.toml`
|
||||
到 `data/i18n/<localization>/<localization>.toml`
|
||||
中实际字符串配置的符号链接（记得提交符号链接关联）。
|
||||
|
||||
例如，对于德语，字符串位于 `data/i18n/de/de.toml` 中，
|
||||
而 `i18n/de.toml` 是指向 `data/i18n/de/de.toml` 的符号链接。
|
||||
|
||||
<!--
|
||||
### Localize the community code of conduct
|
||||
|
||||
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.
|
||||
|
||||
-->
|
||||
### 本地化社区行为准则 {#localize-the-community-code-of-conduct}
|
||||
|
||||
在 [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages)
|
||||
仓库提交 PR，添加你所用语言版本的行为准则。
|
||||
|
||||
-->
|
||||
<!--
|
||||
### Setting up the OWNERS files
|
||||
|
||||
To set the roles of each user contributing to the localization, create an `OWNERS` file inside the language-specific subdirectory with:
|
||||
|
||||
- **reviewers**: A list of kubernetes teams with reviewer roles, in this case, the `sig-docs-**-reviews` team created in [Add your localization team in GitHub](#add-your-localization-team-in-github).
|
||||
- **approvers**: A list of kubernetes teams with approvers roles, in this case, the `sig-docs-**-owners` team created in [Add your localization team in GitHub](#add-your-localization-team-in-github).
|
||||
- **labels**: A list of GitHub labels to automatically apply to a PR, in this case, the language label created in [Configure the workflow](#configure-the-workflow).
|
||||
-->
|
||||
### 设置 OWNERS 文件 {#setting-up-the-owners-files}
|
||||
|
||||
要设置每个对本地化做出贡献用户的角色，请在特定于语言的子目录内创建一个 `OWNERS` 文件，其中：
|
||||
|
||||
- **reviewers**: 具有评审人角色的 kubernetes 团队的列表，在本例中为在
|
||||
[在 GitHub 中添加你的本地化团队](#add-your-localization-team-in-github)
|
||||
中创建的 `sig-docs-**-reviews` 团队。
|
||||
- **approvers**: 具有批准人角色的 kubernetes 团队的列表，在本例中为在
|
||||
[在 GitHub 中添加你的本地化团队](#add-your-localization-team-in-github)
|
||||
中创建的 `sig-docs-**-owners` 团队。
|
||||
- **labels**: 可以自动应用于 PR 的 GitHub 标签列表，在本例中为
|
||||
[配置工作流程](#configure-the-workflow)中创建的语言标签。
|
||||
|
||||
<!--
|
||||
More information about the `OWNERS` file can be found at [go.k8s.io/owners](https://go.k8s.io/owners).
|
||||
|
||||
The [Spanish OWNERS file](https://git.k8s.io/website/content/es/OWNERS), with language code `es`, looks like:
|
||||
-->
|
||||
有关 `OWNERS` 文件的更多信息，请访问[go.k8s.io/owners](https://go.k8s.io/owners)。
|
||||
|
||||
语言代码为 `es` 的[西班牙语 OWNERS 文件](https://git.k8s.io/website/content/es/OWNERS)看起来像：
|
||||
|
||||
|
||||
```yaml
|
||||
# See the OWNERS docs at https://go.k8s.io/owners
|
||||
|
||||
# This is the localization project for Spanish.
|
||||
# Teams and members are visible at https://github.com/orgs/kubernetes/teams.
|
||||
|
||||
reviewers:
|
||||
- sig-docs-es-reviews
|
||||
|
||||
approvers:
|
||||
- sig-docs-es-owners
|
||||
|
||||
labels:
|
||||
- language/es
|
||||
```
|
||||
|
||||
<!--
|
||||
After adding the language-specific `OWNERS` file, update the [root `OWNERS_ALIASES`](https://git.k8s.io/website/OWNERS_ALIASES) file with the new Kubernetes teams for the localization, `sig-docs-**-owners` and `sig-docs-**-reviews`.
|
||||
|
||||
For each team, add the list of GitHub users requested in [Add your localization team in GitHub](#add-your-localization-team-in-github), in alphabetical order.
|
||||
-->
|
||||
添加了特定语言的 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 用户列表。
|
||||
|
||||
```diff
|
||||
--- a/OWNERS_ALIASES
|
||||
+++ b/OWNERS_ALIASES
|
||||
@@ -48,6 +48,14 @@ aliases:
|
||||
- stewart-yu
|
||||
- xiangpengzhao
|
||||
- zhangxiaoyu-zidif
|
||||
+ sig-docs-es-owners: # Admins for Spanish content
|
||||
+ - alexbrand
|
||||
+ - raelga
|
||||
+ sig-docs-es-reviews: # PR reviews for Spanish content
|
||||
+ - alexbrand
|
||||
+ - electrocucaracha
|
||||
+ - glo-pena
|
||||
+ - raelga
|
||||
sig-docs-fr-owners: # Admins for French content
|
||||
- perriea
|
||||
- remyleone
|
||||
```
|
||||
|
||||
<!--
|
||||
### Open a pull request
|
||||
|
||||
Next, [open a pull request](/docs/contribute/new-content/open-a-pr/#open-a-pr) (PR) to add a localization to the `kubernetes/website` repository.
|
||||
|
||||
The PR must include all of the [minimum required content](#minimum-required-content) before it can be approved.
|
||||
|
||||
For an example of adding a new localization, see the PR to enable [docs in French](https://github.com/kubernetes/website/pull/12548).
|
||||
-->
|
||||
### 打开拉取请求 {#open-a-pull-request}
|
||||
|
||||
接下来，[打开拉取请求](/zh/docs/contribute/new-content/open-a-pr/#open-a-pr)（PR）
|
||||
将本地化添加到 `kubernetes/website` 存储库。
|
||||
|
||||
PR 必须包含所有[最低要求内容](#minimum-required-content)才能获得批准。
|
||||
|
||||
有关添加新本地化的示例，
|
||||
请参阅 PR 以启用[法语文档](https://github.com/kubernetes/website/pull/12548)。
|
||||
|
||||
<!--
|
||||
### Add a localized README file
|
||||
|
||||
To guide other localization contributors, add a new [`README-**.md`](https://help.github.com/articles/about-readmes/) to the top level of [k/website](https://github.com/kubernetes/website/), where `**` is the two-letter language code. For example, a German README file would be `README-de.md`.
|
||||
|
||||
Provide guidance to localization contributors in the localized `README-**.md` file. Include the same information contained in `README.md` as well as:
|
||||
|
||||
- A point of contact for the localization project
|
||||
- Any information specific to the localization
|
||||
-->
|
||||
### 添加本地化的 README 文件 {#add-a-localized-readme-file}
|
||||
|
||||
为了指导其他本地化贡献者，请在 [k/website](https://github.com/kubernetes/website/)
|
||||
的根目录添加一个新的 [`README-**.md`](https://help.github.com/articles/about-readmes/)，
|
||||
其中 `**` 是两个字母的语言代码。例如，德语 README 文件为 `README-de.md`。
|
||||
|
||||
在本地化的 `README-**.md` 文件中为本地化贡献者提供指导。包含 `README.md` 中包含的相同信息，以及：
|
||||
|
||||
- 本地化项目的联系人
|
||||
- 任何特定于本地化的信息
|
||||
|
||||
<!--
|
||||
After you create the localized README, add a link to the file from the main English `README.md`, and include contact information in English. You can provide a GitHub ID, email address, [Slack channel](https://slack.com/), or other method of contact. You must also provide a link to your localized Community Code of Conduct.
|
||||
-->
|
||||
创建本地化的 README 文件后，请在英语版文件 `README.md` 中添加指向该文件的链接，
|
||||
并给出英文形式的联系信息。你可以提供 GitHub ID、电子邮件地址、
|
||||
[Slack 频道](https://slack.com/)或其他联系方式。你还必须提供指向本地化的社区行为准则的链接。
|
||||
|
||||
<!--
|
||||
### Launching your new localization
|
||||
|
||||
Once a localization meets requirements for workflow and minimum output, SIG Docs will:
|
||||
|
||||
- Enable language selection on the website
|
||||
- Publicize the localization's availability through [Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF) channels, including the [Kubernetes blog](https://kubernetes.io/blog/).
|
||||
-->
|
||||
### 启动你的新本地化 {#add-a-localized-readme-file}
|
||||
|
||||
一旦本地化满足工作流程和最小输出的要求，SIG Docs 将：
|
||||
|
||||
- 在网站上启用语言选择
|
||||
- 通过[云原生计算基金会](https://www.cncf.io/about/)（CNCF）渠道，
|
||||
包括 [Kubernetes 博客](https://kubernetes.io/blog/)，来宣传本地化的可用性。
|
||||
|
||||
<!--
|
||||
## Translating content
|
||||
|
||||
Localizing *all* of the Kubernetes documentation is an enormous task. It's okay to start small and expand over time.
|
||||
-->
|
||||
## 翻译文档 {#translating-content}
|
||||
|
||||
本地化*所有* Kubernetes 文档是一项艰巨的任务。从小做起，循序渐进。
|
||||
|
||||
<!--
|
||||
### Minimum required content
|
||||
|
||||
At a minimum, all localizations must include:
|
||||
-->
|
||||
### 最低要求内容 {#minimum-required-content}
|
||||
|
||||
所有本地化至少必须包括：
|
||||
|
||||
<!--
|
||||
Description | URLs
|
||||
-----|-----
|
||||
Home | [All heading and subheading URLs](/docs/home/)
|
||||
Setup | [All heading and subheading URLs](/docs/setup/)
|
||||
Tutorials | [Kubernetes Basics](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/hello-minikube/)
|
||||
Site strings | [All site strings](#Site-strings-in-i18n) in a new localized TOML file
|
||||
Releases | [All heading and subheading URLs](/releases)
|
||||
-->
|
||||
描述 | 网址
|
||||
-----|-----
|
||||
主页 | [所有标题和副标题网址](/zh/docs/home/)
|
||||
安装 | [所有标题和副标题网址](/zh/docs/setup/)
|
||||
教程 | [Kubernetes 基础](/zh/docs/tutorials/kubernetes-basics/), [Hello Minikube](/zh/docs/tutorials/hello-minikube/)
|
||||
网站字符串 | [所有网站字符串](#Site-strings-in-i18n)
|
||||
发行版本 | [所有标题和副标题 URL](/releases)
|
||||
|
||||
<!--
|
||||
Translated documents must reside in their own `content/**/` subdirectory, but otherwise follow the same URL path as the English source. For example, to prepare the [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) tutorial for translation into German, create a subfolder under the `content/de/` folder and copy the English source:
|
||||
-->
|
||||
翻译后的文档必须保存在自己的 `content/**/` 子目录中，否则将遵循与英文源相同的 URL 路径。
|
||||
例如，要准备将 [Kubernetes 基础](/zh/docs/tutorials/kubernetes-basics/) 教程翻译为德语，
|
||||
请在 `content/de/` 文件夹下创建一个子文件夹并复制英文源：
|
||||
|
||||
```shell
|
||||
mkdir -p content/de/docs/tutorials
|
||||
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md
|
||||
```
|
||||
|
||||
<!--
|
||||
Translation tools can speed up the translation process. For example, some editors offers plugins to quickly translate text.
|
||||
-->
|
||||
翻译工具可以加快翻译过程。例如，某些编辑器提供了用于快速翻译文本的插件。
|
||||
|
||||
<!--
|
||||
Machine-generated translation is insufficient on its own. Localization requires extensive human review to meet minimum standards of quality.
|
||||
-->
|
||||
{{< caution >}}
|
||||
机器生成的翻译本身是不够的，本地化需要广泛的人工审核才能满足最低质量标准。
|
||||
{{< /caution >}}
|
||||
|
||||
<!--
|
||||
To ensure accuracy in grammar and meaning, members of your localization team should carefully review all machine-generated translations before publishing.
|
||||
-->
|
||||
为了确保语法和含义的准确性，本地化团队的成员应在发布之前仔细检查所有由机器生成的翻译。
|
||||
|
||||
<!--
|
||||
### Source files
|
||||
|
||||
Localizations must be based on the English files from a specific release targeted by the localization team.
|
||||
Each localization team can decide which release to target which is referred to as the _target version_ below.
|
||||
|
||||
To find source files for your target version:
|
||||
|
||||
1. Navigate to the Kubernetes website repository at https://github.com/kubernetes/website.
|
||||
2. Select a branch for your target version from the following table:
|
||||
Target version | Branch
|
||||
-----|-----
|
||||
Latest version | [`main`](https://github.com/kubernetes/website/tree/main)
|
||||
Previous version | [`release-{{< skew prevMinorVersion >}}`](https://github.com/kubernetes/website/tree/release-{{< skew prevMinorVersion >}})
|
||||
Next version | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})
|
||||
|
||||
The `main` branch holds content for the current release `{{< latest-version >}}`. The release team will create a `{{< release-branch >}}` branch before the next release: v{{< skew nextMinorVersion >}}.
|
||||
-->
|
||||
### 源文件 {#source-files}
|
||||
|
||||
本地化必须基于本地化团队所针对的特定发行版本中的英文文件。
|
||||
每个本地化团队可以决定要针对哪个发行版本，在下文中称作目标版本（target version）。）
|
||||
|
||||
要查找你的目标版本的源文件：
|
||||
|
||||
1. 导航到 Kubernetes website 仓库，网址为 https://github.com/kubernetes/website。
|
||||
2. 从下面的表格中选择你的目标版本分支：
|
||||
|
||||
目标版本 | 分支
|
||||
-----|-----
|
||||
最新版本 | [`main`](https://github.com/kubernetes/website/tree/main)
|
||||
上一个版本 | [`release-{{< skew prevMinorVersion >}}`](https://github.com/kubernetes/website/tree/release-{{< skew prevMinorVersion >}})
|
||||
下一个版本 | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})
|
||||
|
||||
`main` 分支中保存的是当前发行版本 `{{< latest-version >}}` 的内容。
|
||||
发行团队会在下一个发行版本 v{{< skew nextMinorVersion >}} 出现之前创建
|
||||
`{{< release-branch >}}` 分支。
|
||||
|
||||
<!--
|
||||
### Site strings in i18n
|
||||
|
||||
Localizations must include the contents of [`data/i18n/en/en.toml`](https://github.com/kubernetes/website/blob/main/data/i18n/en/en.toml) in a new language-specific file. Using German as an example: `data/i18n/de/de.toml`.
|
||||
|
||||
Add a new localization directory and file to `data/i18n/`. For example, with German (`de`):
|
||||
-->
|
||||
### i18n/ 中的网站字符串 {#site-strings-in-i18n}
|
||||
|
||||
本地化必须在新的语言特定文件中包含
|
||||
[`data/i18n/en/en.toml`](https://github.com/kubernetes/website/blob/main/data/i18n/en/en.toml)
|
||||
的内容。以德语为例：`data/i18n/de/de.toml`。
|
||||
|
||||
将新的本地化文件和目录添加到 `data/i18n/`。例如德语 (`de`)：
|
||||
|
||||
```bash
|
||||
mkdir -p data/i18n/de
|
||||
cp data/i18n/en/en.toml data/i18n/de/de.toml
|
||||
```
|
||||
|
||||
<!--
|
||||
Revise the comments at the top of the file to suit your localization,
|
||||
then translate the value of each string. For example, this is the German-language
|
||||
placeholder text for the search form:
|
||||
-->
|
||||
修改文件顶部的注释以适合你的本地化，
|
||||
然后翻译每个字符串的值。例如，这是搜索表单的德语占位符文本：
|
||||
|
||||
```toml
|
||||
[ui_search_placeholder]
|
||||
other = "Suchen"
|
||||
```
|
||||
|
||||
<!--
|
||||
Localizing site strings lets you customize site-wide text and features: for example, the legal copyright text in the footer on each page.
|
||||
-->
|
||||
本地化网站字符串允许你自定义网站范围的文本和特性：例如，每个页面页脚中的合法版权文本。
|
||||
|
||||
<!--
|
||||
### Language specific style guide and glossary
|
||||
|
||||
Some language teams have their own language-specific style guide and glossary. For example, see the [Korean Localization Guide](/ko/docs/contribute/localization_ko/).
|
||||
-->
|
||||
### 特定语言的样式指南和词汇表 {#language-specific-style-guide-and-glossary}
|
||||
|
||||
一些语言团队有自己的特定语言样式指南和词汇表。
|
||||
例如，请参见[中文本地化指南](/zh/docs/contribute/localization_zh/)。
|
||||
|
||||
<!--
|
||||
### Language specific Zoom meetings
|
||||
|
||||
If the localization project needs a separate meeting time, contact a SIG Docs Co-Chair or Tech Lead to create a new reoccurring Zoom meeting and calendar invite. This is only needed when the the team is large enough to sustain and require a separate meeting.
|
||||
|
||||
Per CNCF policy, the localization teams must upload their meetings to the SIG Docs YouTube playlist. A SIG Docs Co-Chair or Tech Lead can help with the process until SIG Docs automates it.
|
||||
|
||||
-->
|
||||
|
||||
### 特定语言的 Zoom 会议 {#language-specific-zoom-meetings}
|
||||
|
||||
如果本地化项目需要单独的会议时间，
|
||||
请联系 SIG Docs 联合主席或技术主管以创建新的重复 Zoom 会议和日历邀请。
|
||||
仅当团队维持在足够大的规模并需要单独的会议时才需要这样做。
|
||||
|
||||
根据 CNCF 政策，本地化团队必须将他们的会议上传到 SIG Docs YouTube 播放列表。
|
||||
SIG Docs 联合主席或技术主管可以帮助完成该过程，直到 SIG Docs 实现自动化。
|
||||
|
||||
<!--
|
||||
## Branching strategy
|
||||
|
||||
Because localization projects are highly collaborative efforts, we
|
||||
encourage teams to work in shared localization branches - especially
|
||||
when starting out and the localization is not yet live.
|
||||
|
||||
To collaborate on a localization branch:
|
||||
-->
|
||||
### 分支策略 {#branching-strategy}
|
||||
|
||||
因为本地化项目是高度协同的工作，所以我们鼓励团队基于共享的本地化分支工作。
|
||||
- 特别是在开始并且本地化尚未生效时。
|
||||
|
||||
在本地化分支上协作需要：
|
||||
|
||||
<!--
|
||||
1. A team member of [@kubernetes/website-maintainers](https://github.com/orgs/kubernetes/teams/website-maintainers) opens a localization branch from a source branch on https://github.com/kubernetes/website.
|
||||
|
||||
Your team approvers joined the `@kubernetes/website-maintainers` team when you [added your localization team](#add-your-localization-team-in-github) to the [`kubernetes/org`](https://github.com/kubernetes/org) repository.
|
||||
|
||||
We recommend the following branch naming scheme:
|
||||
|
||||
`dev-<source version>-<language code>.<team milestone>`
|
||||
|
||||
For example, an approver on a German localization team opens the localization branch `dev-1.12-de.1` directly against the k/website repository, based on the source branch for Kubernetes v1.12.
|
||||
-->
|
||||
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-<source version>-<language code>.<team milestone>`
|
||||
|
||||
例如，一个德语本地化团队的批准人基于 Kubernetes v1.12 版本的源分支，
|
||||
直接新建了 k/website 仓库的本地化分支 `dev-1.12-de.1`。
|
||||
|
||||
<!--
|
||||
2. Individual contributors open feature branches based on the localization branch.
|
||||
|
||||
For example, a German contributor opens a pull request with changes to `kubernetes:dev-1.12-de.1` from `username:local-branch-name`.
|
||||
|
||||
3. Approvers review and merge feature branches into the localization branch.
|
||||
|
||||
4. Periodically, an approver merges the localization branch to its source branch by opening and approving a new pull request. Be sure to squash the commits before approving the pull request.
|
||||
-->
|
||||
2. 个人贡献者基于本地化分支创建新的特性分支
|
||||
|
||||
例如，一个德语贡献者新建了一个拉取请求，并将 `username:local-branch-name` 更改为 `kubernetes:dev-1.12-de.1`。
|
||||
|
||||
3. 批准人审查功能分支并将其合并到本地化分支中。
|
||||
|
||||
4. 批准人会定期发起并批准新的 PR，将本地化分支合并到其源分支。
|
||||
在批准 PR 之前，请确保先 squash commits。
|
||||
|
||||
<!--
|
||||
Repeat steps 1-4 as needed until the localization is complete. For example, subsequent German localization branches would be: `dev-1.12-de.2`, `dev-1.12-de.3`, etc.
|
||||
-->
|
||||
根据需要重复步骤 1-4，直到完成本地化工作。例如，随后的德语本地化分支将是：
|
||||
`dev-1.12-de.2`、`dev-1.12-de.3`，等等。
|
||||
|
||||
<!--
|
||||
Teams must merge localized content into the same branch from which the content was sourced.
|
||||
|
||||
For example:
|
||||
|
||||
- a localization branch sourced from `main` must be merged into `main`.
|
||||
- a localization branch sourced from `release-{{% skew "prevMinorVersion" %}}` must be merged into `release-{{% skew "prevMinorVersion" %}}`.
|
||||
|
||||
{{< note >}}
|
||||
If your localization branch was created from `main` branch but it is not merged into `main` before new release branch `{{< release-branch >}}` created, merge it into both `main` and new release branch `{{< release-branch >}}`. To merge your localization branch into new release branch `{{< release-branch >}}`, you need to switch upstream branch of your localization branch to `{{< release-branch >}}`.
|
||||
{{< /note >}}
|
||||
-->
|
||||
团队必须将本地化内容合入到发布分支中，该发布分支是内容的来源。
|
||||
|
||||
例如：
|
||||
|
||||
- 源于 `main` 分支的本地化分支必须被合并到 `main`。
|
||||
- 源于 `release-{{ skew "prevMinorVersion" }}`
|
||||
的本地化分支必须被合并到 `release-{{ skew "prevMinorVersion" }}`。
|
||||
|
||||
如果你的本地化分支是基于 `main` 分支创建的，但最终没有在新的发行
|
||||
分支 `{{< release-branch >}}` 被创建之前合并到 `main` 中，需要将其
|
||||
同时将其合并到 `main` 和新的发行分支 `{{< release-branch >}}` 中。
|
||||
要将本地化分支合并到新的发行分支 `{{< release-branch >}}` 中，你需要
|
||||
将你本地化分支的上游分支切换到 `{{< release-branch >}}`。
|
||||
|
||||
<!--
|
||||
At the beginning of every team milestone, it's helpful to open an issue comparing upstream changes between the previous localization branch and the current localization branch. There are two scripts for comparing upstream changes. [`upstream_changes.py`](https://github.com/kubernetes/website/tree/main/scripts#upstream_changespy) is useful for checking the changes made to a specific file. And [`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/main/scripts#diff_l10n_branchespy) is useful for creating a list of outdated files for a specific localization branch.
|
||||
|
||||
While only approvers can open a new localization branch and merge pull requests, anyone can open a pull request for a new localization branch. No special permissions are required.
|
||||
-->
|
||||
在团队每个里程碑的开始时段，创建一个 issue 来比较先前的本地化分支
|
||||
和当前的本地化分支之间的上游变化很有帮助。
|
||||
现在有两个脚本用来比较上游的变化。
|
||||
[`upstream_changes.py`](https://github.com/kubernetes/website/tree/main/scripts#upstream_changespy)
|
||||
对于检查对某个文件的变更很有用。
|
||||
[`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/main/scripts#diff_l10n_branchespy)
|
||||
可以用来为某个特定本地化分支创建过时文件的列表。
|
||||
|
||||
虽然只有批准人才能创建新的本地化分支并合并 PR，任何人都可以
|
||||
为新的本地化分支提交一个拉取请求（PR）。不需要特殊权限。
|
||||
|
||||
<!--
|
||||
For more information about working from forks or directly from the repository, see ["fork and clone the repo"](#fork-and-clone-the-repo).
|
||||
-->
|
||||
有关基于派生或直接从仓库开展工作的更多信息，请参见 ["派生和克隆"](#fork-and-clone-the-repo)。
|
||||
|
||||
<!--
|
||||
## Upstream contributions
|
||||
|
||||
SIG Docs welcomes upstream contributions and corrections to the English source.
|
||||
-->
|
||||
### 上游贡献 {#upstream-contributions}
|
||||
|
||||
Sig Docs 欢迎对英文原文的上游贡献和修正。
|
||||
@@ -0,0 +1,485 @@
|
||||
---
|
||||
title: 中文本地化样式指南
|
||||
content_type: concept
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
本节详述文档中文本地化过程中须注意的事项。
|
||||
这里列举的内容包含了**中文本地化小组**早期给出的指导性建议和后续实践过程中积累的经验。
|
||||
在阅读、贡献、评阅中文本地化文档的过程中，如果对本文的指南有任何改进建议，
|
||||
都请直接提出 PR。我们欢迎任何形式的补充和更正！
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## 一般规定
|
||||
|
||||
本节列举一些译文中常见问题和约定。
|
||||
|
||||
### 英文原文的保留
|
||||
|
||||
为便于译文审查和变更追踪，所有中文本地化 Markdown 文件中都应使用 HTML 注释
|
||||
`<!--` 和 `-->` 将英文原文逐段注释起来，后跟对应中文译文。例如：
|
||||
|
||||
```
|
||||
<!--
|
||||
This is English text ...
|
||||
-->
|
||||
中文译文对应 ...
|
||||
```
|
||||
|
||||
不建议采用下面的方式注释英文段落，除非英文段落非常非常短：
|
||||
|
||||
```
|
||||
<!-- This is English text ... -->
|
||||
中文译文对应 ...
|
||||
|
||||
```
|
||||
|
||||
无论英文原文或者中文译文中，都不要保留过多的、不必要的空白行。
|
||||
|
||||
#### 段落划分
|
||||
|
||||
请避免大段大段地注释和翻译。一般而言，每段翻译可对应两三个自然段。
|
||||
段落过长会导致译文很难评阅。但也不必每个段落都单独翻译。例如：
|
||||
|
||||
```
|
||||
<!--
|
||||
## Overview
|
||||
|
||||
### Concept
|
||||
|
||||
First paragraph, not very long.
|
||||
-->
|
||||
## 概述 {#overview}
|
||||
|
||||
### 概念 {#concept}
|
||||
|
||||
第一段落，不太长。
|
||||
```
|
||||
|
||||
以下风格是不必要的：
|
||||
|
||||
```
|
||||
<!--
|
||||
## Overview
|
||||
-->
|
||||
## 概述 {#overview}
|
||||
|
||||
<!--
|
||||
### Concept
|
||||
-->
|
||||
### 概念 {#concept}
|
||||
|
||||
<!--
|
||||
First paragraph, not very long.
|
||||
-->
|
||||
第一段落，不太长。
|
||||
```
|
||||
|
||||
#### 编号列表的处理
|
||||
|
||||
编号列表需要编号的连续性，处理不好的话可能导致输出结果错误。
|
||||
由于有些列表可能很长，一次性等将整个列表注释掉再翻译也不现实。
|
||||
推荐采用下面的方式。
|
||||
|
||||
假定英文为：
|
||||
|
||||
```
|
||||
1. Prepare something
|
||||
1. Followed by a long step with code snippets and notes ...
|
||||
this is a really long item
|
||||
1. Another long item ...
|
||||
.. continues here
|
||||
1. Almost done ...
|
||||
```
|
||||
|
||||
本地化处理：
|
||||
|
||||
```
|
||||
<!--
|
||||
1. Prepare something
|
||||
-->
|
||||
1. 准备工作，...
|
||||
这里每行缩进 3 个空格
|
||||
|
||||
<!--
|
||||
1. Followed by a long step with code snippets and notes ...
|
||||
this is a really long item
|
||||
-->
|
||||
2. 这里是第二个编号，但需要显式给出数字，不能沿用英文编号。
|
||||
缩进内容同上，3 个空格。
|
||||
即使有三个反引号的代码段或者短代码，都按 3 个空格缩进。
|
||||
|
||||
<!--
|
||||
1. Another long item ...
|
||||
.. continues here
|
||||
1. Almost done ...
|
||||
-->
|
||||
3. 继续列表。
|
||||
|
||||
如果条目有多个段落，也要
|
||||
保持缩进对齐以确保排版正确。
|
||||
|
||||
4. 列表终于结束
|
||||
```
|
||||
|
||||
#### Frontmatter 的处理
|
||||
|
||||
页面中的 Frontmatter 指的是文件头的两个 `---` 中间的部分。
|
||||
对这一部分，解析器有特殊处理，因此不能将英文部分放在前面，中文跟在后面。
|
||||
需要将二者顺序颠倒。如下所示：
|
||||
|
||||
```
|
||||
---
|
||||
title: 译文标题
|
||||
type: concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
<!--
|
||||
title: English title
|
||||
type: concept
|
||||
reviewers:
|
||||
- john
|
||||
- doe
|
||||
weight: 30
|
||||
-->
|
||||
```
|
||||
|
||||
这里要注意的是：
|
||||
|
||||
- `title`、`description` 的内容要翻译，其他字段一般不必（甚至不可）翻译。
|
||||
- `reviewers` 部分要删除，不然中文译文会转给英文作者来审阅。
|
||||
|
||||
|
||||
#### 短代码（shortcode）处理
|
||||
|
||||
通过 HTML 注释的短代码仍会被运行，因此需要额外小心。建议处理方式：
|
||||
|
||||
```
|
||||
<!--
|
||||
English text
|
||||
-->
|
||||
{{</* note */>}}
|
||||
中文译文
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
评阅人应该不难理解中英文段落的对应关系。但是如果采用下面的方式，
|
||||
则会出现两个 `note`，因此需要避免。这是因为被注释起来的短代码仍会起作用！
|
||||
|
||||
```
|
||||
<!--
|
||||
{{</* note */>}}
|
||||
English text
|
||||
{{</* /note */>}}
|
||||
-->
|
||||
{{</* note */>}}
|
||||
中文译文
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
### 译与不译
|
||||
|
||||
#### 资源名称或字段不译
|
||||
|
||||
根据英文原文写作风格约定【也在持续修订改进】，对 Kubernetes 中的 API
|
||||
资源均按其规范中所给的大小写形式书写，例如：英文中会使用 Deployment 而不是
|
||||
deployment 来表示名为 "Deployment" 的 API 资源类型和对象实例。
|
||||
|
||||
对这类词语，一般不应翻译。
|
||||
|
||||
{{< note >}}
|
||||
英文原文在这方面并不严谨，译者或中文译文的评阅者要非常留心。
|
||||
比如 Secret 资源，很多时候被误写为 secret。
|
||||
这时在本地化版本中一定不能译为“秘密”，以免与原文的语义不符。
|
||||
{{< /note >}}
|
||||
|
||||
#### 代码中的注释
|
||||
|
||||
一般而言，代码中的注释需要翻译，包括存放在 `content/zh/examples/`
|
||||
目录下的清单文件中的注释。
|
||||
|
||||
|
||||
#### 出站链接
|
||||
|
||||
如果超级链接的目标是 Kubernetes 网站之外的纯英文网页，链接中的内容*可以*不翻译。
|
||||
例如：
|
||||
|
||||
```
|
||||
<!--
|
||||
Please check [installation caveats](https://acme.com/docs/v1/caveats) ...
|
||||
-->
|
||||
请参阅 [installation caveats](https://acme.com/docs/v1/caveats) ...
|
||||
```
|
||||
|
||||
注意，这里的 `installation` 与 `参阅` 之间留白，因为解析后属于中英文混排的情况。
|
||||
|
||||
### 标点符号
|
||||
|
||||
译文中标点符号要使用全角字符，除非以下两种情况：
|
||||
|
||||
- 标点符号是英文命令的一部分；
|
||||
- 标点符号是 Markdown 语法的一部分。
|
||||
|
||||
英文排比句式中采用的逗号，在译文中要使用顿号代替，以便符合中文书写习惯。
|
||||
|
||||
## 更新译文
|
||||
|
||||
由于整个文档站点会随着 Kubernetes 项目的开发进展而演化，英文版本的网站内容会不断更新。
|
||||
鉴于中文站点的基本翻译工作在 1.19 版本已完成，
|
||||
从 1.20 版本开始本地化的工作会集中在追踪英文内容变化上。
|
||||
|
||||
为确保准确跟踪中文化版本与英文版本之间的差异，中文内容的 PR 所包含的每个页面都必须是“最新的”。
|
||||
这里的“最新”指的是对应的英文页面中的更改已全部同步到中文页面。
|
||||
如果某中文 PR 中包含对 `content/zh/docs/foo/bar.md` 的更改，且文件 `bar.md`
|
||||
的上次更改日期是 `2020-10-01 01:02:03 UTC`，对应 GIT 标签 `abcd1234`，
|
||||
则 `bar.md` 应包含自 `abcd1234` 以来 `content/en/docs/foo/bar.md` 的所有变更，
|
||||
否则视此 PR 为不完整 PR，会破坏我们对上游变更的跟踪。
|
||||
|
||||
这一要求适用于所有更改，包括拼写错误、格式更正、链接修订等等。要查看文件
|
||||
`bar.md` 上次提交以来发生的所有变更，可使用：
|
||||
|
||||
```
|
||||
./scripts/lsync.sh content/zh/docs/foo/bar.md
|
||||
```
|
||||
|
||||
## 关于链接
|
||||
|
||||
### 链接锚点
|
||||
|
||||
英文 Markdown 中的各级标题会自动生成锚点，以便从其他页面中链接。
|
||||
在译为中文后，相应的链接必然会失效。为防止这类问题，
|
||||
建议在翻译各级标题时，使用英文方式显式给出链接锚点。例如：
|
||||
|
||||
```
|
||||
<!--
|
||||
### Create a Pod
|
||||
-->
|
||||
### 创建 Pod {#create-a-pod}
|
||||
```
|
||||
|
||||
此类问题对于概念部分的页面最为突出，需要格外注意。
|
||||
|
||||
|
||||
### 中文链接目标
|
||||
|
||||
由于大部分页面已经完成中文本地化，这意味着很多链接可以使用中文版本作为目标。
|
||||
例如：
|
||||
|
||||
```
|
||||
<!--
|
||||
For more information, please check [volumes](/docs/concepts/storage/)
|
||||
...
|
||||
-->
|
||||
更多的信息可参考[卷](/zh/docs/concepts/storage/)页面。
|
||||
```
|
||||
|
||||
如果对应目标页面尚未本地化，建议登记一个 Issue。
|
||||
|
||||
{{< note >}}
|
||||
Website 的仓库中 `scripts/linkchecker.py` 是一个工具，可用来检查页面中的链接。
|
||||
例如，下面的命令检查中文本地化目录 `/content/zh/docs/concepts/containers/`
|
||||
中所有 Markdown 文件中的链接合法性：
|
||||
|
||||
```
|
||||
./scripts/linkchecker.py -l zh -f /docs/concepts/containers/**/*.md
|
||||
```
|
||||
{{< /note >}}
|
||||
|
||||
## 排版格式
|
||||
|
||||
以下为译文 Markdown 排版格式要求：
|
||||
|
||||
- 中英文之间留一个空格
|
||||
* 这里的“英文”包括以英文呈现的超级链接
|
||||
* 这里的中文、英文都不包括标点符号
|
||||
- 译文 Markdown 中不要使用长行，应适当断行。
|
||||
* 可根据需要在 80-120 列断行
|
||||
* 最好结合句子的边界断行，即一句话在一行，不必留几个字转到下一行
|
||||
* 不要在两个中文字符中间断行，因为这样会造成中文字符中间显示一个多余空格，
|
||||
如果句子太长，可以从中文与非中文符号之间断行
|
||||
* 超级链接文字一般较长，可独立成行
|
||||
|
||||
{{< warning >}}
|
||||
我们注意到有些贡献者可能使用了某种自动化工具，在 Markdown 英文原文中自动添加空格。
|
||||
虽然这些工具可一定程度提高效率，仍然需要提请作者注意，某些工具所作的转换可能是不对的，
|
||||
例如将 `foo=bar` 转换为 `foo = bar`、将 `），另一些文字` 转换为 `） ，另一些文字` 等等，
|
||||
甚至将超级链接中的半角井号（`#`）转换为全角，导致链接失效。
|
||||
{{< /warning >}}
|
||||
|
||||
英文中 "you" 翻译成 "你" 不必是 "您"。
|
||||
文章内的链接用英文，例如 (#deploying)，在对应的标题上后面加上 {#deploying}
|
||||
|
||||
|
||||
## 术语
|
||||
|
||||
### 术语拼写
|
||||
|
||||
按中文译文习惯，尽量不要在中文译文中使用首字母小写的拼写。例如：
|
||||
|
||||
```
|
||||
列举所有 pods，查看其创建时间 ... [No]
|
||||
列举所有 Pod，查看其创建时间 ... [Yes]
|
||||
```
|
||||
|
||||
**第一次**使用首字母缩写时，应标注其全称和中文译文。例如：
|
||||
|
||||
```
|
||||
你可以创建一个 Pod 干扰预算（Pod Disruption Budget，PDB）来解决这一问题。
|
||||
所谓 PDB 实际上是 ...
|
||||
```
|
||||
|
||||
对于某些特定于 Kubernetes 语境的术语，也应在**第一次**出现在页面中时给出其英文原文，
|
||||
以便读者对照阅读。例如：
|
||||
|
||||
```
|
||||
镜像策略（Image Policy）用来控制集群可拉取的镜像仓库（Image Registry）源。
|
||||
```
|
||||
|
||||
### 术语对照
|
||||
|
||||
本节列举常见术语的统一译法。除极个别情况，对于专业术语应使用本节所列举的译法：
|
||||
|
||||
- API Server，API 服务器
|
||||
- GA (general availability)，正式发布
|
||||
- addons，插件
|
||||
- admission controller，准入控制器
|
||||
- affinity，亲和性
|
||||
- annotation，注解
|
||||
- anti-affinity，反亲和性
|
||||
- attach，挂接
|
||||
- autoscale，自动扩缩容
|
||||
- bearer token，持有者令牌
|
||||
- capabilities
|
||||
* 当泛指某主体执行某操作的能力时，可直译为“能力”
|
||||
* 当特指 Linux 操作系统上的[权限控制](http://man7.org/linux/man-pages/man7/capabilities.7.html)机制时，译为“权能字”
|
||||
- certificate authority，证书机构
|
||||
- certificate，证书
|
||||
- claim，申领
|
||||
- cloud provider
|
||||
* 当用来指代下层云服务的提供厂商时，译为“云服务供应商”
|
||||
* 当特指 Kubernetes 中对不同云平台的支持时，可酌情译为“云驱动”
|
||||
- cluster，集群
|
||||
- condition
|
||||
* 大多数上下文中，可译为“条件”
|
||||
* 在讨论 Kubernetes 资源的 condition 时，应译为“状况”
|
||||
- control loop，控制回路
|
||||
- control plane，控制平面，或控制面
|
||||
- controller，控制器
|
||||
- controller manager，控制器管理器
|
||||
- credential，登录凭据，凭据
|
||||
- custom，定制，或自定义
|
||||
- daemon，守护进程
|
||||
- dashboard，仪表板
|
||||
- dependent，附属或附属者
|
||||
- deprecated，已弃用的
|
||||
- deprecation，弃用
|
||||
- desired，预期的
|
||||
- desired state，预期状态
|
||||
- detach，解除挂接
|
||||
- distribution，发行版本
|
||||
- disruption，干扰（请勿译为“中断”）
|
||||
- drain，腾空
|
||||
- endpoint，端点
|
||||
- egress，出站
|
||||
- evict，驱逐
|
||||
- eviction，驱逐
|
||||
- feature gate，特性门控
|
||||
- federation，联邦
|
||||
- flags，命令行参数，参数
|
||||
- grace period，宽限期限
|
||||
- graceful termination，体面终止
|
||||
- hairpin，发夹
|
||||
- hash，哈希
|
||||
- headless service，无头服务
|
||||
- healthcheck，健康检查
|
||||
- hook，回调
|
||||
- host，主机，宿主机
|
||||
- hosting，托管
|
||||
- idempotent，幂等的
|
||||
- image，镜像
|
||||
- image registry，镜像仓库
|
||||
- ingress，入站
|
||||
- init container，Init 容器
|
||||
- key
|
||||
* 在加密解密、安全认证上下文中，译为密钥
|
||||
* 在配置文件、数据结构上下文中，译为主键，或键
|
||||
- label，标签
|
||||
- label selector，标签选择算符
|
||||
- lifecycle，生命周期
|
||||
- limit，限制，限值
|
||||
- liveness probe，存活态探针
|
||||
- load balance，负载均衡
|
||||
- load balancer，负载均衡器
|
||||
- log flush，清刷日志数据
|
||||
- loopback，本地回路
|
||||
- manifest，清单，清单文件
|
||||
- master node，主控节点
|
||||
- metric
|
||||
* 用来指代被测量的数据源时，译为指标
|
||||
* 用来指代测量观测结果时，译为度量值
|
||||
- mount，挂载
|
||||
- namespace，名字空间，命名空间
|
||||
- orphans，孤立或孤立的
|
||||
- override，覆写
|
||||
- owner，所有者，属主
|
||||
- pending，悬决的
|
||||
- persistent volume，持久卷
|
||||
- persistent volume claim，持久卷申领
|
||||
- pipeline，流水线
|
||||
- prerequisites，依赖，前提条件（根据上下文判断）
|
||||
- priority class，优先级类
|
||||
- probe，探针
|
||||
- provision，供应
|
||||
- pull，拉取
|
||||
- push，推送
|
||||
- quota，配额
|
||||
- readiness probe，就绪态探针
|
||||
- replica，副本
|
||||
- repo，仓库
|
||||
- repository，仓库
|
||||
- revision，修订版本
|
||||
- role，角色
|
||||
- role binding，角色绑定
|
||||
- rolling update，滚动更新
|
||||
- rollout，上线
|
||||
- rotate，轮换
|
||||
- round robin，轮转
|
||||
- runtime，运行时
|
||||
- scale in/out，横向缩容/扩容
|
||||
- scale up/down，纵向扩容/缩容
|
||||
- scale
|
||||
* 做动词用时，译为“扩缩”，或者“改变...的规模”
|
||||
* 做名词用时，译为“规模”
|
||||
- scheduler，调度器
|
||||
- service，服务
|
||||
- service account，服务账号
|
||||
- service account token，服务账号令牌
|
||||
- service discovery，服务发现
|
||||
- service mesh，服务网格
|
||||
- session，会话
|
||||
- sidecar，边车
|
||||
- skew，偏移
|
||||
- spec，规约
|
||||
- specification，规约
|
||||
- startup probe，启动探针
|
||||
- stateless，无状态的
|
||||
- static pod，静态 Pod
|
||||
- stderr，标准错误输出
|
||||
- stdin，标准输入
|
||||
- stdout，标准输出
|
||||
- storage class，存储类
|
||||
- taint，污点
|
||||
- threshold，阈值
|
||||
- toleration，容忍度
|
||||
- topology，拓扑
|
||||
- topology spread constraint，拓扑分布约束
|
||||
- traffic，流量
|
||||
* 在某些上下文中，可以根据情况译为“服务请求”，“服务响应”
|
||||
- unmount，卸载
|
||||
- use case，用例，使用场景
|
||||
- volume，卷
|
||||
- worker node，工作节点
|
||||
- workload，工作负载
|
||||
@@ -0,0 +1,200 @@
|
||||
---
|
||||
title: 贡献新内容
|
||||
content_type: 概念
|
||||
main_menu: true
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: Contributing new content
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This section contains information you should know before contributing new
|
||||
content.
|
||||
-->
|
||||
|
||||
本节包含你在贡献新内容之前需要知晓的信息。
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< 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 编写文档<br>并用 Hugo 构建网站] --- E[GitHub 源代码]
|
||||
E --- G['/content/../docs' 文件夹包含<br>多语言文档]
|
||||
G --- H[评审 Hugo 页面内容<br>类型和短代码]
|
||||
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
|
||||
{{</ mermaid >}}
|
||||
|
||||
<!--
|
||||
***Figure - Contributing new content preparation***
|
||||
|
||||
The figure above depicts the information you should know
|
||||
prior to submitting new content. The information details follow.
|
||||
-->
|
||||
|
||||
***插图 - 贡献新内容准备工作***
|
||||
|
||||
上图描述了你在提交新内容之前需要知晓的信息。
|
||||
详细信息见下文。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Contributing basics
|
||||
|
||||
- Write Kubernetes documentation in Markdown and build the Kubernetes site
|
||||
using [Hugo](https://gohugo.io/).
|
||||
- Kubernetes documentation uses [CommonMark](https://commonmark.org/) as its flavor of Markdown.
|
||||
- The source is in [GitHub](https://github.com/kubernetes/website). You can find
|
||||
Kubernetes documentation at `/content/en/docs/`. Some of the reference
|
||||
documentation is automatically generated from scripts in
|
||||
the `update-imported-docs/` directory.
|
||||
- [Page content types](/docs/contribute/style/page-content-types/) describe the
|
||||
presentation of documentation content in Hugo.
|
||||
-->
|
||||
|
||||
## 基本知识
|
||||
|
||||
- 使用 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 描述文档内容的呈现。
|
||||
|
||||
<!--
|
||||
- You can use [Docsy shortcodes](https://www.docsy.dev/docs/adding-content/shortcodes/) or [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) to contribute to Kubernetes documentation.
|
||||
- In addition to the standard Hugo shortcodes, we use a number of
|
||||
[custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) in our
|
||||
documentation to control the presentation of content.
|
||||
- Documentation source is available in multiple languages in `/content/`. Each
|
||||
language has its own folder with a two-letter code determined by the
|
||||
[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php)
|
||||
. For example, English documentation source is stored in `/content/en/docs/`.
|
||||
- For more information about contributing to documentation in multiple languages
|
||||
or starting a new translation,
|
||||
see [localization](/docs/contribute/localization).
|
||||
-->
|
||||
|
||||
- 你可以使用 [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 {#before-you-begin}
|
||||
### Sign the CNCF CLA {#sign-the-cla}
|
||||
All Kubernetes contributors **must** read
|
||||
the [Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md)
|
||||
and [sign the Contributor License Agreement (CLA)](https://github.com/kubernetes/community/blob/master/CLA.md).
|
||||
Pull requests from contributors who haven't signed the CLA fail the automated
|
||||
tests. The name and email you provide must match those found in
|
||||
your `git config`, and your git name and email must match those used for the
|
||||
CNCF CLA.
|
||||
-->
|
||||
|
||||
## 开始之前 {#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 的信息一致。
|
||||
|
||||
<!--
|
||||
### Choose which Git branch to use
|
||||
|
||||
When opening a pull request, you need to know in advance which branch to base
|
||||
your work on.
|
||||
|
||||
Scenario | Branch
|
||||
:---------|:------------
|
||||
Existing or new English language content for the current release | `main`
|
||||
Content for a feature change release | The branch which corresponds to the major and minor version the feature change is in, using the pattern `dev-<version>`. For example, if a feature changes in the `v{{< skew nextMinorVersion >}}` release, then add documentation changes to the ``dev-{{< skew nextMinorVersion >}}`` branch.
|
||||
Content in other languages (localizations) | Use the localization's convention. See the [Localization branching strategy](/docs/contribute/localization/#branching-strategy) for more information.
|
||||
|
||||
If you're still not sure which branch to choose, ask in `#sig-docs` on Slack.
|
||||
-->
|
||||
|
||||
### 选择要使用的 Git 分支
|
||||
|
||||
在发起 PR 时，你需要预先知道基于哪个分支来开展工作。
|
||||
|
||||
场景 | 分支
|
||||
:---------|:------------
|
||||
针对当前发行版本的，对现有英文内容的修改或新的英文内容 | `main`
|
||||
针对功能特性变更的内容 | 分支对应于功能特性变更的主要和次要版本，分支名称采用 `dev-<version>` 的模式。例如，如果某功能特性在 `v{{< skew nextMinorVersion >}}` 版本发生变化，则对应的文档变化要添加到 `dev-{{< skew nextMinorVersion >}}` 分支。
|
||||
其他语言的内容（本地化） | 基于本地化团队的约定。参见[本地化分支策略](/zh/docs/contribute/localization/#branching-strategy)了解更多信息。
|
||||
|
||||
如果你仍不能确定要选择哪个分支，请在 Slack 的 `#sig-docs` 频道上提出问题。
|
||||
|
||||
<!--
|
||||
{{< note >}} If you already submitted your pull request and you know that the
|
||||
base branch was wrong, you (and only you, the submitter) can change it. {{<
|
||||
/note >}}
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
如果你已经提交了 PR，并且发现所针对的分支选错了，你（且只有作为提交人的你）可以更改分支。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Languages per PR
|
||||
|
||||
Limit pull requests to one language per PR. If you need to make an identical
|
||||
change to the same code sample in multiple languages, open a separate PR for
|
||||
each language.
|
||||
-->
|
||||
|
||||
### 每个 PR 牵涉的语言
|
||||
|
||||
请确保每个 PR 仅涉及一种语言。
|
||||
如果你需要对多种语言下的同一代码示例进行相同的修改，也请为每种语言发起一个独立的 PR。
|
||||
|
||||
<!--
|
||||
## Tools for contributors
|
||||
|
||||
The [doc contributors tools](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools)
|
||||
directory in the `kubernetes/website` repository contains tools to help your
|
||||
contribution journey go more smoothly.
|
||||
-->
|
||||
|
||||
## 为贡献者提供的工具
|
||||
|
||||
`kubernetes/website` 仓库的[文档贡献者工具](https://github.com/kubernetes/website/tree/main/content/zh/docs/doc-contributor-tools)目录中包含了一些工具，
|
||||
有助于使你的贡献过程更为顺畅。
|
||||
@@ -0,0 +1,311 @@
|
||||
---
|
||||
title: 提交博客和案例分析
|
||||
linktitle: 博客和案例分析
|
||||
slug: blogs-case-studies
|
||||
content_type: concept
|
||||
weight: 30
|
||||
---
|
||||
<!--
|
||||
title: Submitting blog posts and case studies
|
||||
linktitle: Blogs and case studies
|
||||
slug: blogs-case-studies
|
||||
content_type: concept
|
||||
weight: 30
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
Anyone can write a blog post and submit it for review.
|
||||
Case studies require extensive review before they're approved.
|
||||
-->
|
||||
任何人都可以撰写博客并提交评阅。
|
||||
案例分析则在被批准之前需要更多的评阅。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## The Kubernetes Blog
|
||||
|
||||
The Kubernetes blog is used by the project to communicate new features, community reports, and any news that might be relevant to the Kubernetes community.
|
||||
This includes end users and developers.
|
||||
Most of the blog's content is about things happening in the core project, but we encourage you to submit about things happening elsewhere in the ecosystem too!
|
||||
|
||||
Anyone can write a blog post and submit it for review.
|
||||
-->
|
||||
## Kubernetes 博客
|
||||
|
||||
Kubernetes 博客用于项目发布新功能特性、
|
||||
社区报告以及其他一些可能对整个社区很重要的新闻。
|
||||
其读者包括最终用户和开发人员。
|
||||
大多数博客的内容是关于核心项目中正在发生的事情，
|
||||
不过我们也鼓励你提交一些有关生态系统中其他时事的博客。
|
||||
|
||||
任何人都可以撰写博客并提交评阅。
|
||||
|
||||
<!--
|
||||
### Submit a Post
|
||||
|
||||
Blog posts should not be commercial in nature and should consist of original content that applies broadly to the Kubernetes community.
|
||||
Appropriate blog content includes:
|
||||
|
||||
- New Kubernetes capabilities
|
||||
- Kubernetes projects updates
|
||||
- Updates from Special Interest Groups
|
||||
- Tutorials and walkthroughs
|
||||
- Thought leadership around Kubernetes
|
||||
- Kubernetes Partner OSS integration
|
||||
- **Original content only**
|
||||
-->
|
||||
### 提交博文
|
||||
|
||||
博文不应该是商业性质的，应该包含广泛适用于 Kubernetes 社区的原创内容。
|
||||
合适的博客内容包括：
|
||||
|
||||
- Kubernetes 新能力
|
||||
- Kubernetes 项目更新信息
|
||||
- 来自特别兴趣小组（Special Interest Groups, SIG）的更新信息
|
||||
- 教程和演练
|
||||
- 有关 Kubernetes 的纲领性理念
|
||||
- Kubernetes 合作伙伴 OSS 集成信息
|
||||
- **仅限原创内容**
|
||||
|
||||
<!--
|
||||
Unsuitable content includes:
|
||||
|
||||
- Vendor product pitches
|
||||
- Partner updates without an integration and customer story
|
||||
- Syndicated posts (language translations ok)
|
||||
-->
|
||||
|
||||
不合适的博客内容包括：
|
||||
|
||||
- 供应商产品推介
|
||||
- 不含集成信息和客户故事的合作伙伴更新信息
|
||||
- 已发表的博文（可刊登博文译稿）
|
||||
|
||||
<!--
|
||||
To submit a blog post, follow these steps:
|
||||
|
||||
1. [Sign the CLA](https://kubernetes.io/docs/contribute/start/#sign-the-cla) if you have not yet done so.
|
||||
1. Have a look at the Markdown format for existing blog posts in the [website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts).
|
||||
1. Write out your blog post in a text editor of your choice.
|
||||
1. On the same link from step 2, click the Create new file button. Paste your content into the editor. Name the file to match the proposed title of the blog post, but don’t put the date in the file name. The blog reviewers will work with you on the final file name and the date the blog will be published.
|
||||
1. When you save the file, GitHub will walk you through the pull request process.
|
||||
1. A blog post reviewer will review your submission and work with you on feedback and final details. When the blog post is approved, the blog will be scheduled for publication.
|
||||
-->
|
||||
要提交博文，你可以遵从以下步骤：
|
||||
|
||||
1. 如果你还未签署 CLA，请先[签署 CLA](https://kubernetes.io/docs/contribute/start/#sign-the-cla)。
|
||||
2. 查阅[网站仓库](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts)中现有博文的 Markdown 格式。
|
||||
3. 在你所选的文本编辑器中撰写你的博文。
|
||||
4. 在第 2 步的同一链接上，点击 **Create new file** 按钮。
|
||||
将你的内容粘贴到编辑器中。为文件命名，使其与提议的博文标题一致，
|
||||
但不要在文件名中写日期。
|
||||
博客评阅者将与你一起确定最终的文件名和发表博客的日期。
|
||||
5. 保存文件时，GitHub 将引导你完成 PR 流程。
|
||||
6. 博客评阅者将评阅你提交的内容，并与你一起处理反馈和最终细节。
|
||||
当博文被批准后，博客将排期发表。
|
||||
|
||||
<!--
|
||||
### Guidelines and expectations
|
||||
|
||||
- Blog posts should not be vendor pitches.
|
||||
- Articles must contain content that applies broadly to the Kubernetes community. For example, a submission should focus on upstream Kubernetes as opposed to vendor-specific configurations. Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for what is typically allowed on Kubernetes properties.
|
||||
- Links should primarily be to the official Kubernetes documentation. When using external references, links should be diverse - For example a submission shouldn't contain only links back to a single company's blog.
|
||||
- Sometimes this is a delicate balance. The [blog team](https://kubernetes.slack.com/messages/sig-docs-blog/) is there to give guidance on whether a post is appropriate for the Kubernetes blog, so don't hesitate to reach out.
|
||||
-->
|
||||
### 指导原则和期望 {#guidelines-and-expectations}
|
||||
|
||||
- 博客内容不可以是销售用语。
|
||||
- 文章内容必须是对整个 Kubernetes 社区中很多人都有参考意义。
|
||||
例如，所提交的文章应该关注上游的 Kubernetes 项目本身，而不是某个厂商特定的配置。
|
||||
请参阅[文档风格指南](/zh/docs/contribute/style/content-guide/#what-s-allowed)
|
||||
以了解哪些内容是 Kubernetes 所允许的。
|
||||
- 链接应该主要指向官方的 Kubernetes 文档。
|
||||
当引用外部信息时，链接应该是多样的。
|
||||
例如，所提交的博客文章中不可以只包含指向某个公司的博客的链接。
|
||||
- 有些时候，这是一个比较棘手的权衡过程。
|
||||
[博客团队](https://kubernetes.slack.com/messages/sig-docs-blog/)的存在目的即是为
|
||||
Kubernetes 博客提供文章是否合适的指导意见。
|
||||
所以，需要帮助的时候不要犹豫。
|
||||
<!--
|
||||
- Blog posts are not published on specific dates.
|
||||
- Articles are reviewed by community volunteers. We'll try our best to accommodate specific timing, but we make no guarantees.
|
||||
- Many core parts of the Kubernetes projects submit blog posts during release windows, delaying publication times. Consider submitting during a quieter period of the release cycle.
|
||||
- If you are looking for greater coordination on post release dates, coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post.
|
||||
- Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs, you can reach out to the blog team via [this slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/) to ask in real time.
|
||||
-->
|
||||
- 博客内容并非在某特定日期发表。
|
||||
- 文章会交由社区自愿者评阅。我们会尽力满足特定的时限要求，只是无法就此作出承诺。
|
||||
- Kubernetes 项目的很多核心组件会在发布窗口期内提交博客文章，导致发表时间被推迟。
|
||||
因此，请考虑在发布周期内较为平静的时间段提交博客文章。
|
||||
- 如果你希望就博文发表日期上进行较大范围的协调，请联系
|
||||
[CNCF 推广团队](https://www.cncf.io/about/contact/)。
|
||||
这也许是比提交博客文章更合适的一种选择。
|
||||
- 有时，博客的评审可能会堆积起来。如果你觉得你的文章没有引起该有的重视，
|
||||
你可以通过[此 Slack 频道](https://kubernetes.slack.com/messages/sig-docs-blog/)
|
||||
联系博客团队，以获得实时反馈。
|
||||
<!--
|
||||
- Blog posts should be relevant to Kubernetes users.
|
||||
- Topics related to participation in or results of Kubernetes SIGs activities are always on topic (see the work in the [Upstream Marketing Team](https://github.com/kubernetes/community/blob/master/communication/marketing-team/blog-guidelines.md#upstream-marketing-blog-guidelines) for support on these posts).
|
||||
- The components of Kubernetes are purposely modular, so tools that use existing integration points like CNI and CSI are on topic.
|
||||
- Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team before submitting a draft.
|
||||
- Many CNCF projects have their own blog. These are often a better choice for posts. There are times of major feature or milestone for a CNCF project that users would be interested in reading on the Kubernetes blog.
|
||||
- Blog posts about contributing to the Kubernetes project should be in the [Kubernetes Contributors site](https://kubernetes.dev)
|
||||
-->
|
||||
- 博客内容应该对 Kubernetes 用户有用。
|
||||
- 与参与 Kubernetes SIGs 活动相关，或者与这类活动的结果相关的主题通常是切题的。
|
||||
请参考[上游推广团队](https://github.com/kubernetes/community/blob/master/communication/marketing-team/blog-guidelines.md#upstream-marketing-blog-guidelines)的工作以获得对此类博文的支持。
|
||||
- Kubernetes 的组件都有意设计得模块化，因此使用类似 CNI、CSI 等集成点的工具
|
||||
通常都是切题的。
|
||||
- 关于其他 CNCF 项目的博客可能切题也可能不切题。
|
||||
我们建议你在提交草稿之前与博客团队联系。
|
||||
- 很多 CNCF 项目有自己的博客。这些博客通常是更好的选择。
|
||||
有些时候，某个 CNCF 项目的主要功能特性或者里程碑的变化可能是用户有兴趣在
|
||||
Kubernetes 博客上阅读的内容。
|
||||
- 关于为 Kubernetes 项目做贡献的博客内容应该放在 [Kubernetes 贡献者站点](https://kubernetes.dev)上。
|
||||
<!--
|
||||
- Blog posts should be original content
|
||||
- The official blog is not for repurposing existing content from a third party as new content.
|
||||
- The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows commercial use of the content for commercial purposes, just not the other way around.
|
||||
- Blog posts should aim to be future proof
|
||||
- Given the development velocity of the project, we want evergreen content that won't require updates to stay accurate for the reader.
|
||||
- It can be a better choice to add a tutorial or update official documentation than to write a high level overview as a blog post.
|
||||
- Consider concentrating the long technical content as a call to action of the blog post, and focus on the problem space or why readers should care.
|
||||
-->
|
||||
- 博客文章应该是原创内容。
|
||||
- 官方博客的目的不是将某第三方已发表的内容重新作为新内容发表。
|
||||
- 博客的[授权协议](https://github.com/kubernetes/website/blob/main/LICENSE)
|
||||
的确允许出于商业目的来使用博客内容；但并不是所有可以商用的内容都适合在这里发表。
|
||||
- 博客文章的内容应该在一段时间内不过期。
|
||||
- 考虑到项目的开发速度，我们希望读者看到的是不必更新就能保持长期准确的内容。
|
||||
- 有时候，在官方文档中添加一个教程或者进行内容更新都是比博客更好的选择。
|
||||
- 可以考虑在博客文章中将较长技术内容的重点放在鼓励读者自行尝试上，或者
|
||||
放在问题域本身或者为什么读者应该关注某个话题上。
|
||||
|
||||
<!--
|
||||
### Technical Considerations for submitting a blog post
|
||||
|
||||
Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use this technology stack.
|
||||
|
||||
We recognize that this requirement makes the process more difficult for less-familiar folks to submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to lower the barrier, please volunteer to help out.
|
||||
-->
|
||||
### 提交博客的技术考虑
|
||||
|
||||
所提交的内容应该是 Markdown 格式的，以便能够被 [Hugo](https://gohugo.io/) 生成器来处理。
|
||||
关于如何使用相关技术，有[很多可用的资源](https://gohugo.io/documentation/)。
|
||||
|
||||
我们知道这一需求可能给那些对此过程不熟悉的朋友们带来不便，
|
||||
我们也一直在寻找降低难度的解决方案。
|
||||
如果你有降低难度的好主意，请自荐帮忙。
|
||||
|
||||
<!--
|
||||
The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject) manages the review process for blog posts. For more information, see [Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post).
|
||||
|
||||
To submit a blog post follow these directions:
|
||||
-->
|
||||
SIG Docs [博客子项目](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject) 负责管理博客的评阅过程。
|
||||
更多信息可参考[提交博文](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post)。
|
||||
|
||||
要提交博文，你可以遵从以下指南：
|
||||
<!--
|
||||
- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) directory.
|
||||
|
||||
- Ensure that your blog post follows the correct naming conventions and the following frontmatter (metadata) information:
|
||||
|
||||
- The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example, `2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`.
|
||||
- Do **not** include dots in the filename. A name like `2020-01-01-whats-new-in-1.19.md` causes failures during a build.
|
||||
- The front matter must include the following:
|
||||
-->
|
||||
- [发起一个包含新博文的 PR](/zh/docs/contribute/new-content/open-a-pr/#fork-the-repo)。
|
||||
新博文要创建于 [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) 目录下。
|
||||
|
||||
- 确保你的博文遵从合适的命名规范，并带有下面的引言（元数据）信息：
|
||||
|
||||
- Markdown 文件名必须符合格式 `YYYY-MM-DD-Your-Title-Here.md`。
|
||||
例如，`2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`。
|
||||
- **不要**在文件名中包含多余的句点。类似 `2020-01-01-whats-new-in-1.19.md`
|
||||
这类文件名会导致文件无法正确打开。
|
||||
- 引言部分必须包含以下内容：
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: blog
|
||||
title: "Your Title Here"
|
||||
date: YYYY-MM-DD
|
||||
slug: text-for-URL-link-here-no-spaces
|
||||
---
|
||||
```
|
||||
<!--
|
||||
- The first or initial commit message should be a short summary of the work being done and should stand alone as a description of the blog post. Please note that subsequent edits to your blog will be squashed into this main commit, so it should be as useful as possible.
|
||||
- Examples of a good commit message:
|
||||
- _Add blog post on the foo kubernetes feature_
|
||||
- _blog: foobar announcement_
|
||||
- Examples of bad commit message:
|
||||
- _Add blog post_
|
||||
- _._
|
||||
- _initial commit_
|
||||
- _draft post_
|
||||
- The blog team will then review your PR and give you comments on things you might need to fix. After that the bot will merge your PR and your blog post will be published.
|
||||
-->
|
||||
- 第一个或者最初的提交的描述信息中应该包含一个所作工作的简单摘要，
|
||||
并作为整个博文的一个独立描述。
|
||||
请注意，对博文的后续修改编辑都会最终合并到此主提交中，所以此提交的描述信息
|
||||
应该尽量有用。
|
||||
- 较好的提交消息（Commit Message）示例：
|
||||
- _Add blog post on the foo kubernetes feature_
|
||||
- _blog: foobar announcement_
|
||||
- 较差的提交消息示例：
|
||||
- _Add blog post_
|
||||
- _._
|
||||
- _initial commit_
|
||||
- _draft post_
|
||||
- 博客团队会对 PR 内容进行评阅，为你提供一些评语以便修订。
|
||||
之后，机器人会将你的博文合并并发表。
|
||||
|
||||
<!--
|
||||
- If the content of the blog post contains only content that is not expected to require updates to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic warning about outdated content added to blog posts older than one year.
|
||||
- To mark a blog post as evergreen, add this to the front matter:
|
||||
|
||||
```yaml
|
||||
evergreen: true
|
||||
```
|
||||
- Examples of content that should not be marked evergreen:
|
||||
- **Tutorials** that only apply to specific releases or versions and not all future versions
|
||||
- References to pre-GA APIs or features
|
||||
-->
|
||||
|
||||
- 如果博文的内容仅包含预期无需更新就能对读者保持精准的内容，
|
||||
则可以将这篇博文标记为长期有效（evergreen），
|
||||
且免除添加博文发表一年后内容过期的自动警告。
|
||||
- 要将一篇博文标记为长期有效，请在引言部分添加以下标记：
|
||||
|
||||
```yaml
|
||||
evergreen: true
|
||||
```
|
||||
- 不应标记为长期有效的内容示例：
|
||||
- 仅适用于特定发行版或版本而不是所有未来版本的**教程**
|
||||
- 对非正式发行（Pre-GA）API 或功能特性的引用
|
||||
|
||||
<!--
|
||||
## Submit a case study
|
||||
|
||||
Case studies highlight how organizations are using Kubernetes to solve
|
||||
real-world problems. The Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} collaborate with you on all case studies.
|
||||
|
||||
Have a look at the source for the
|
||||
[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies).
|
||||
|
||||
Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md) and submit your request as outlined in the guidelines.
|
||||
-->
|
||||
## 提交案例分析
|
||||
|
||||
案例分析用来概述组织如何使用 Kubernetes 解决现实世界的问题。
|
||||
Kubernetes 市场化团队和 {{< glossary_tooltip text="CNCF" term_id="cncf" >}} 成员会与你一起工作，
|
||||
撰写所有的案例分析。
|
||||
|
||||
请查看[现有案例分析](https://github.com/kubernetes/website/tree/main/content/en/case-studies)的源码。
|
||||
|
||||
参考[案例分析指南](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md)，
|
||||
根据指南中的注意事项提交你的 PR 请求。
|
||||
|
||||
@@ -0,0 +1,280 @@
|
||||
---
|
||||
title: 为发行版本撰写功能特性文档
|
||||
linktitle: 为发行版本撰写文档
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 20
|
||||
card:
|
||||
name: contribute
|
||||
weight: 45
|
||||
title: 为发行版本撰写功能特性文档
|
||||
---
|
||||
<!--
|
||||
title: Documenting a feature for a release
|
||||
linktitle: Documenting for a release
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 20
|
||||
card:
|
||||
name: contribute
|
||||
weight: 45
|
||||
title: Documenting a feature for a release
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
Each major Kubernetes release introduces new features that require documentation.
|
||||
New releases also bring updates to existing features and documentation (such as upgrading a feature from alpha to beta).
|
||||
|
||||
Generally, the SIG responsible for a feature submits draft documentation of the
|
||||
feature as a pull request to the appropriate development branch of the
|
||||
`kubernetes/website` repository, and someone on the SIG Docs team provides
|
||||
editorial feedback or edits the draft directly. This section covers the branching
|
||||
conventions and process used during a release by both groups.
|
||||
-->
|
||||
Kubernetes 的每个主要版本发布都会包含一些需要文档说明的新功能。
|
||||
新的发行版本也会对已有功能特性和文档（例如将某功能特性从 alpha 升级为
|
||||
beta）进行更新。
|
||||
|
||||
通常，负责某功能特性的 SIG 要为功能特性的文档草拟文档，并针对 `kubernetes/website`
|
||||
仓库的合适的开发分支发起拉取请求。
|
||||
SIG Docs 团队会提供文字方面的反馈意见，或者直接编辑文档草稿。
|
||||
本节讨论两个小组在分支方面和发行期间所遵从的流程方面的约定。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## For documentation contributors
|
||||
|
||||
In general, documentation contributors don't write content from scratch for a release.
|
||||
Instead, they work with the SIG creating a new feature to refine the draft documentation and make it release ready.
|
||||
|
||||
After you've chosen a feature to document or assist, ask about it in the `#sig-docs`
|
||||
Slack channel, in a weekly SIG Docs meeting, or directly on the PR filed by the
|
||||
feature SIG. If you're given the go-ahead, you can edit into the PR using one of
|
||||
the techniques described in
|
||||
[Commit into another person's PR](/docs/contribute/review/for-approvers/#commit-into-another-persons-pr).
|
||||
-->
|
||||
## 对于文档贡献者
|
||||
|
||||
一般而言，文档贡献者不会为某个发行版本从头撰写文档。
|
||||
相反，他们会与开发该功能特性的 SIG 团队一起，对文档草稿进行润色，
|
||||
使之符合发布条件。
|
||||
|
||||
在你选定了某个功能特性，为其撰写文档（主笔或辅助），请在 `#sig-docs` Slack 频道、SIG Docs 的每周例会上，
|
||||
或者在功能特性对应的 PR 上提出咨询。
|
||||
如果继续工作是没有问题的，你可以使用
|
||||
[向他人的 PR 中提交](/zh/docs/contribute/review/for-approvers/#commit-into-another-persons-pr)
|
||||
中描述的技术之一，参与 PR 的编辑工作。
|
||||
|
||||
<!--
|
||||
### Find out about upcoming features
|
||||
|
||||
To find out about upcoming features, attend the weekly SIG Release meeting (see
|
||||
the [community](https://kubernetes.io/community/) page for upcoming meetings)
|
||||
and monitor the release-specific documentation
|
||||
in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/)
|
||||
repository. Each release has a sub-directory in the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
directory. The sub-directory contains a release schedule, a draft of the release
|
||||
notes, and a document listing each person on the release team.
|
||||
-->
|
||||
### 了解即将发布的功能特性
|
||||
|
||||
要了解即将发布的功能特性，可以参加每周的 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)
|
||||
下都有一个对应的子目录。
|
||||
该子目录包含了发行版本的时间计划、发行公告的草稿以及列举发行团队名单的文档。
|
||||
|
||||
<!--
|
||||
The release schedule contains links to all other documents, meetings,
|
||||
meeting minutes, and milestones relating to the release. It also contains
|
||||
information about the goals and timeline of the release, and any special
|
||||
processes in place for this release. Near the bottom of the document, several
|
||||
release-related terms are defined.
|
||||
|
||||
This document also contains a link to the **Feature tracking sheet**, which is
|
||||
the official way to find out about all new features scheduled to go into the
|
||||
release.
|
||||
-->
|
||||
发行时间计划文件中包含到所有其他文档、会议、会议记录及发行相关的里程碑的链接。
|
||||
其中也包含关于发行版本的目标列表、时间线，以及当前发行版本中就绪的特殊流程的信息。
|
||||
文档末尾附近定义了若干与该发行版本有关的术语。
|
||||
|
||||
此文档也包含到 **功能特性跟踪清单** 的链接。
|
||||
这一清单是了解哪些功能特性计划进入某发行版本的正式途径。
|
||||
|
||||
<!--
|
||||
The release team document lists who is responsible for each release role. If
|
||||
it's not clear who to talk to about a specific feature or question you have,
|
||||
either attend the release meeting to ask your question, or contact the release
|
||||
lead so that they can redirect you.
|
||||
|
||||
The release notes draft is a good place to find out about
|
||||
specific features, changes, deprecations, and more about the release. The
|
||||
content is not finalized until late in the release cycle, so use caution.
|
||||
-->
|
||||
发行团队文档列举了哪些人扮演着各个发行版本的不同角色。
|
||||
如果不清楚要联系谁来讨论特定的功能特性或者回答你的问题，
|
||||
你可以参加发行团队的会议，提出你的问题，或者联系发行团队的牵头人，
|
||||
这样他们就可以帮你找到正确的联系人。
|
||||
|
||||
发行说明草稿是用来发现与特定发行版本相关的功能特性、变更、废弃以及其他信息的好来源。
|
||||
由于在发行周期的后段该文档的内容才会最终定稿，参考其中的信息时请谨慎。
|
||||
|
||||
<!--
|
||||
### Feature tracking sheet
|
||||
|
||||
The feature tracking sheet [for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
lists each feature that is planned for a release.
|
||||
Each line item includes the name of the feature, a link to the feature's main
|
||||
GitHub issue, its stability level (Alpha, Beta, or Stable), the SIG and
|
||||
individual responsible for implementing it, whether it
|
||||
needs docs, a draft release note for the feature, and whether it has been
|
||||
merged. Keep the following in mind:
|
||||
-->
|
||||
### 特性跟踪清单 {#feature-tracking-sheet}
|
||||
|
||||
针对[给定 Kubernetes 发行版本](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
特性跟踪清单中列举的是计划包含于该版本中的每个功能特性。
|
||||
每一行中都包含特性的名称、特性对应的主要 GitHub Issue，其稳定性级别（ALpha、
|
||||
Beta 或 Stable）、负责实现该特性的 SIG 和个人、是否该特性需要文档、该特性的
|
||||
发行说明草稿以及该特性是否已经被合并等等。阅读此清单时请注意：
|
||||
|
||||
<!--
|
||||
- Beta and Stable features are generally a higher documentation priority than
|
||||
Alpha features.
|
||||
- It's hard to test (and therefore to document) a feature that hasn't been merged,
|
||||
or is at least considered feature-complete in its PR.
|
||||
- Determining whether a feature needs documentation is a manual process. Even if
|
||||
a feature is not marked as needing docs, you may need to document the feature.
|
||||
-->
|
||||
- Beta 和 Stable 功能特性通常比 Alpha 特性更为需要文档支持。
|
||||
- 如果某功能特性尚未被合并，就很难测试或者为其撰写文档。
|
||||
对于对应的 PR 而言，也很难讲特性是否完全实现。
|
||||
- 确定某个功能特性是否需要文档的过程是一个手动的过程。
|
||||
即使某个功能特性没有标记需要文档，你仍可能需要为其提供文档。
|
||||
|
||||
<!--
|
||||
## For developers or other SIG members
|
||||
|
||||
This section is information for members of other Kubernetes SIGs documenting new features
|
||||
for a release.
|
||||
|
||||
If you are a member of a SIG developing a new feature for Kubernetes, you need
|
||||
to work with SIG Docs to be sure your feature is documented in time for the
|
||||
release. Check the
|
||||
[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
or check in the `#sig-release` Kubernetes Slack channel to verify scheduling details and
|
||||
deadlines.
|
||||
-->
|
||||
## 针对开发人员或其他 SIG 成员
|
||||
|
||||
本节中的信息是针对为发行版本中新功能特性撰写文档的来自其他 Kubernetes SIGs
|
||||
的成员。
|
||||
|
||||
如果你是某个 SIG 的成员，负责为 Kubernetes 开发某一项新的功能特性，你需要与
|
||||
SIG Docs 一起工作，确保这一新功能在发行之前已经为之撰写文档。
|
||||
请参考[特性跟踪清单](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
或者 Kubernetes Slack 上的 `#sig-release` 频道，检查时间安排的细节以及截止日期。
|
||||
|
||||
<!--
|
||||
### Open a placeholder PR
|
||||
|
||||
1. Open a **draft** pull request against the
|
||||
`dev-{{< skew nextMinorVersion >}}` branch in the `kubernetes/website` repository, with a small
|
||||
commit that you will amend later. To create a draft pull request, use the
|
||||
Create Pull Request drop-down and select **Create Draft Pull Request**,
|
||||
then click **Draft Pull Request**.
|
||||
2. Edit the pull request description to include links to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes)
|
||||
PR(s) and [kubernetes/enhancements](https://github.com/kubernetes/enhancements) issue(s).
|
||||
3. Leave a comment on the related [kubernetes/enhancements](https://github.com/kubernetes/enhancements)
|
||||
issue with a link to the PR to notify the docs person managing this release that
|
||||
the feature docs are coming and should be tracked for the release.
|
||||
-->
|
||||
### 提交占位 PR {#open-a-placeholder-pr}
|
||||
|
||||
1. 在 `kubernetes/website` 仓库上针对 `dev-{{< skew nextMinorVersion >}}`
|
||||
分支提交一个**draft** PR，其中包含较少的、待以后慢慢补齐的提交内容。
|
||||
要创建一个草案（draft）状态的 PR，可以在 Create Pull Request 下拉菜单中
|
||||
选择 **Create Draft Pull Request**，然后点击 **Draft Pull Request**。
|
||||
1. 编辑拉取请求描述以包括指向 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) PR
|
||||
和 [kubernetes/enhancements](https://github.com/kubernetes/enhancements) 问题的链接。
|
||||
1. 在对应的 [kubernetes/enhancements](https://github.com/kubernetes/enhancements)
|
||||
issue 上添加评论，附上新 PR 的链接以便管理此发行版本的人员能够得到通知，
|
||||
了解特性的文档正在被撰写，在新的发行版本中要跟踪其进展。
|
||||
|
||||
<!--
|
||||
If your feature does not need
|
||||
any documentation changes, make sure the sig-release team knows this, by
|
||||
mentioning it in the `#sig-release` Slack channel. If the feature does need
|
||||
documentation but the PR is not created, the feature may be removed from the
|
||||
milestone.
|
||||
-->
|
||||
如果对应的功能特性不需要任何类型的文档变更，请通过在 `#sig-release` Slack
|
||||
频道声明这一点以确保 sig-release 团队了解。
|
||||
如果功能特性确实需要文档，而没有对应的 PR
|
||||
提交，该功能特性可能会被从里程碑中移除。
|
||||
|
||||
<!--
|
||||
### PR ready for review
|
||||
|
||||
When ready, populate your placeholder PR with feature documentation and change
|
||||
the state of the PR from draft to **ready for review**. To mark a pull request
|
||||
as ready for review, navigate to the merge box and click **Ready for review**.
|
||||
|
||||
Do your best to describe your feature and how to use it. If you need help
|
||||
structuring your documentation, ask in the `#sig-docs` slack channel.
|
||||
|
||||
When you complete your content, the documentation person assigned to your
|
||||
feature reviews it.
|
||||
To ensure technical accuracy, the content may also require a technical review from corresponding SIG(s).
|
||||
Use their suggestions to get the content to a release ready state.
|
||||
-->
|
||||
### PR 准备好评阅 {#pr-ready-for-review}
|
||||
|
||||
时机成熟时，你可以在你的占位 PR 中完成功能特性文档，并将 PR 的状态
|
||||
从草案状态更改为 **Ready for Review**。要将一个拉取请求标记为预备
|
||||
评阅，转到页面的 merge 框，点击 **Ready for review**。
|
||||
|
||||
尽可能为功能特性提供详尽文档以及使用说明。如果你需要文档组织方面的帮助，请
|
||||
在 `#sig-docs` Slack 频道中提问。
|
||||
|
||||
当你已经完成内容撰写，指派给你的功能特性的文档贡献者会去评阅文档。
|
||||
为了确保技术准确性，内容可能还需要相应 SIG 的技术审核。
|
||||
尽量利用他们所给出的建议，改进文档内容以达到发布就绪状态。
|
||||
|
||||
<!--
|
||||
If your feature is an Alpha or Beta feature and is behind a feature gate,
|
||||
make sure you add it to [Alpha/Beta Feature gates](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features)
|
||||
table as part of your pull request. With new feature gates, a description of
|
||||
the feature gate is also required. If your feature is GA'ed or deprecated,
|
||||
make sure to move it from that table to [Feature gates for graduated or deprecated features](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-graduated-or-deprecated-features)
|
||||
table with Alpha and Beta history intact.
|
||||
-->
|
||||
如果你在处理的功能特性处于 Alpha 或 Beta 阶段并由某特性门控控制，
|
||||
请确保在你的 PR 中，该特性门控被添加到
|
||||
[Alpha/Beta 特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features)
|
||||
表格中。对于新的特性门控选项，需要为该特性门控提供一段描述。
|
||||
如果所处理的功能特性已经进入正式发布（GA）状态或者被废弃，
|
||||
请确保将其从上述表格中迁移到
|
||||
[已毕业或废弃的特性](/zh/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-graduated-or-deprecated-features)
|
||||
表格中，并确保迁移后保留其 Alpha、Beta 版本变迁历史。
|
||||
|
||||
<!--
|
||||
### All PRs reviewed and ready to merge
|
||||
|
||||
If your PR has not yet been merged into the `dev-{{< skew nextMinorVersion >}}` branch by the release deadline, work with the
|
||||
docs person managing the release to get it in by the deadline. If your feature needs
|
||||
documentation and the docs are not ready, the feature may be removed from the
|
||||
milestone.
|
||||
-->
|
||||
### 所有 PR 均经过评审且合并就绪 {#all-prs-reviewd-and-ready-to-merge}
|
||||
|
||||
如果你的 PR 在发行截止日期之前尚未合并到 `dev-{{< skew nextMinorVersion >}}` 分支，
|
||||
请与负责管理该发行版本的文档团队成员一起合作，在截止期限之前将其合并。
|
||||
如果功能特性需要文档，而文档并未就绪，该特性可能会被从里程碑中去除。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,225 @@
|
||||
---
|
||||
title: 参与 SIG Docs
|
||||
content_type: concept
|
||||
weight: 60
|
||||
card:
|
||||
name: contribute
|
||||
weight: 60
|
||||
---
|
||||
<!--
|
||||
title: Participating in SIG Docs
|
||||
content_type: concept
|
||||
weight: 60
|
||||
card:
|
||||
name: contribute
|
||||
weight: 60
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
SIG Docs is one of the
|
||||
[special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md)
|
||||
within the Kubernetes project, focused on writing, updating, and maintaining
|
||||
the documentation for Kubernetes as a whole. See
|
||||
[SIG Docs from the community github repo](https://github.com/kubernetes/community/tree/master/sig-docs)
|
||||
for more information about the SIG.
|
||||
-->
|
||||
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 welcomes content and reviews from all contributors. Anyone can open a
|
||||
pull request (PR), and anyone is welcome to file issues about content or comment
|
||||
on pull requests in progress.
|
||||
-->
|
||||
SIG Docs 欢迎所有贡献者提供内容和审阅。任何人可以提交拉取请求（PR）。
|
||||
欢迎所有人对文档内容创建 Issue 和对正在处理中的 PR 进行评论。
|
||||
|
||||
<!--
|
||||
You can also become a [member](/docs/contribute/participating/roles-and-responsibilities/#members),
|
||||
[reviewer](/docs/contribute/participating/roles-and-responsibilities/#reviewers), or [approver](/docs/contribute/participating/roles-and-responsibilities/#approvers). These roles require greater
|
||||
access and entail certain responsibilities for approving and committing changes.
|
||||
See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
|
||||
for more information on how membership works within the Kubernetes community.
|
||||
|
||||
The rest of this document outlines some unique ways these roles function within
|
||||
SIG Docs, which is responsible for maintaining one of the most public-facing
|
||||
aspects of Kubernetes - the Kubernetes website and documentation.
|
||||
-->
|
||||
你也可以成为[成员（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 网站和文档。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
#### SIG Docs chairperson
|
||||
|
||||
Each SIG, including SIG Docs, selects one or more SIG members to act as
|
||||
chairpersons. These are points of contact between SIG Docs and other parts of
|
||||
the Kubernetes organization. They require extensive knowledge of the structure
|
||||
of the Kubernetes project as a whole and how SIG Docs works within it. See
|
||||
[Leadership](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)
|
||||
for the current list of chairpersons.
|
||||
-->
|
||||
## SIG Docs 主席
|
||||
|
||||
每个 SIG，包括 SIG Docs，都会选出一位或多位成员作为主席。
|
||||
主席会成为 SIG Docs 和其他 Kubernetes 组织的联络接口人。
|
||||
他们需要了解整个 Kubernetes 项目的架构，并明白 SIG Docs 如何在其中运作。
|
||||
如需查询当前的主席名单，请查阅
|
||||
[领导人员](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)。
|
||||
|
||||
<!--
|
||||
## SIG Docs teams and automation
|
||||
|
||||
Automation in SIG Docs relies on two different mechanisms for automation:
|
||||
GitHub groups and OWNERS files.
|
||||
-->
|
||||
## SIG Docs 团队和自动化 {#sig-docs-teams-and-automation}
|
||||
|
||||
SIG 文档中的自动化服务依赖于两种不同的自动化机制:
|
||||
GitHub 组和 OWNERS 文件。
|
||||
|
||||
<!--
|
||||
### GitHub teams
|
||||
|
||||
There are two categories of SIG Docs [teams](https://github.com/orgs/kubernetes/teams?query=sig-docs) on GitHub:
|
||||
|
||||
- `@sig-docs-{language}-owners` are approvers and leads
|
||||
- `@sig-docs-{language}-reviewers` are reviewers
|
||||
|
||||
Each can be referenced with their `@name` in GitHub comments to communicate with
|
||||
everyone in that group.
|
||||
|
||||
Sometimes Prow and GitHub teams overlap without matching exactly. For assignment of issues, pull requests, and to support PR approvals,
|
||||
the automation uses information from `OWNERS` files.
|
||||
-->
|
||||
### GitHub 团队 {#github-teams}
|
||||
|
||||
GitHub 上有两类 SIG Docs 团队：
|
||||
|
||||
- `@sig-docs-{language}-owners` 包含批准人和牵头人
|
||||
- `@sig-docs-{language}-reviewers` 包含评阅人
|
||||
|
||||
可以在 GitHub 的评论中使用团队的名称 `@name` 来与团队成员沟通。
|
||||
|
||||
有时候 Prow 所定义的团队和 GitHub 团队有所重叠，并不完全一致。
|
||||
对于指派 Issue、PR 和批准 PR，自动化工具使用来自 `OWNERS` 文件的信息。
|
||||
|
||||
<!--
|
||||
### OWNERS files and front-matter
|
||||
|
||||
The Kubernetes project uses an automation tool called prow for automation
|
||||
related to GitHub issues and pull requests. The
|
||||
[Kubernetes website repository](https://github.com/kubernetes/website) uses
|
||||
two [prow plugins](https://github.com/kubernetes/test-infra/blob/master/prow/plugins):
|
||||
-->
|
||||
### 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
|
||||
|
||||
<!--
|
||||
These two plugins use the
|
||||
[OWNERS](https://github.com/kubernetes/website/blob/main/OWNERS) and
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES)
|
||||
files in the top level of the `kubernetes/website` GitHub repository to control
|
||||
how prow works within the repository.
|
||||
-->
|
||||
这两个插件使用位于 `kubernetes/website` 仓库顶层的
|
||||
[OWNERS](https://github.com/kubernetes/website/blob/main/OWNERS) 文件和
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES)
|
||||
文件来控制 prow 在仓库范围的工作方式。
|
||||
|
||||
<!--
|
||||
An OWNERS file contains a list of people who are SIG Docs reviewers and
|
||||
approvers. OWNERS files can also exist in subdirectories, and can override who
|
||||
can act as a reviewer or approver of files in that subdirectory and its
|
||||
descendents. For more information about OWNERS files in general, see
|
||||
[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md).
|
||||
-->
|
||||
OWNERS 文件包含 SIG Docs 评阅人和批准人的列表。
|
||||
OWNERS 文件也可以存在于子目录中，可以在子目录层级重新设置哪些人可以作为评阅人和
|
||||
批准人，并将这一设定传递到下层子目录。
|
||||
关于 OWNERS 的更多信息，请参考
|
||||
[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md)
|
||||
文档。
|
||||
|
||||
<!--
|
||||
In addition, an individual Markdown file can list reviewers and approvers in its
|
||||
front-matter, either by listing individual GitHub usernames or GitHub groups.
|
||||
|
||||
The combination of OWNERS files and front-matter in Markdown files determines
|
||||
the advice PR owners get from automated systems about who to ask for technical
|
||||
and editorial review of their PR.
|
||||
-->
|
||||
此外，每个独立的 Markdown 文件都可以在其前言部分列出评阅人和批准人，
|
||||
每一项可以是 GitHub 用户名，也可以是 GitHub 组名。
|
||||
|
||||
结合 OWNERS 文件及 Markdown 文件的前言信息，自动化系统可以给 PR 作者可以就应该
|
||||
向谁请求技术和文字评阅给出建议。
|
||||
|
||||
<!--
|
||||
## How merging works
|
||||
|
||||
When a pull request is merged to the branch used to publish content, that content
|
||||
is published to http://kubernetes.io. To ensure that
|
||||
the quality of our published content is high, we limit merging pull requests to
|
||||
SIG Docs approvers. Here's how it works.
|
||||
|
||||
- When a pull request has both the `lgtm` and `approve` labels, has no `hold`
|
||||
labels, and all tests are passing, the pull request merges automatically.
|
||||
- Kubernetes organization members and SIG Docs approvers can add comments to
|
||||
prevent automatic merging of a given pull request (by adding a `/hold` comment
|
||||
or withholding a `/lgtm` comment).
|
||||
- Any Kubernetes member can add the `lgtm` label by adding a `/lgtm` comment.
|
||||
- Only SIG Docs approvers can merge a pull request
|
||||
by adding an `/approve` comment. Some approvers also perform additional
|
||||
specific roles, such as [PR Wrangler](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week) or
|
||||
[SIG Docs chairperson](#sig-docs-chairperson).
|
||||
-->
|
||||
## 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 管理者](/zh/docs/contribute/participate/pr-wranglers/) 或
|
||||
[SIG Docs 主席](#sig-docs-chairperson)等。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
For more information about contributing to the Kubernetes documentation, see:
|
||||
|
||||
- [Contributing new content](/docs/contribute/overview/)
|
||||
- [Reviewing content](/docs/contribute/review/reviewing-prs)
|
||||
- [Documentation style guide](/docs/contribute/style/)
|
||||
-->
|
||||
关于贡献 Kubernetes 文档的更多信息，请参考：
|
||||
|
||||
- [贡献新内容](/zh/docs/contribute/new-content/overview/)
|
||||
- [评阅内容](/zh/docs/contribute/review/reviewing-prs)
|
||||
- [文档样式指南](/zh/docs/contribute/style/)
|
||||
@@ -0,0 +1,224 @@
|
||||
---
|
||||
title: PR 管理者
|
||||
content_type: concept
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: PR wranglers
|
||||
content_type: concept
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers) take week-long shifts [managing pull requests](https://github.com/kubernetes/website/wiki/PR-Wranglers) for the repository.
|
||||
|
||||
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-responsibilities/#approvers)们每周轮流负责
|
||||
[管理仓库的 PR](https://github.com/kubernetes/website/wiki/PR-Wranglers)。
|
||||
|
||||
本节介绍 PR 管理者的职责。关于如何提供较好的评审意见，
|
||||
可参阅[评审变更](/zh/docs/contribute/review/)。
|
||||
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Duties
|
||||
|
||||
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.
|
||||
-->
|
||||
## 职责 {#duties}
|
||||
在为期一周的轮值期内，PR 管理者要：
|
||||
|
||||
- 每天对新增的 Issues 判定和打标签。参见
|
||||
[对 Issues 进行判定和分类](/zh/docs/contribute/review/for-approvers/#triage-and-categorize-issues)
|
||||
以了解 SIG Docs 如何使用元数据的详细信息。
|
||||
- 检查[悬决的 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。
|
||||
<!--
|
||||
- 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.
|
||||
- You can also tag a [SIG](https://github.com/kubernetes/community/blob/master/sig-list.md) for a review by commenting `@kubernetes/<sig>-pr-reviews` on the PR.
|
||||
-->
|
||||
- 确保贡献者完成 [CLA](https://github.com/kubernetes/community/blob/master/CLA.md) 签署。
|
||||
- 使用[此脚本](https://github.com/zparnold/k8s-docs-pr-botherer)自动提醒尚未签署
|
||||
CLA 的贡献者签署 CLA。
|
||||
- 针对提供提供反馈，请求其他 SIG 的成员进行技术审核。
|
||||
- 为 PR 所建议的内容更改提供就地反馈。
|
||||
- 如果你需要验证内容，请在 PR 上发表评论并要求贡献者提供更多细节。
|
||||
- 设置相关的 `sig/` 标签。
|
||||
- 如果需要，根据文件开头的 `reviewers:` 块来指派评审人。
|
||||
- 你也可以通过在 PR 上作出 `@kubernetes/<sig>-pr-reviews` 的评论以标记需要某个
|
||||
[SIG](https://github.com/kubernetes/community/blob/master/sig-list.md) 来评审。
|
||||
<!--
|
||||
- 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/). As you approve the change,
|
||||
open a new issue to address the style concern. You can usually write these style fix
|
||||
issues as [good first issues](https://kubernetes.dev/docs/guide/help-wanted/#good-first-issue).
|
||||
- Using style fixups as good first issues is a good way to ensure a supply of easier tasks
|
||||
to help onboard new contributors.
|
||||
-->
|
||||
- 使用 `/approve` 评论来批准可以合并的 PR，在 PR 就绪时将其合并。
|
||||
- PR 在被合并之前，应该有来自其他成员的 `/lgtm` 评论。
|
||||
- 可以考虑接受那些技术上准确，但文风上不满足
|
||||
[风格指南](/zh/docs/contribute/style/style-guide/)要求的 PR。
|
||||
批准变更时，可以登记一个新的 Issue 来解决文档风格问题。
|
||||
你通常可以将这些风格修复问题标记为 `good first issue`。
|
||||
- 将风格修复事项标记为 `good first issue` 可以很好地确保向新加入的贡献者分派一些比较简单的任务，
|
||||
这有助于接纳新的贡献者。
|
||||
|
||||
<!--
|
||||
### Helpful GitHub queries for wranglers
|
||||
|
||||
The following queries are helpful when wrangling.
|
||||
After working through these queries, the remaining list of PRs to review is usually small.
|
||||
These queries exclude localization PRs. All queries are against the main branch except the last one.
|
||||
-->
|
||||
### 对管理者有用的 GitHub 查询
|
||||
|
||||
执行管理操作时，以下查询很有用。完成以下这些查询后，剩余的要审阅的 PR 列表通常很小。
|
||||
这些查询都不包含本地化的 PR，并仅包含主分支上的 PR（除了最后一个查询）。
|
||||
|
||||
<!--
|
||||
- [No CLA, not eligible to merge](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+no%22+-label%3A%22do-not-merge%2Fwork-in-progress%22+-label%3A%22do-not-merge%2Fhold%22+label%3Alanguage%2Fen):
|
||||
Remind the contributor to sign the CLA. If both the bot and a human have reminded them, close
|
||||
the PR and remind them that they can open it after signing the CLA.
|
||||
**Do not review PRs whose authors have not signed the CLA!**
|
||||
- [Needs LGTM](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+-label%3A%22cncf-cla%3A+no%22+-label%3Ado-not-merge%2Fwork-in-progress+-label%3Ado-not-merge%2Fhold+label%3Alanguage%2Fen+-label%3Algtm):
|
||||
Lists PRs that need an LGTM from a member. If the PR needs technical review, loop in one of the reviewers suggested by the bot. If the content needs work, add suggestions and feedback in-line.
|
||||
- [Has LGTM, needs docs approval](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+-label%3Ado-not-merge%2Fwork-in-progress+-label%3Ado-not-merge%2Fhold+label%3Alanguage%2Fen+label%3Algtm+):
|
||||
Lists PRs that need an `/approve` comment to merge.
|
||||
- [Quick Wins](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+base%3Amain+-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): Lists PRs against the main branch with no clear blockers. (change "XS" in the size label as you work through the PRs [XS, S, M, L, XL, XXL]).
|
||||
- [Not against the primary branch](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3Alanguage%2Fen+-base%3Amain): If the PR is against a `dev-` branch, it's for an upcoming release. Assign the [docs release manager](https://github.com/kubernetes/sig-release/tree/master/release-team#kubernetes-release-team-roles) using: `/assign @<manager's_github-username>`. If the PR is against an old branch, help the author figure out whether it's targeted against the best branch.
|
||||
-->
|
||||
- [未签署 CLA，不可合并的 PR](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+no%22+-label%3A%22do-not-merge%2Fwork-in-progress%22+-label%3A%22do-not-merge%2Fhold%22+label%3Alanguage%2Fen)：
|
||||
提醒贡献者签署 CLA。如果机器人和审阅者都已经提醒他们，请关闭 PR，并提醒他们在签署 CLA 后可以重新提交。
|
||||
|
||||
**在作者没有签署 CLA 之前，不要审阅他们的 PR！**
|
||||
|
||||
- [需要 LGTM](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+-label%3A%22cncf-cla%3A+no%22+-label%3Ado-not-merge%2Fwork-in-progress+-label%3Ado-not-merge%2Fhold+label%3Alanguage%2Fen+-label%3Algtm)：
|
||||
列举需要来自成员的 LGTM 评论的 PR。
|
||||
如果需要技术审查，请告知机器人所建议的审阅者。
|
||||
如果 PR 继续改进，就地提供更改建议或反馈。
|
||||
|
||||
- [已有 LGTM标签，需要 Docs 团队批准](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+-label%3Ado-not-merge%2Fwork-in-progress+-label%3Ado-not-merge%2Fhold+label%3Alanguage%2Fen+label%3Algtm+)：
|
||||
列举需要 `/approve` 评论来合并的 PR。
|
||||
|
||||
- [快速批阅](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+base%3Amain+-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)：
|
||||
列举针对主分支的、没有明确合并障碍的 PR。
|
||||
在浏览 PR 时，可以将 "XS" 尺寸标签更改为 "S"、"M"、"L"、"XL"、"XXL"。
|
||||
|
||||
- [非主分支的 PR](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3Alanguage%2Fen+-base%3Amain):
|
||||
如果 PR 针对 `dev-` 分支，则表示它适用于即将发布的版本。
|
||||
请添加带有 `/assign @<负责人的 github 账号>`，将其指派给
|
||||
[发行版本负责人](https://github.com/kubernetes/sig-release/tree/master/release-team#kubernetes-release-team-roles)。
|
||||
如果 PR 是针对旧分支，请帮助 PR 作者确定是否所针对的是最合适的分支。
|
||||
|
||||
<!--
|
||||
### Helpful Prow commands for wranglers
|
||||
-->
|
||||
### 对管理者有用的 Prow 命令 {#helpful-prow-commands-for-wranglers}
|
||||
|
||||
```
|
||||
# 添加 English 标签
|
||||
/language en
|
||||
|
||||
# 如果 PR 包含多个提交（commits），添加 squash 标签
|
||||
/label tide/merge-method-squash
|
||||
|
||||
# 使用 Prow 来为 PR 重设标题（例如一个正在处理 [WIP] 的 PR 或为 PR 提供更好的细节信息）
|
||||
/retitle [WIP] <TITLE>
|
||||
```
|
||||
|
||||
<!--
|
||||
### When to close Pull Requests
|
||||
|
||||
Reviews and approvals are one tool to keep our PR queue short and current. Another tool is closure.
|
||||
|
||||
Close PRs where:
|
||||
- The author hasn't signed the CLA for two weeks.
|
||||
|
||||
Authors can reopen the PR after signing the CLA. This is a low-risk way to make sure nothing gets merged without a signed CLA.
|
||||
|
||||
- The author has not responded to comments or feedback in 2 or more weeks.
|
||||
|
||||
Don't be afraid to close pull requests. Contributors can easily reopen and resume works in progress. Often a closure notice is what spurs an author to resume and finish their contribution.
|
||||
|
||||
To close a pull request, leave a `/close` comment on the PR.
|
||||
-->
|
||||
### 何时关闭 PR {#when-to-close-pull-requests}
|
||||
|
||||
审查和批准是缩短和更新我们的 PR 队列的一种方式；另一种方式是关闭 PR。
|
||||
|
||||
当以下条件满足时，可以关闭 PR：
|
||||
|
||||
- 作者两周内未签署 CLA。
|
||||
PR 作者可以在签署 CLA 后重新打开 PR，因此这是确保未签署 CLA 的 PR 不会被合并的一种风险较低的方法。
|
||||
|
||||
- 作者在两周或更长时间内未回复评论或反馈。
|
||||
|
||||
不要害怕关闭 PR。贡献者可以轻松地重新打开并继续工作。
|
||||
通常，关闭通知会激励作者继续完成其贡献。
|
||||
|
||||
要关闭 PR，请在 PR 上输入 `/close` 评论。
|
||||
|
||||
<!--
|
||||
The [`k8s-ci-robot`](https://github.com/k8s-ci-robot) bot marks issues as stale after 90 days of inactivity. After 30 more days it marks issues as rotten and closes them. PR wranglers should close issues after 14-30 days of inactivity.
|
||||
-->
|
||||
{{< note >}}
|
||||
一个名为 [`k8s-ci-robot`](https://github.com/k8s-ci-robot) 的自动服务会在 Issue 停滞 90
|
||||
天后自动将其标记为过期；然后再等 30 天，如果仍然无人过问，则将其关闭。
|
||||
PR 管理者应该在 issues 处于无人过问状态 14-30 天后关闭它们。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## PR Wrangler shadow program
|
||||
|
||||
In late 2021, SIG Docs introduced the PR Wrangler Shadow Program. The program was introduced to help new contributors understand the PR wrangling process.
|
||||
-->
|
||||
## PR 管理者影子计划
|
||||
|
||||
2021 下半年，SIG Docs 推出了 PR 管理者影子计划（PR Wrangler Shadow Program）。
|
||||
该计划旨在帮助新的贡献者们了解 PR 管理流程。
|
||||
|
||||
<!--
|
||||
### Become a shadow
|
||||
|
||||
- If you are interested in shadowing as a PR wrangler, please visit the [PR Wranglers Wiki page](https://github.com/kubernetes/website/wiki/PR-Wranglers) to see the PR wrangling schedule for this year and sign up.
|
||||
|
||||
- Kubernetes org members can edit the [PR Wranglers Wiki page](https://github.com/kubernetes/website/wiki/PR-Wranglers) and sign up to shadow an existing PR Wrangler for a week.
|
||||
|
||||
- Others can reach out on the [#sig-docs Slack channel](https://kubernetes.slack.com/messages/sig-docs) for requesting to shadow an assigned PR Wrangler for a specific week. Feel free to reach out to Brad Topol (`@bradtopol`) or one of the [SIG Docs co-chairs/leads](https://github.com/kubernetes/community/tree/master/sig-docs#leadership).
|
||||
|
||||
- Once you've signed up to shadow a PR Wrangler, introduce yourself to the PR Wrangler on the [Kubernetes Slack](https://slack.k8s.io).
|
||||
-->
|
||||
### 成为一名影子
|
||||
|
||||
- 如果你有兴趣成为一名 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](https://slack.k8s.io) 向这名 PR 管理者做一次自我介绍。
|
||||
@@ -0,0 +1,418 @@
|
||||
---
|
||||
title: 角色与责任
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, you can apply for different levels of membership in the community.
|
||||
These roles allow you to take on more responsibility within the community.
|
||||
Each role requires more time and commitment. The roles are:
|
||||
|
||||
- Anyone: regular contributors to the Kubernetes documentation
|
||||
- Members: can assign and triage issues and provide non-binding review on pull requests
|
||||
- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality
|
||||
- Approvers: can lead reviews on documentation and merge changes
|
||||
-->
|
||||
任何人都可以为 Kubernetes 作出贡献。随着你对 SIG Docs 的贡献增多，你可以申请
|
||||
社区内不同级别的成员资格。
|
||||
这些角色使得你可以在社区中承担更多的责任。
|
||||
每个角色都需要更多的时间和投入。具体包括：
|
||||
|
||||
- 任何人（Anyone）：为 Kubernetes 文档作出贡献的普通贡献者。
|
||||
- 成员（Members）：可以对 Issue 进行分派和判别，对 PR 提出无约束性的评审意见。
|
||||
- 评审人（Reviewers）：可以领导对文档 PR 的评审，可以对变更的质量进行判别。
|
||||
- 批准人（Approvers）：可以领导对文档的评审并合并变更。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Anyone
|
||||
|
||||
Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors!
|
||||
|
||||
Anyone can:
|
||||
|
||||
- Open an issue in any [Kubernetes](https://github.com/kubernetes/) repository, including [`kubernetes/website`](https://github.com/kubernetes/website)
|
||||
- Give non-binding feedback on a pull request
|
||||
- Contribute to a localization
|
||||
- Suggest improvements on [Slack](http://slack.k8s.io/) or the [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
|
||||
After [signing the CLA](/docs/contribute/new-content/overview/#sign-the-cla), anyone can also:
|
||||
|
||||
- Open a pull request to improve existing content, add new content, or write a blog post or case study
|
||||
- Create diagrams, graphics assets, and embeddable screencasts and videos
|
||||
|
||||
For more information, see [contributing new content](/docs/contribute/new-content/).
|
||||
-->
|
||||
## 任何人（Anyone） {#anyone}
|
||||
|
||||
任何拥有 GitHub 账号的人都可以对 Kubernetes 作出贡献。SIG Docs
|
||||
欢迎所有新的贡献者。
|
||||
|
||||
任何人都可以：
|
||||
|
||||
- 在任何 [Kubernetes](https://github.com/kubernetes/) 仓库，包括
|
||||
[`kubernetes/website`](https://github.com/kubernetes/website) 上报告 Issue。
|
||||
- 对某 PR 给出无约束力的反馈信息
|
||||
- 为本地化提供帮助
|
||||
- 在 [Slack](https://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
|
||||
|
||||
A member is someone who has submitted multiple pull requests to `kubernetes/website`. Members are a part of the [Kubernetes GitHub organization](https://github.com/kubernetes).
|
||||
|
||||
Members can:
|
||||
|
||||
- Do everything listed under [Anyone](#anyone)
|
||||
- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request
|
||||
|
||||
{{< note >}}
|
||||
Using `/lgtm` triggers automation. If you want to provide non-binding approval, commenting "LGTM" works too!
|
||||
{{< /note >}}
|
||||
- Use the `/hold` comment to block merging for a pull request
|
||||
- Use the `/assign` comment to assign a reviewer to a pull request
|
||||
- Provide non-binding review on pull requests
|
||||
- Use automation to triage and categorize issues
|
||||
- Document new features
|
||||
-->
|
||||
## 成员（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
|
||||
|
||||
After submitting at least 5 substantial pull requests and meeting the other [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member):
|
||||
-->
|
||||
### 成为一个成员 {#becoming-a-member}
|
||||
|
||||
在你成功地提交至少 5 个 PR 并满足
|
||||
[相关条件](https://github.com/kubernetes/community/blob/master/community-membership.md#member)
|
||||
之后：
|
||||
|
||||
<!--
|
||||
1. Find two [reviewers](#reviewers) or [approvers](#approvers) to [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your membership.
|
||||
|
||||
Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the
|
||||
[SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
|
||||
{{< note >}}
|
||||
Don't send a direct email or Slack direct message to an individual
|
||||
SIG Docs member. You must request sponsorship before submitting your application.
|
||||
{{< /note >}}
|
||||
|
||||
2. Open a GitHub issue in the [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the **Organization Membership Request** issue template.
|
||||
-->
|
||||
1. 找到两个[评审人](#reviewers)或[批准人](#approvers)为你的成员身份提供
|
||||
[担保](/zh/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. Let your sponsors know about the GitHub issue. You can either:
|
||||
- Mention their GitHub username in an issue (`@<GitHub-username>`)
|
||||
- Send them the issue link using Slack or email.
|
||||
|
||||
Sponsors will approve your request with a `+1` vote. Once your sponsors approve the request, a Kubernetes GitHub admin adds you as a member. Congratulations!
|
||||
|
||||
If your membership request is not accepted you will receive feedback. After addressing the feedback, apply again.
|
||||
|
||||
4. Accept the invitation to the Kubernetes GitHub organization in your email account.
|
||||
|
||||
{{< note >}}
|
||||
GitHub sends the invitation to the default email address in your account.
|
||||
{{< /note >}}
|
||||
-->
|
||||
3. 告知你的担保人你所创建的 Issue，你可以：
|
||||
|
||||
- 在 Issue 中 `@<GitHub-username>` 提及他们的 GitHub 用户名
|
||||
- 通过 Slack 或 email 直接发送给他们 Issue 链接
|
||||
|
||||
担保人会通过 `+1` 投票来批准你的请求。一旦你的担保人批准了该请求，
|
||||
某个 Kubernetes GitHub 管理员会将你添加为组织成员。恭喜！
|
||||
|
||||
如果你的成员请求未被接受，你会收到一些反馈。
|
||||
当处理完反馈意见之后，可以再次发起申请。
|
||||
|
||||
4. 登录你的邮件账户，接受来自 Kubernetes GitHub 组织发出的成员邀请。
|
||||
|
||||
{{< note >}}
|
||||
GitHub 会将邀请发送到你的账户中所设置的默认邮件地址。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Reviewers
|
||||
|
||||
Reviewers are responsible for reviewing open pull requests. Unlike member feedback, you must address reviewer feedback. Reviewers are members of the [@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) GitHub team.
|
||||
|
||||
Reviewers can:
|
||||
|
||||
- Do everything listed under [Anyone](#anyone) and [Members](#members)
|
||||
- Review pull requests and provide binding feedback
|
||||
|
||||
{{< note >}}
|
||||
To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ".
|
||||
{{< /note >}}
|
||||
|
||||
- Edit user-facing strings in code
|
||||
- Improve code comments
|
||||
|
||||
You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area.
|
||||
-->
|
||||
## 评审人（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 的评审人，也可以是某个主题领域的文档的评审人。
|
||||
|
||||
<!--
|
||||
### Assigning reviewers to pull requests
|
||||
|
||||
Automation assigns reviewers to all pull requests. You can request a
|
||||
review from a specific person by commenting: `/assign
|
||||
[@_github_handle]`.
|
||||
|
||||
If the assigned reviewer has not commented on the PR, another reviewer can step in. You can also assign technical reviewers as needed.
|
||||
|
||||
### Using `/lgtm`
|
||||
|
||||
LGTM stands for "Looks good to me" and indicates that a pull request is technically accurate and ready to merge. All PRs need a `/lgtm` comment from a reviewer and a `/approve` comment from an approver to merge.
|
||||
|
||||
A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label.
|
||||
-->
|
||||
### 为 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
|
||||
|
||||
When you meet the
|
||||
[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), you can become a SIG Docs reviewer. Reviewers in other SIGs must apply separately for reviewer status in SIG Docs.
|
||||
|
||||
To apply:
|
||||
-->
|
||||
### 成为评审人 {#becoming-a-reviewer}
|
||||
|
||||
当你满足[相关条件](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer)时，
|
||||
你可以成为一个 SIG Docs 评审人。
|
||||
来自其他 SIG 的评审人必须为 SIG Docs 单独申请评审人资格。
|
||||
|
||||
申请流程如下：
|
||||
|
||||
<!--
|
||||
1. Open a pull request that adds your GitHub user name to a section of the
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) file
|
||||
in the `kubernetes/website` repository.
|
||||
|
||||
{{< note >}}
|
||||
If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`.
|
||||
{{< /note >}}
|
||||
|
||||
2. Assign the PR to one or more SIG-Docs approvers (user names listed under `sig-docs-{language}-owners`).
|
||||
|
||||
If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added,
|
||||
[@k8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) assigns and suggests you as a reviewer on new pull requests.
|
||||
-->
|
||||
1. 发起 PR，将你的 GitHub 用户名添加到 `kubernetes/website` 仓库中
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES)
|
||||
文件的对应节区。
|
||||
|
||||
{{< 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 review and approve pull requests for merging. Approvers are members of the
|
||||
[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) GitHub teams.
|
||||
|
||||
-->
|
||||
## 批准人（Approvers） {#approvers}
|
||||
|
||||
批准人负责评审和批准 PR 以将其合并。
|
||||
批准人是 [@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) GitHub 团队的成员。
|
||||
|
||||
<!--
|
||||
Approvers can do the following:
|
||||
|
||||
- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers)
|
||||
- Publish contributor content by approving and merging pull requests using the `/approve` comment
|
||||
- Propose improvements to the style guide
|
||||
- Propose improvements to docs tests
|
||||
- Propose improvements to the Kubernetes website or other tooling
|
||||
|
||||
If the PR already has a `/lgtm`, or if the approver also comments with `/lgtm`, the PR merges automatically. A SIG Docs approver should only leave a `/lgtm` on a change that doesn't need additional technical review.
|
||||
-->
|
||||
批准人可以执行以下操作：
|
||||
|
||||
- 执行列举在[任何人](#anyone)、[成员](#members)和[评审人](#reviewers)节区的操作
|
||||
- 通过使用 `/approve` 评论来批准、合并 PR，发布贡献者所贡献的内容。
|
||||
- 就样式指南给出改进建议
|
||||
- 对文档测试给出改进建议
|
||||
- 对 Kubernetes 网站或其他工具给出改进建议
|
||||
|
||||
如果某个 PR 已有 `/lgtm` 标签，或者批准人再回复一个 `/lgtm` ，则这个 PR 会自动合并。
|
||||
SIG Docs 批准人应该只在不需要额外的技术评审的情况下才可以标记 `/lgtm`。
|
||||
|
||||
<!--
|
||||
### Approving pull requests
|
||||
|
||||
Approvers and SIG Docs leads are the only ones who can merge pull requests into the website repository. This comes with certain responsibilities.
|
||||
|
||||
- Approvers can use the `/approve` command, which merges PRs into the repo.
|
||||
|
||||
{{< warning >}}
|
||||
A careless merge can break the site, so be sure that when you merge something, you mean it.
|
||||
{{< /warning >}}
|
||||
|
||||
- Make sure that proposed changes meet the [contribution guidelines](/docs/contribute/style/content-guide/#contributing-content).
|
||||
|
||||
If you ever have a question, or you're not sure about something, feel free to call for additional review.
|
||||
-->
|
||||
### 批准 PR {#approving-pull-requests}
|
||||
|
||||
只有批准人和 SIG Docs Leads 可以将 PR 合并到网站仓库。
|
||||
这意味着以下责任：
|
||||
|
||||
- 批准人可以使用 `/approve` 命令将 PR 合并到仓库中。
|
||||
|
||||
{{< warning >}}
|
||||
不小心的合并可能会破坏整个站点。在执行合并操作时，务必小心。
|
||||
{{< /warning >}}
|
||||
|
||||
- 确保所提议的变更满足[贡献指南](/zh/docs/contribute/style/content-guide/#contributing-content)要求。
|
||||
|
||||
如果有问题或者疑惑，可以根据需要请他人帮助评审。
|
||||
|
||||
- 在 `/approve` PR 之前，须验证 Netlify 测试是否正常通过。
|
||||
|
||||
<img src="/images/docs/contribute/netlify-pass.png" width="75%" alt="批准之前必须通过 Netlify 测试" />
|
||||
|
||||
- 在批准之前，请访问 Netlify 的页面预览来确保变更内容可正常显示。
|
||||
|
||||
- 参与 [PR 管理者轮值排班](https://github.com/kubernetes/website/wiki/PR-Wranglers)
|
||||
执行时长为一周的 PR 管理。SIG Docs 期望所有批准人都参与到此轮值工作中。
|
||||
更多细节可参见 [PR 管理者](/zh/docs/contribute/participate/pr-wranglers/)。
|
||||
|
||||
<!--
|
||||
### Becoming an approver
|
||||
|
||||
When you meet the [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), you can become a SIG Docs approver. Approvers in other SIGs must apply separately for approver status in SIG Docs.
|
||||
-->
|
||||
### 成为批准人 {#becoming-an-approver}
|
||||
|
||||
当你满足[一定条件](https://github.com/kubernetes/community/blob/master/community-membership.md#approver)时，可以成为一个 SIG Docs 批准人。
|
||||
来自其他 SIG 的批准人也必须在 SIG Docs 独立申请批准人资格。
|
||||
|
||||
<!--
|
||||
To apply:
|
||||
|
||||
1. Open a pull request adding yourself to a section of the [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) file in the `kubernetes/website` repository.
|
||||
|
||||
{{< note >}}
|
||||
If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`.
|
||||
{{< /note >}}
|
||||
|
||||
2. Assign the PR to one or more current SIG Docs approvers.
|
||||
|
||||
If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) assigns and suggests you as a reviewer on new pull requests.
|
||||
-->
|
||||
申请流程如下：
|
||||
|
||||
1. 发起一个 PR，将自己添加到 `kubernetes/website` 仓库中
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES)
|
||||
文件的对应节区。
|
||||
|
||||
{{< 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。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
- Read about [PR wrangling](/docs/contribute/participating/pr-wranglers), a role all approvers take on rotation.
|
||||
-->
|
||||
- 阅读 [PR 管理者](/zh/docs/contribute/participate/pr-wranglers/)，了解所有批准人轮值的角色。
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: 评阅变更
|
||||
weight: 30
|
||||
---
|
||||
<!--
|
||||
title: Reviewing changes
|
||||
weight: 30
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
This section describes how to review content.
|
||||
-->
|
||||
本节描述如何对内容进行评阅。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
@@ -0,0 +1,432 @@
|
||||
---
|
||||
title: 评阅人和批准人文档
|
||||
linktitle: 评阅人和批准人
|
||||
slug: for-approvers
|
||||
content_type: concept
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: Reviewing for approvers and reviewers
|
||||
linktitle: For approvers and reviewers
|
||||
slug: for-approvers
|
||||
content_type: concept
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
SIG Docs [Reviewers](/docs/contribute/participate/roles-and-responsibilities/#reviewers) and [Approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers) do a few extra things when reviewing a change.
|
||||
|
||||
Every week a specific docs approver volunteers to triage
|
||||
and review pull requests. This
|
||||
person is the "PR Wrangler" for the week. See the
|
||||
[PR Wrangler scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers) for more information. To become a PR Wrangler, attend the weekly SIG Docs meeting and volunteer. Even if you are not on the schedule for the current week, you can still review pull
|
||||
requests (PRs) that are not already under active review.
|
||||
|
||||
In addition to the rotation, a bot assigns reviewers and approvers
|
||||
for the PR based on the owners for the affected files.
|
||||
-->
|
||||
SIG Docs
|
||||
[评阅人（Reviewers）](/zh/docs/contribute/participate/roles-and-responsibilities/#reviewers)
|
||||
和[批准人（Approvers）](/zh/docs/contribute/participate/roles-and-responsibilities/#approvers)
|
||||
在对变更进行评审时需要做一些额外的事情。
|
||||
|
||||
每周都有一个特定的文档批准人自愿负责对 PR 进行分类和评阅。
|
||||
此角色称作该周的“PR 管理者（PR Wrangler）”。
|
||||
相关信息可参考 [PR Wrangler 排班表](https://github.com/kubernetes/website/wiki/PR-Wranglers)。
|
||||
要成为 PR Wangler，需要参加每周的 SIG Docs 例会，并自愿报名。
|
||||
即使当前这周排班没有轮到你，你仍可以评阅那些尚未被积极评阅的 PRs。
|
||||
|
||||
除了上述的轮值安排，后台机器人也会为基于所影响的文件来为 PR
|
||||
指派评阅人和批准人。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Reviewing a PR
|
||||
Kubernetes documentation follows the [Kubernetes code review process](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process).
|
||||
|
||||
Everything described in [Reviewing a pull request](/docs/contribute/review/reviewing-prs) applies, but Reviewers and Approvers should also do the following:
|
||||
-->
|
||||
## 评阅 PR
|
||||
|
||||
Kubernetes 文档遵循 [Kubernetes 代码评阅流程](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process)。
|
||||
|
||||
[评阅 PR](/zh/docs/contribute/review/reviewing-prs/) 文档中所描述的所有规程都适用，
|
||||
不过评阅人和批准人还要做以下工作：
|
||||
|
||||
<!--
|
||||
- Using the `/assign` Prow command to assign a specific reviewer to a PR as needed. This is extra important
|
||||
when it comes to requesting technical review from code contributors.
|
||||
|
||||
{{< note >}}
|
||||
Look at the `reviewers` field in the front-matter at the top of a Markdown file to see who can
|
||||
provide technical review.
|
||||
{{< /note >}}
|
||||
|
||||
- Making sure the PR follows the [Content](/docs/contribute/style/content-guide/) and [Style](/docs/contribute/style/style-guide/) guides; link the author to the relevant part of the guide(s) if it doesn't.
|
||||
- Using the GitHub **Request Changes** option when applicable to suggest changes to the PR author.
|
||||
- Changing your review status in GitHub using the `/approve` or `/lgtm` Prow commands, if your suggestions are implemented.
|
||||
-->
|
||||
- 根据需要使用 Prow 命令 `/assign` 指派特定的评阅人。如果某个 PR
|
||||
需要来自代码贡献者的技术审核时，这一点非常重要。
|
||||
|
||||
{{< note >}}
|
||||
你可以查看 Markdown 文件的文件头，其中的 `reviewers` 字段给出了哪些人可以为文档提供技术审核。
|
||||
{{< /note >}}
|
||||
|
||||
- 确保 PR 遵从[内容指南](/zh/docs/contribute/style/content-guide/)和[样式指南](/zh/docs/contribute/style/style-guide/)；
|
||||
如果 PR 没有达到要求，指引作者阅读指南中的相关部分。
|
||||
- 适当的时候使用 GitHub **Request Changes** 选项，建议 PR 作者实施所建议的修改。
|
||||
- 当你所提供的建议被采纳后，在 GitHub 中使用 `/approve` 或 `/lgtm` Prow 命令，改变评审状态。
|
||||
|
||||
<!--
|
||||
## Commit into another person's PR
|
||||
|
||||
Leaving PR comments is helpful, but there might be times when you need to commit
|
||||
into another person's PR instead.
|
||||
|
||||
Do not "take over" for another person unless they explicitly ask
|
||||
you to, or you want to resurrect a long-abandoned PR. While it may be faster
|
||||
in the short term, it deprives the person of the chance to contribute.
|
||||
|
||||
The process you use depends on whether you need to edit a file that is already
|
||||
in the scope of the PR, or a file that the PR has not yet touched.
|
||||
-->
|
||||
## 提交到他人的 PR
|
||||
|
||||
为 PR 留下评语是很有用的，不过有时候你需要向他人的 PR 提交内容。
|
||||
|
||||
除非他人明确请求你的帮助或者你希望重启一个被放弃很久的 PR，不要“接手”他人的工作。
|
||||
尽管短期看来这样做可以提高效率，但是也剥夺了他人提交贡献的机会。
|
||||
|
||||
你所要遵循的流程取决于你需要编辑已经在 PR 范畴的文件，还是 PR 尚未触碰的文件。
|
||||
|
||||
<!--
|
||||
You can't commit into someone else's PR if either of the following things is
|
||||
true:
|
||||
|
||||
- If the PR author pushed their branch directly to the
|
||||
[https://github.com/kubernetes/website/](https://github.com/kubernetes/website/)
|
||||
repository. Only a reviewer with push access can commit to another user's PR.
|
||||
|
||||
{{< note >}}
|
||||
Encourage the author to push their branch to their fork before
|
||||
opening the PR next time.
|
||||
{{< /note >}}
|
||||
|
||||
- The PR author explicitly disallows edits from approvers.
|
||||
-->
|
||||
如果处于下列情况之一，你不可以向别人的 PR 提交内容：
|
||||
|
||||
- 如果 PR 作者是直接将自己的分支提交到
|
||||
[https://github.com/kubernetes/website/](https://github.com/kubernetes/website/)
|
||||
仓库。只有具有推送权限的评阅人才可以向他人的 PR 提交内容。
|
||||
|
||||
{{< note >}}
|
||||
我们应鼓励作者下次将分支推送到自己的克隆副本之后再发起 PR。
|
||||
{{< /note >}}
|
||||
|
||||
- PR 作者明确地禁止批准人编辑他/她的 PR。
|
||||
|
||||
<!--
|
||||
## Prow commands for reviewing
|
||||
|
||||
[Prow](https://github.com/kubernetes/test-infra/blob/master/prow/README.md) is
|
||||
the Kubernetes-based CI/CD system that runs jobs against pull requests (PRs). Prow
|
||||
enables chatbot-style commands to handle GitHub actions across the Kubernetes
|
||||
organization, like [adding and removing labels](#adding-and-removing-issue-labels), closing issues, and assigning an approver. Enter Prow commands as GitHub comments using the `/<command-name>` format.
|
||||
|
||||
The most common prow commands reviewers and approvers use are:
|
||||
-->
|
||||
## 评阅用的 Prow 命令
|
||||
|
||||
[Prow](https://github.com/kubernetes/test-infra/blob/master/prow/README.md)
|
||||
是基于 Kubernetes 的 CI/CD 系统，基于拉取请求（PR）的触发运行不同任务。
|
||||
Prow 使得我们可以使用会话机器人一样的命令跨整个 Kubernetes 组织处理 GitHub
|
||||
动作，例如[添加和删除标签](#adding-and-removing-issue-labels)、关闭 Issues
|
||||
以及指派批准人等等。你可以使用 `/<命令名称>` 的形式以 GitHub 评论的方式输入
|
||||
Prow 命令。
|
||||
|
||||
评阅人和批准人最常用的 Prow 命令有：
|
||||
|
||||
<!--
|
||||
{{< table caption="Prow commands for reviewing" >}}
|
||||
Prow Command | Role Restrictions | Description
|
||||
:------------|:------------------|:-----------
|
||||
`/lgtm` | Organization members | Signals that you've finished reviewing a PR and are satisfied with the changes.
|
||||
`/approve` | Approvers | Approves a PR for merging.
|
||||
`/assign` | Reviewers or Approvers | Assigns a person to review or approve a PR
|
||||
`/close` | Reviewers or Approvers | Closes an issue or PR.
|
||||
`/hold` | Anyone | Adds the `do-not-merge/hold` label, indicating the PR cannot be automatically merged.
|
||||
`/hold cancel` | Anyone | Removes the `do-not-merge/hold` label.
|
||||
{{< /table >}}
|
||||
|
||||
See [the Prow command reference](https://prow.k8s.io/command-help) to see the full list
|
||||
of commands you can use in a PR.
|
||||
-->
|
||||
{{< table caption="评阅用 Prow 命令" >}}
|
||||
Prow 命令 | 角色限制 | 描述
|
||||
:------------|:------------------|:-----------
|
||||
`/lgtm` | 组织成员 | 用来表明你已经完成 PR 的评阅并对其所作变更表示满意
|
||||
`/approve` | 批准人 | 批准某 PR 可以合并
|
||||
`/assign` |评阅人或批准人 | 指派某人来评阅或批准某 PR
|
||||
`/close` | 评阅人或批准人 | 关闭 Issue 或 PR
|
||||
`/hold` | 任何人 | 添加 `do-not-merge/hold` 标签，用来表明 PR 不应被自动合并
|
||||
`/hold cancel` | 任何人 | 去掉 `do-not-merge/hold` 标签
|
||||
{{< /table >}}
|
||||
|
||||
请参考 [Prow 命令指南](https://prow.k8s.io/command-help)，了解你可以在 PR
|
||||
中使用的命令的完整列表。
|
||||
|
||||
<!--
|
||||
## Triage and categorize issues
|
||||
|
||||
In general, SIG Docs follows the [Kubernetes issue triage](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md) process and uses the same labels.
|
||||
|
||||
This GitHub Issue [filter](https://github.com/kubernetes/website/issues?q=is%3Aissue+is%3Aopen+-label%3Apriority%2Fbacklog+-label%3Apriority%2Fimportant-longterm+-label%3Apriority%2Fimportant-soon+-label%3Atriage%2Fneeds-information+-label%3Atriage%2Fsupport+sort%3Acreated-asc)
|
||||
finds issues that might need triage.
|
||||
-->
|
||||
## 对 Issue 进行诊断和分类
|
||||
|
||||
一般而言，SIG Docs 遵从 [Kubernetes issue 判定](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md) 流程并使用相同的标签。
|
||||
|
||||
此 GitHub Issue
|
||||
[过滤器](https://github.com/kubernetes/website/issues?q=is%3Aissue+is%3Aopen+-label%3Apriority%2Fbacklog+-label%3Apriority%2Fimportant-longterm+-label%3Apriority%2Fimportant-soon+-label%3Atriage%2Fneeds-information+-label%3Atriage%2Fsupport+sort%3Acreated-asc)
|
||||
可以用来查找需要评判的 Issues。
|
||||
|
||||
<!--
|
||||
### Triaging an issue
|
||||
|
||||
1. Validate the issue
|
||||
- Make sure the issue is about website documentation. Some issues can be closed quickly by
|
||||
answering a question or pointing the reporter to a resource. See the
|
||||
[Support requests or code bug reports](#support-requests-or-code-bug-reports) section for details.
|
||||
- Assess whether the issue has merit.
|
||||
- Add the `triage/needs-information` label if the issue doesn't have enough
|
||||
detail to be actionable or the template is not filled out adequately.
|
||||
- Close the issue if it has both the `lifecycle/stale` and `triage/needs-information` labels.
|
||||
-->
|
||||
|
||||
### 评判 Issue {#triaging-an-issue}
|
||||
|
||||
1. 验证 Issue 的合法性
|
||||
|
||||
- 确保 Issue 是关于网站文档的。某些 Issue 可以通过回答问题或者为报告者提供
|
||||
资源链接来快速关闭。
|
||||
参考[请求支持或代码缺陷报告](#support-requests-or-code-bug-reports)
|
||||
节以了解详细信息。
|
||||
- 评估该 Issue 是否有价值。
|
||||
- 如果 Issue 缺少足够的细节以至于无法采取行动，或者报告者没有通过模版提供
|
||||
足够信息，可以添加 `triage/needs-information` 标签。
|
||||
- 如果 Issue 同时标注了 `lifecycle/stale` 和 `triage/needs-information`
|
||||
标签，可以直接关闭。
|
||||
|
||||
<!--
|
||||
2. Add a priority label (the
|
||||
[Issue Triage Guidelines](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority) define priority labels in detail)
|
||||
|
||||
< table caption="Issue labels" >
|
||||
Label | Description
|
||||
:------------|:------------------
|
||||
`priority/critical-urgent` | Do this right now.
|
||||
`priority/important-soon` | Do this within 3 months.
|
||||
`priority/important-longterm` | Do this within 6 months.
|
||||
`priority/backlog` | Deferrable indefinitely. Do when resources are available.
|
||||
`priority/awaiting-more-evidence` | Placeholder for a potentially good issue so it doesn't get lost.
|
||||
`help` or `good first issue` | Suitable for someone with very little Kubernetes or SIG Docs experience. See [Help Wanted and Good First Issue Labels](https://kubernetes.dev/docs/guide/help-wanted/) for more information.
|
||||
|
||||
At your discretion, take ownership of an issue and submit a PR for it
|
||||
(especially if it's quick or relates to work you're already doing).
|
||||
|
||||
If you have questions about triaging an issue, ask in `#sig-docs` on Slack or
|
||||
the [kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
-->
|
||||
2. 添加优先级标签（
|
||||
[Issue 判定指南](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority)中有优先级标签的详细定义)
|
||||
|
||||
{{< table caption="Issue 标签" >}}
|
||||
标签 | 描述
|
||||
:------------|:------------------
|
||||
`priority/critical-urgent` | 应马上处理
|
||||
`priority/important-soon` | 应在 3 个月内处理
|
||||
`priority/important-longterm` | 应在 6 个月内处理
|
||||
`priority/backlog` | 可无限期地推迟，可在人手充足时处理
|
||||
`priority/awaiting-more-evidence` | 占位符，标示 Issue 可能是一个不错的 Issue，避免该 Issue 被忽略或遗忘
|
||||
`help` or `good first issue` | 适合对 Kubernetes 或 SIG Docs 经验较少的贡献者来处理。更多信息可参考[需要帮助和入门候选 Issue 标签](https://kubernetes.dev/docs/guide/help-wanted/)。
|
||||
{{< /table >}}
|
||||
|
||||
基于你自己的判断，你可以选择某 Issue 来处理，为之发起 PR
|
||||
（尤其是那些可以很快处理或与你已经在做的工作相关的 Issue）。
|
||||
|
||||
如果你对 Issue 评判有任何问题，可以在 `#sig-docs` Slack 频道或者
|
||||
[kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
|
||||
中提问。
|
||||
|
||||
<!--
|
||||
## Adding and removing issue labels
|
||||
|
||||
To add a label, leave a comment in one of the following formats:
|
||||
|
||||
- `/<label-to-add>` (for example, `/good-first-issue`)
|
||||
- `/<label-category> <label-to-add>` (for example, `/triage needs-information` or `/language ja`)
|
||||
|
||||
To remove a label, leave a comment in one of the following formats:
|
||||
|
||||
- `/remove-<label-to-remove>` (for example, `/remove-help`)
|
||||
- `/remove-<label-category> <label-to-remove>` (for example, `/remove-triage needs-information`)`
|
||||
-->
|
||||
## 添加和删除 Issue 标签 {#adding-and-removing-issue-labels}
|
||||
|
||||
要添加标签，可以用以下形式对 PR 进行评论：
|
||||
|
||||
- `/<要添加的标签>` （例如, `/good-first-issue`）
|
||||
- `/<标签类别> <要添加的标签>` （例如，`/triage needs-information` 或 `/language ja`）
|
||||
|
||||
要移除某个标签，可以用以下形式对 PR 进行评论：
|
||||
|
||||
- `/remove-<要移除的标签>` （例如，`/remove-help`）
|
||||
- `/remove-<标签类别> <要移除的标签>` （例如，`/remove-triage needs-information`）
|
||||
|
||||
<!--
|
||||
In both cases, the label must already exist. If you try to add a label that does not exist, the command is
|
||||
silently ignored.
|
||||
|
||||
For a list of all labels, see the [website repository's Labels section](https://github.com/kubernetes/website/labels). Not all labels are used by SIG Docs.
|
||||
-->
|
||||
在以上两种情况下，标签都必须合法存在。如果你尝试添加一个尚不存在的标签，
|
||||
对应的命令会被悄悄忽略。
|
||||
|
||||
关于所有标签的完整列表，可以参考
|
||||
[Website 仓库的标签节](https://github.com/kubernetes/website/labels)。
|
||||
实际上，SIG Docs 并没有使用全部标签。
|
||||
|
||||
<!--
|
||||
### Issue lifecycle labels
|
||||
|
||||
Issues are generally opened and closed quickly.
|
||||
However, sometimes an issue is inactive after its opened.
|
||||
Other times, an issue may need to remain open for longer than 90 days.
|
||||
|
||||
{{< table caption="Issue lifecycle labels" >}}
|
||||
Label | Description
|
||||
:------------|:------------------
|
||||
`lifecycle/stale` | After 90 days with no activity, an issue is automatically labeled as stale. The issue will be automatically closed if the lifecycle is not manually reverted using the `/remove-lifecycle stale` command.
|
||||
`lifecycle/frozen` | An issue with this label will not become stale after 90 days of inactivity. A user manually adds this label to issues that need to remain open for much longer than 90 days, such as those with a `priority/important-longterm` label.
|
||||
{{< /table >}}
|
||||
-->
|
||||
### Issue 生命周期标签
|
||||
|
||||
Issues 通常都可以快速创建并关闭。
|
||||
不过也有些时候，某个 Issue 被创建之后会长期处于非活跃状态。
|
||||
也有一些时候，即使超过 90 天，某个 Issue 仍应保持打开状态。
|
||||
|
||||
{{< table caption="Issue 生命周期标签" >}}
|
||||
标签 | 描述
|
||||
:------------|:------------------
|
||||
`lifecycle/stale` | 过去 90 天内某 Issue 无人问津，会被自动标记为停滞状态。如果 Issue 没有被 `/remove-lifecycle stale` 命令重置生命期，就会被自动关闭。
|
||||
`lifecycle/frozen` | 对应的 Issue 即使超过 90 天仍无人处理也不会进入停滞状态。用户手动添加此标签给一些需要保持打开状态超过 90 天的 Issue，例如那些带有 `priority/important-longterm` 标签的 Issue。
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
## Handling special issue types
|
||||
|
||||
SIG Docs encounters the following types of issues often enough to document how
|
||||
to handle them.
|
||||
|
||||
### Duplicate issues
|
||||
|
||||
If a single problem has one or more issues open for it, combine them into a single issue.
|
||||
You should decide which issue to keep open (or
|
||||
open a new issue), then move over all relevant information and link related issues.
|
||||
Finally, label all other issues that describe the same problem with
|
||||
`triage/duplicate` and close them. Only having a single issue to work on reduces confusion
|
||||
and avoids duplicate work on the same problem.
|
||||
-->
|
||||
## 处理特殊的 Issue 类型 {#handling-special-issue-types}
|
||||
|
||||
SIG Docs 常常会遇到以下类型的 Issue，因此对其处理方式描述如下。
|
||||
|
||||
### 重复的 Issue {#duplicate-issues}
|
||||
|
||||
如果针对同一个问题有不止一个打开的 Issue，可以将其合并为一个 Issue。
|
||||
你需要决定保留哪个 Issue 为打开状态（或者重新登记一个新的 Issue），
|
||||
然后将所有相关的信息复制过去并提供对关联 Issues 的链接。
|
||||
最后，将所有其他描述同一问题的 Issue 标记为 `triage/duplicate` 并关闭之。
|
||||
保持只有一个 Issue 待处理有助于减少困惑，避免在同一问题上发生重复劳动。
|
||||
|
||||
<!--
|
||||
### Dead link issues
|
||||
|
||||
If the dead link issue is in the API or `kubectl` documentation, assign them `/priority critical-urgent` until the problem is fully understood. Assign all other dead link issues `/priority important-longterm`, as they must be manually fixed.
|
||||
|
||||
### Blog issues
|
||||
|
||||
We expect [Kubernetes Blog](https://kubernetes.io/blog/) entries to become
|
||||
outdated over time. Therefore, we only maintain blog entries less than a year old.
|
||||
If an issue is related to a blog entry that is more than one year old,
|
||||
close the issue without fixing.
|
||||
-->
|
||||
### 失效链接 Issues {#dead-link-issues}
|
||||
|
||||
如果失效链接是关于 API 或者 `kubectl` 文档的，可以将其标记为
|
||||
`/priority critical-urgent`，直到问题原因被弄清楚为止。
|
||||
对于其他的链接失效问题，可以标记 `/priority important-longterm`，
|
||||
因为这些问题都需要手动处理。
|
||||
|
||||
### 博客问题 {#blog-issues}
|
||||
|
||||
我们预期 [Kubernetes 博客](https://kubernetes.io/blog/)条目随着时间推移都会过期。
|
||||
因此，我们只维护一年内的博客条目。
|
||||
如果某个 Issue 是与某个超过一年的博客条目有关的，可以直接关闭
|
||||
Issue，不必修复。
|
||||
|
||||
<!--
|
||||
### Support requests or code bug reports
|
||||
|
||||
Some docs issues are actually issues with the underlying code, or requests for
|
||||
assistance when something, for example a tutorial, doesn't work.
|
||||
For issues unrelated to docs, close the issue with the `kind/support` label and a comment
|
||||
directing the requester to support venues (Slack, Stack Overflow) and, if
|
||||
relevant, the repository to file an issue for bugs with features (`kubernetes/kubernetes`
|
||||
is a great place to start).
|
||||
|
||||
Sample response to a request for support:
|
||||
-->
|
||||
### 请求支持或代码缺陷报告 {#support-requests-or-code-bug-reports}
|
||||
|
||||
某些文档 Issues 实际上是关于底层代码的 Issue 或者在某方面请求协助的问题，
|
||||
例如某个教程无法正常工作。
|
||||
对于与文档无关的 Issues，关闭它并打上标签 `kind/support`，可以通过评论
|
||||
告知请求者其他支持渠道（Slack、Stack Overflow）。
|
||||
如果有相关的其他仓库，可以告诉请求者应该在哪个仓库登记与功能特性相关的 Issues
|
||||
（通常会是 `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](https://slack.k8s.io/). You can also search
|
||||
resources like
|
||||
[Stack Overflow](https://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.
|
||||
```
|
||||
|
||||
<!--
|
||||
Sample code bug report response:
|
||||
-->
|
||||
对代码缺陷 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.
|
||||
```
|
||||
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: 评审 PR
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 10
|
||||
---
|
||||
<!--
|
||||
title: Reviewing pull requests
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 10
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
Anyone can review a documentation pull request. Visit the [pull requests](https://github.com/kubernetes/website/pulls) section in the Kubernetes website repository to see open pull requests.
|
||||
|
||||
Reviewing documentation pull requests is a
|
||||
great way to introduce yourself to the Kubernetes community.
|
||||
It helps you learn the code base and build trust with other contributors.
|
||||
|
||||
Before reviewing, it's a good idea to:
|
||||
|
||||
- Read the [content guide](/docs/contribute/style/content-guide/) and
|
||||
[style guide](/docs/contribute/style/style-guide/) so you can leave informed comments.
|
||||
- Understand the different [roles and responsibilities](/docs/contribute/participating/#roles-and-responsibilities) in the Kubernetes documentation community.
|
||||
-->
|
||||
任何人均可评审文档的拉取请求。
|
||||
访问 Kubernetes 网站仓库的 [pull requests](https://github.com/kubernetes/website/pulls) 部分，
|
||||
可以查看所有待处理的拉取请求（PR）。
|
||||
|
||||
评审文档 PR 是将你自己介绍给 Kubernetes 社区的一种很好的方式。
|
||||
它将有助于你学习代码库并与其他贡献者之间建立相互信任关系。
|
||||
|
||||
在评审之前，可以考虑：
|
||||
|
||||
- 阅读[内容指南](/zh/docs/contribute/style/content-guide/)和
|
||||
[样式指南](/zh/docs/contribute/style/style-guide/)以便给出有价值的评论。
|
||||
- 了解 Kubernetes 文档社区中不同的[角色和职责](/zh/docs/contribute/participate/roles-and-responsibilities/)。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Before you begin
|
||||
|
||||
Before you start a review:
|
||||
|
||||
- Read the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and ensure that you abide by it at all times.
|
||||
- Be polite, considerate, and helpful.
|
||||
- Comment on positive aspects of PRs as well as changes.
|
||||
- Be empathetic and mindful of how your review may be received.
|
||||
- Assume good intent and ask clarifying questions.
|
||||
- Experienced contributors, consider pairing with new contributors whose work requires extensive changes.
|
||||
-->
|
||||
## 准备工作 {#before-you-begin}
|
||||
|
||||
在你开始评审之前：
|
||||
|
||||
- 阅读 [CNCF 行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)。
|
||||
确保你会始终遵从其中约定。
|
||||
- 保持有礼貌、体谅他人，怀助人为乐初心。
|
||||
- 评论时若给出修改建议，也要兼顾 PR 的积极方面。
|
||||
- 保持同理心，多考虑他人收到评审意见时的可能反应。
|
||||
- 假定大家都是好意的，通过问问题澄清意图。
|
||||
- 如果你是有经验的贡献者，请考虑和新贡献者一起合作，提高其产出质量。
|
||||
|
||||
<!--
|
||||
## Review process
|
||||
|
||||
In general, review pull requests for content and style in English. Figure 1 outlines the steps for the review process. The details for each step follow.
|
||||
-->
|
||||
## 评审过程 {#review-process}
|
||||
|
||||
一般而言，应该使用英语来评审 PR 的内容和样式。
|
||||
图 1 概述了评审流程的各个步骤。
|
||||
每个步骤的详细信息如下。
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph fourth[开始评审]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
M[添加评论] --> N[评审变更]
|
||||
N --> O[新手应该<br>选择 Comment]
|
||||
end
|
||||
subgraph third[选择 PR]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
J[阅读描述<br>和评论]--> K[通过 Netlify 预览构建<br>来预览变更]
|
||||
end
|
||||
|
||||
A[查阅待处理的 PR 清单]--> B[通过标签过滤<br>待处理的 PR]
|
||||
B --> third --> fourth
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,J,K,M,N,O grey
|
||||
class S,T spacewhite
|
||||
class third,fourth white
|
||||
{{</ mermaid >}}
|
||||
|
||||
<!--
|
||||
Figure 1. Review process steps.
|
||||
-->
|
||||
图 1. 评审流程步骤。
|
||||
|
||||
<!--
|
||||
1. Go to
|
||||
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
|
||||
You see a list of every open pull request against the Kubernetes website and
|
||||
docs.
|
||||
|
||||
2. Filter the open PRs using one or all of the following labels:
|
||||
- `cncf-cla: yes` (Recommended): PRs submitted by contributors who have not signed the CLA cannot be merged. See [Sign the CLA](/docs/contribute/new-content/overview/#sign-the-cla) for more information.
|
||||
- `language/en` (Recommended): Filters for english language PRs only.
|
||||
- `size/<size>`: filters for PRs of a certain size. If you're new, start with smaller PRs.
|
||||
|
||||
Additionally, ensure the PR isn't marked as a work in progress. PRs using the `work in progress` label are not ready for review yet.
|
||||
-->
|
||||
1. 前往 [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls)，
|
||||
你会看到所有针对 Kubernetes 网站和文档的待处理 PR。
|
||||
|
||||
2. 使用以下标签（组合）对待处理 PR 进行过滤：
|
||||
|
||||
- `cncf-cla: yes` （建议）：由尚未签署 CLA 的贡献者所发起的 PR 不可以合并。
|
||||
参考[签署 CLA](/zh/docs/contribute/new-content/overview/#sign-the-cla) 以了解更多信息。
|
||||
- `language/en` （建议）：仅查看英语语言的 PR。
|
||||
- `size/<尺寸>`：过滤特定尺寸（规模）的 PR。
|
||||
如果你刚入门，可以从较小的 PR 开始。
|
||||
|
||||
此外，确保 PR 没有标记为尚未完成（Work in Progress）。
|
||||
包含 `work in progress` 的 PR 通常还没准备好被评审。
|
||||
|
||||
<!--
|
||||
3. Once you've selected a PR to review, understand the change by:
|
||||
- Reading the PR description to understand the changes made, and read any linked issues
|
||||
- Reading any comments by other reviewers
|
||||
- Clicking the **Files changed** tab to see the files and lines changed
|
||||
- Previewing the changes in the Netlify preview build by scrolling to the PR's build check section at the bottom of the **Conversation** tab.
|
||||
Here's a screenshot (this shows GitHub's desktop site; if you're reviewing
|
||||
on a tablet or smartphone device, the GitHub web UI is slightly different):
|
||||
{{< figure src="/images/docs/github_netlify_deploy_preview.png" alt="GitHub pull request details including link to Netlify preview" >}}
|
||||
To open the preview, click on the **Details** link of the **deploy/netlify** line in the list of checks.
|
||||
-->
|
||||
3. 选定 PR 评审之后，可以通过以下方式理解所作的变更：
|
||||
|
||||
- 阅读 PR 描述以理解所作变更，并且阅读所有关联的 Issues。
|
||||
- 阅读其他评审人给出的评论。
|
||||
- 点击 **Files changed** Tab 页面，查看被改变的文件和代码行。
|
||||
- 滚动到 **Conversation** Tab 页面下端的 PR 构建检查节区，
|
||||
预览 Netlify 预览构建中的变更。
|
||||
以下是一个屏幕截图（这显示了 GitHub 的桌面版外观；
|
||||
如果你在平板电脑或智能手机设备上进行评审，
|
||||
GitHub 的 Web UI 会略有不同）：
|
||||
{{< figure src="/images/docs/github_netlify_deploy_preview.png" alt="GitHub PR 详细信息，包括 Netlify 预览链接" >}}
|
||||
要打开预览，请点击 **deploy/netlify** 行的 **Details** 链接。
|
||||
|
||||
<!--
|
||||
4. Go to the **Files changed** tab to start your review.
|
||||
1. Click on the `+` symbol beside the line you want to comment on.
|
||||
2. Fill in any comments you have about the line and click either **Add single comment** (if you have only one comment to make) or **Start a review** (if you have multiple comments to make).
|
||||
3. When finished, click **Review changes** at the top of the page. Here, you can add
|
||||
a summary of your review (and leave some positive comments for the contributor!),
|
||||
approve the PR, comment or request changes as needed. New contributors should always
|
||||
choose **Comment**.
|
||||
-->
|
||||
4. 前往 **Files changed** Tab 页面，开始你的评审工作。
|
||||
|
||||
1. 点击你希望评论的行旁边的 `+` 号。
|
||||
2. 填写你对该行的评论，
|
||||
之后选择 **Add single comment**（如果你只有一条评论）
|
||||
或者 **Start a review**（如果你还有其他评论要添加）。
|
||||
3. 评论结束时，点击页面顶部的 **Review changes**。
|
||||
这里你可以添加你的评论结语（记得留下一些正能量的评论！）、
|
||||
根据需要批准 PR、请求作者进一步修改等等。
|
||||
新手应该选择 **Comment**。
|
||||
|
||||
<!--
|
||||
## Reviewing checklist
|
||||
|
||||
When reviewing, use the following as a starting point.
|
||||
-->
|
||||
## 评审清单 {#reviewing-checklist}
|
||||
|
||||
评审 PR 时可以从下面的条目入手。
|
||||
|
||||
<!--
|
||||
### Language and grammar
|
||||
|
||||
- Are there any obvious errors in language or grammar? Is there a better way to phrase something?
|
||||
- Are there any complicated or archaic words which could be replaced with a simpler word?
|
||||
- Are there any words, terms or phrases in use which could be replaced with a non-discriminatory alternative?
|
||||
- Does the word choice and its capitalization follow the [style guide](/docs/contribute/style/style-guide/)?
|
||||
- Are there long sentences which could be shorter or less complex?
|
||||
- Are there any long paragraphs which might work better as a list or table?
|
||||
-->
|
||||
### 语言和语法 {#language-and-grammar}
|
||||
|
||||
- 是否存在明显的语言或语法错误？对某事的描述有更好的方式？
|
||||
- 是否存在一些过于复杂晦涩的用词，本可以用简单词汇来代替？
|
||||
- 是否有些用词、术语或短语可以用不带歧视性的表达方式代替？
|
||||
- 用词和大小写方面是否遵从了[样式指南](/zh/docs/contribute/style/style-guide/)？
|
||||
- 是否有些句子太长，可以改得更短、更简单？
|
||||
- 是否某些段落过长，可以考虑使用列表或者表格来表达？
|
||||
|
||||
<!--
|
||||
### Content
|
||||
|
||||
- Does similar content exist elsewhere on the Kubernetes site?
|
||||
- Does the content excessively link to off-site, individual vendor or non-open source documentation?
|
||||
-->
|
||||
### 内容 {#content}
|
||||
|
||||
- Kubernetes 网站上是否别处已经存在类似的内容？
|
||||
- 内容本身是否过度依赖于网站范畴之外、独立供应商或者非开源的文档？
|
||||
|
||||
<!--
|
||||
### Website
|
||||
|
||||
- Did this PR change or remove a page title, slug/alias or anchor link? If so, are there broken links as a result of this PR? Is there another option, like changing the page title without changing the slug?
|
||||
- Does the PR introduce a new page? If so:
|
||||
- Is the page using the right [page content type](/docs/contribute/style/page-content-types/) and associated Hugo shortcodes?
|
||||
- Does the page appear correctly in the section's side navigation (or at all)?
|
||||
- Should the page appear on the [Docs Home](/docs/home/) listing?
|
||||
- Do the changes show up in the Netlify preview? Be particularly vigilant about lists, code blocks, tables, notes and images.
|
||||
-->
|
||||
### 网站 {#Website}
|
||||
|
||||
- PR 是否改变或者删除了某页面的标题、slug/别名或者链接锚点？
|
||||
如果是这样，PR 是否会导致出现新的失效链接？
|
||||
是否有其他的办法，比如改变页面标题但不改变其 slug？
|
||||
- PR 是否引入新的页面？如果是：
|
||||
- 该页面是否使用了正确的[页面内容类型](/zh/docs/contribute/style/page-content-types/)
|
||||
及相关联的 Hugo 短代码（shortcodes）？
|
||||
- 该页面能否在对应章节的侧面导航中显示？显示得正确么？
|
||||
- 该页面是否应出现在[网站主页面](/zh/docs/home/)的列表中？
|
||||
- 变更是否正确出现在 Netlify 预览中了？
|
||||
要对列表、代码段、表格、注释和图像等元素格外留心。
|
||||
|
||||
<!--
|
||||
### Other
|
||||
|
||||
For small issues with a PR, like typos or whitespace, prefix your comments with `nit:`. This lets the author know the issue is non-critical.
|
||||
-->
|
||||
### 其他 {#other}
|
||||
|
||||
对于 PR 中的小问题，例如拼写错误或者空格问题，
|
||||
可以在你的评论前面加上 `nit:`。
|
||||
这样做可以让作者知道该问题不是一个不得了的大问题。
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: 文档样式概述
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
|
||||
<!--
|
||||
title: Documentation style overview
|
||||
main_menu: true
|
||||
weight: 80
|
||||
-->
|
||||
|
||||
<!--
|
||||
The topics in this section provide guidance on writing style, content formatting
|
||||
and organization, and using Hugo customizations specific to Kubernetes
|
||||
documentation.
|
||||
-->
|
||||
本节的主题是提供有关写作风格、内容格式和组织以及如何使用
|
||||
特定于 Kubernetes 文档的 Hugo 定制代码的指导。
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: 文档内容指南
|
||||
linktitle: 内容指南
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
<!--
|
||||
title: Documentation Content Guide
|
||||
linktitle: Content guide
|
||||
content_type: concept
|
||||
weight: 10
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
This page contains guidelines for Kubernetes documentation.
|
||||
|
||||
If you have questions about what's allowed, join the #sig-docs channel in
|
||||
[Kubernetes Slack](https://slack.k8s.io/) and ask!
|
||||
|
||||
You can register for Kubernetes Slack at https://slack.k8s.io/.
|
||||
|
||||
For information on creating new content for the Kubernetes
|
||||
docs, follow the [style guide](/docs/contribute/style/style-guide).
|
||||
-->
|
||||
本页包含 Kubernetes 文档的一些指南。
|
||||
|
||||
如果你不清楚哪些事情是可以做的，请加入到
|
||||
[Kubernetes Slack](https://slack.k8s.io/) 的 `#sig-docs` 频道提问！
|
||||
你可以在 https://slack.k8s.io 注册到 Kubernetes Slack。
|
||||
|
||||
关于为 Kubernetes 文档创建新内容的更多信息，可参考
|
||||
[样式指南](/zh/docs/contribute/style/style-guide)。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Overview
|
||||
|
||||
Source for the Kubernetes website, including the docs, resides in the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
|
||||
Located in the `kubernetes/website/content/<language_code>/docs` folder, the
|
||||
majority of Kubernetes documentation is specific to the [Kubernetes
|
||||
project](https://github.com/kubernetes/kubernetes).
|
||||
|
||||
## What's allowed
|
||||
|
||||
Kubernetes docs allow content for third-party projects only when:
|
||||
|
||||
- Content documents software in the Kubernetes project
|
||||
- Content documents software that's out of project but necessary for Kubernetes to function
|
||||
- Content is canonical on kubernetes.io, or links to canonical content elsewhere
|
||||
-->
|
||||
## 概述 {#overview}
|
||||
|
||||
Kubernetes 网站（包括其文档）源代码位于
|
||||
[kubernetes/website](https://github.com/kubernetes/website) 仓库中。
|
||||
|
||||
在 `kubernetes/website/content/<语言代码>/docs` 目录下, 绝大多数 Kubernetes
|
||||
文档都是特定于 [Kubernetes 项目](https://github.com/kubernetes/kubernetes)的。
|
||||
|
||||
## 可以发布的内容 {#what-s-allowed}
|
||||
|
||||
只有当以下条件满足时，Kubernetes 文档才允许第三方项目的内容：
|
||||
|
||||
- 内容所描述的软件在 Kubernetes 项目内
|
||||
- 内容所描述的软件不在 Kubernetes 项目内，却是让 Kubernetes 正常工作所必需的
|
||||
- 内容是被 kubernetes.io 域名收编的，或者是其他位置的标准典型内容
|
||||
|
||||
<!--
|
||||
### Third party content
|
||||
|
||||
Kubernetes documentation includes applied examples of projects in the Kubernetes project—projects that live in the [kubernetes](https://github.com/kubernetes) and
|
||||
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations.
|
||||
|
||||
Links to active content in the Kubernetes project are always allowed.
|
||||
|
||||
Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker),
|
||||
[networking policy](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) (CNI plugins), [Ingress controllers](/docs/concepts/services-networking/ingress-controllers/), and [logging](/docs/concepts/cluster-administration/logging/).
|
||||
|
||||
Docs can link to third-party open source software (OSS) outside the Kubernetes project only if it's necessary for Kubernetes to function.
|
||||
-->
|
||||
### 第三方内容 {#third-party-content}
|
||||
|
||||
Kubernetes 文档包含 Kubernetes 项目下的多个项目的应用示例。
|
||||
这里的 Kubernetes 项目指的是 [kubernetes](https://github.com/kubernetes) 和
|
||||
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub 组织
|
||||
下的项目。
|
||||
|
||||
链接到 Kubernetes 项目中活跃的内容是一直允许的。
|
||||
|
||||
Kubernetes 需要某些第三方内容才能正常工作。例如
|
||||
容器运行时（containerd、CRI-O、Docker），
|
||||
[联网策略](/zh/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/)
|
||||
（CNI 插件），[Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers/)
|
||||
以及[日志](/zh/docs/concepts/cluster-administration/logging/)等。
|
||||
|
||||
只有对应的第三方开源软件（OSS）是运行 Kubernetes 所必需的，才可以在文档中包含
|
||||
指向这些 Kubernetes 项目之外的软件的链接。
|
||||
|
||||
<!--
|
||||
### Dual sourced content
|
||||
|
||||
Wherever possible, Kubernetes docs link to canonical sources instead of hosting
|
||||
dual-sourced content.
|
||||
|
||||
Dual-sourced content requires double the effort (or more!) to maintain
|
||||
and grows stale more quickly.
|
||||
|
||||
{{< note >}}
|
||||
|
||||
If you're a maintainer for a Kubernetes project and need help hosting your own docs,
|
||||
ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/).
|
||||
{{< /note >}}
|
||||
-->
|
||||
### 双重来源的内容 {#dual-sourced-content}
|
||||
|
||||
只要有可能，Kubernetes 文档应该指向标准典型的信息源而不是直接托管多重来源的内容。
|
||||
|
||||
双重来源的内容需要双倍（甚至更多）的投入才能维护，而且通常很快就会变得停滞不前。
|
||||
|
||||
{{< note >}}
|
||||
如果你是一个 Kubernetes 项目的维护者，需要帮忙托管你的文档，
|
||||
请在 Kubernetes 的 [#sig-docs 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)
|
||||
提出请求。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### More information
|
||||
|
||||
If you have questions about allowed content, join the [Kubernetes Slack](https://slack.k8s.io/) #sig-docs channel and ask!
|
||||
-->
|
||||
### 更多信息 {#more-information}
|
||||
|
||||
如果你对允许出现的内容有疑问，请加入到 [Kubernetes Slack](https://slack.k8s.io/)
|
||||
的 `#sig-docs` 频道提问！
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* 阅读[样式指南](/zh/docs/contribute/style/style-guide)。
|
||||
@@ -0,0 +1,228 @@
|
||||
---
|
||||
title: 内容组织
|
||||
content_type: concept
|
||||
weight: 40
|
||||
---
|
||||
<!--
|
||||
title: Content organization
|
||||
content_type: concept
|
||||
weight: 40
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This site uses Hugo. In Hugo, [content
|
||||
organization](https://gohugo.io/content-management/organization/) is a core
|
||||
concept.
|
||||
-->
|
||||
本网站使用了 Hugo。在 Hugo 中，[内容组织](https://gohugo.io/content-management/organization/) 是一个核心概念。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
**Hugo Tip:** Start Hugo with `hugo server -navigateToChanged` for content edit-sessions.
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
**Hugo 提示：** 用 `hugo server --navigateToChanged` 命令启动 Hugo 以进行内容编辑会话。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Page Lists
|
||||
|
||||
### Page Order
|
||||
|
||||
The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first), and finally by the link title.
|
||||
|
||||
Given that, if you want to move a page or a section up, set a weight in the page's front matter:
|
||||
-->
|
||||
|
||||
## 页面列表
|
||||
|
||||
### 页面顺序
|
||||
|
||||
文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出。Hugo 会按照权重（从 1 开始）、
|
||||
日期（最新的排最前面）排序，最后按链接标题排序。
|
||||
|
||||
有鉴于此，如果你想将一个页面或一个章节前移，请在页面头部设置一个较高的权重：
|
||||
|
||||
```yaml
|
||||
title: My Page
|
||||
weight: 10
|
||||
```
|
||||
|
||||
<!--
|
||||
For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
|
||||
-->
|
||||
{{< note >}}
|
||||
对于页面的权重，不建议使用连续的数值，比如1、2、3...，而应采用间隔的数值，比如10、20、30...
|
||||
这样将来你可以将其他页面插入到想要的位置。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Documentation Main Menu
|
||||
|
||||
The `Documentation` main menu is built from the sections below `docs/` with the `main_menu` flag set in front matter of the `_index.md` section content file:
|
||||
-->
|
||||
### 文档主菜单
|
||||
|
||||
`文档` 主菜单是从 `docs/` 下面的章节构建的。
|
||||
这些章节在其章节内容文件 `_index.md` 的头部设置了 `main_menu` 标志：
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
```
|
||||
|
||||
<!--
|
||||
Note that the link title is fetched from the page's `linkTitle`, so if you want it to be something different than the title, change it in the content file:
|
||||
-->
|
||||
注意，链接标题来自页面的 `linkTitle` 字段，因此如果希望它与页面标题不同，请在内容文件中更改它：
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
title: Page Title
|
||||
linkTitle: Title used in links
|
||||
```
|
||||
|
||||
<!--
|
||||
The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
以上操作需要为每种语言分别完成。如果在菜单中没有看到你的章节，这可能是因为它没有被 Hugo 识别为一个章节。
|
||||
请在章节对应的目录下创建 `_index.md` 内容文件。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Documentation Side Menu
|
||||
|
||||
The documentation side-bar menu is built from the _current section tree_ starting below `docs/`.
|
||||
|
||||
It will show all sections and their pages.
|
||||
|
||||
If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter:
|
||||
|
||||
When you navigate to a section that has content, the specific section or page (e.g. `_index.md`) is shown. Else, the first page inside that section is shown.
|
||||
-->
|
||||
### 文档侧方菜单
|
||||
|
||||
文档侧方菜单是基于 `docs/` 下面的 _当前章节的内容树_ 构建的。
|
||||
|
||||
菜单默认显示所有的章节和它们的页面。
|
||||
|
||||
如果你不想列出某个章节或页面，请在页面头部将 `toc_hide` 标志设置为 `true`。
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
当导航到具有内容的章节时，网站将显示出指定的章节或页面（例如 `_index.md`）。
|
||||
否则，将显示该章节里的第一个页面。
|
||||
|
||||
<!--
|
||||
### Documentation Browser
|
||||
|
||||
The page browser on the documentation home page is built using all the sections and pages that are directly below the `docs section`.
|
||||
|
||||
If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter:
|
||||
-->
|
||||
### 文档浏览器 {#documentation-browser}
|
||||
|
||||
文档主页上的页面浏览器是基于 `docs section` 下一层的所有章节和页面构建的。
|
||||
|
||||
如果你不想列出某个章节或页面，请在页面头部将 `toc_hide` 标志设置为 `true`。
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
<!--
|
||||
### The Main Menu
|
||||
|
||||
The site links in the top-right menu -- and also in the footer -- are built by page-lookups. This is to make sure that the page actually exists. So, if the `case-studies` section does not exist in a site (language), it will not be linked to.
|
||||
-->
|
||||
### 主菜单
|
||||
|
||||
右上菜单中的网站链接（也出现在页脚中）是通过页面查找构建的。
|
||||
这是为了确保页面实际存在。因此，如果 `case-studies` 章节在网站（或者其本地化版本）中不存在，
|
||||
则不会出现对应的链接。
|
||||
|
||||
<!--
|
||||
## Page Bundles
|
||||
|
||||
In addition to standalone content pages (Markdown files), Hugo supports [Page Bundles](https://gohugo.io/content-management/page-bundles/).
|
||||
|
||||
One example is [Custom Hugo Shortcodes](/docs/contribute/style/hugo-shortcodes/). It is considered a `leaf bundle`. Everything below the directory, including the `index.md`, will be part of the bundle. This also includes page-relative links, images that can be processed etc.:
|
||||
-->
|
||||
## 页面包
|
||||
|
||||
除了独立的内容页面（Markdown 文件），Hugo 还支持
|
||||
[页面包](https://gohugo.io/content-management/page-bundles/)。
|
||||
|
||||
一个例子是[定制的 Hugo 短代码（shortcodes）](/zh/docs/contribute/style/hugo-shortcodes/)。
|
||||
它被认为是 `leaf bundle`（叶子包）。
|
||||
目录下的所有内容，包括 `index.md`，都是包的一部分。此外还包括页面间相对链接、可被处理的图像等：
|
||||
|
||||
```bash
|
||||
en/docs/home/contribute/includes
|
||||
├── example1.md
|
||||
├── example2.md
|
||||
├── index.md
|
||||
└── podtemplate.json
|
||||
```
|
||||
|
||||
<!--
|
||||
Another widely used example is the `includes` bundle. It sets `headless: true` in front matter, which means that it does not get its own URL. It is only used in other pages.
|
||||
-->
|
||||
另一个广泛使用的例子是 `includes` 包。
|
||||
这类包在页面头部设置 `headless: true`，意味着它没有得到自己的 URL。它只用于其他页面。
|
||||
|
||||
```bash
|
||||
en/includes
|
||||
├── default-storage-class-prereqs.md
|
||||
├── index.md
|
||||
├── partner-script.js
|
||||
├── partner-style.css
|
||||
├── task-tutorial-prereqs.md
|
||||
├── user-guide-content-moved.md
|
||||
└── user-guide-migration-notice.md
|
||||
```
|
||||
|
||||
<!--
|
||||
Some important notes to the files in the bundles:
|
||||
|
||||
* For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
|
||||
* All the files in a bundle are what Hugo calls `Resources` and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See [Page Resources Metadata](https://gohugo.io/content-management/page-resources/#page-resources-metadata).
|
||||
* The value you get from `.RelPermalink` of a `Resource` is page-relative. See [Permalinks](https://gohugo.io/content-management/urls/#permalinks).
|
||||
-->
|
||||
有关包中文件的一些重要说明：
|
||||
|
||||
* 已翻译的包会从上面的语言继承所有缺失的、非内容文件。这一设计可以避免重复。
|
||||
* 包中的所有文件都是 Hugo 所指的 `Resources`，你可以为用不同语言为其提供元数据，
|
||||
例如参数和标题，即使它不支持头部设置（YAML 文件等）。
|
||||
参见[页面资源元数据](https://gohugo.io/content-management/page-resources/#page-resources-metadata)。
|
||||
* 从 `Resource` 的 `.RelPermalink` 中获得的值是相对于当前页面的。
|
||||
参见 [Permalinks](https://gohugo.io/content-management/urls/#permalinks)。
|
||||
|
||||
<!--
|
||||
## Styles
|
||||
|
||||
The `SASS` source of the stylesheets for this site is stored below `src/sass` and can be built with `make sass` (note that Hugo will get `SASS` support soon, see https://github.com/gohugoio/hugo/issues/4243).
|
||||
-->
|
||||
## 样式 {#styles}
|
||||
|
||||
网站的样式表的 `SASS` 源文件存储在 `src/sass` 下面，可以用 `make sass` 构建
|
||||
（Hugo 很快就提供 `SASS` 的支持，参见 https://github.com/gohugoio/hugo/issues/4243）。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* Learn about [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/)
|
||||
* Learn about the [Style guide](/docs/contribute/style/style-guide)
|
||||
* Learn about the [Content guide](/docs/contribute/style/content-guide)
|
||||
-->
|
||||
|
||||
* 了解[定制 Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/)
|
||||
* 了解[样式指南](/zh/docs/contribute/style/style-guide)
|
||||
* 了解[内容指南](/zh/docs/contribute/style/content-guide)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: 例子 #1
|
||||
---
|
||||
|
||||
<!--
|
||||
title: Example #1
|
||||
-->
|
||||
<!--
|
||||
This is an **example** content file inside the **includes** leaf bundle.
|
||||
-->
|
||||
这是一个内容文件**示例**，位于一个**includes**叶子包中。
|
||||
|
||||
<!--
|
||||
Included content files can also contain shortcodes.
|
||||
-->
|
||||
{{< note >}}
|
||||
被包含的内容文件也可以包含短代码。
|
||||
{{< /note >}}
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: 例子 #1
|
||||
---
|
||||
<!--
|
||||
title: Example #1
|
||||
-->
|
||||
|
||||
<!--
|
||||
This is another **example** content file inside the **includes** leaf bundle.
|
||||
-->
|
||||
这是另一个内容文件**示例**，位于一个**includes**叶子包中。
|
||||
|
||||
@@ -0,0 +1,651 @@
|
||||
---
|
||||
title: 定制 Hugo 短代码
|
||||
content_type: concept
|
||||
---
|
||||
<!--
|
||||
title: Custom Hugo Shortcodes
|
||||
content_type: concept
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation.
|
||||
-->
|
||||
本页面将介绍 Hugo 自定义短代码，可以用于 Kubernetes Markdown 文档书写。
|
||||
|
||||
<!--
|
||||
Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes).
|
||||
-->
|
||||
关于短代码的更多信息可参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Feature state
|
||||
|
||||
In a Markdown page (`.md` file) on this site, you can add a shortcode to
|
||||
display version and state of the documented feature.
|
||||
-->
|
||||
## 功能状态
|
||||
|
||||
在本站的 Markdown 页面（`.md` 文件）中，你可以加入短代码来展示所描述的功能特性的版本和状态。
|
||||
|
||||
<!--
|
||||
### Feature state demo
|
||||
|
||||
Below is a demo of the feature state snippet, which displays the feature as
|
||||
stable in the latest Kubernetes version.
|
||||
-->
|
||||
### 功能状态示例
|
||||
|
||||
下面是一个功能状态代码段的演示，表明这个功能已经在最新版 Kubernetes 中稳定了。
|
||||
|
||||
```
|
||||
{{</* feature-state state="stable" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
Renders to:
|
||||
-->
|
||||
会转换为：
|
||||
|
||||
{{< feature-state state="stable" >}}
|
||||
|
||||
<!--
|
||||
The valid values for `state` are:
|
||||
-->
|
||||
`state` 的可选值如下：
|
||||
|
||||
* alpha
|
||||
* beta
|
||||
* deprecated
|
||||
* stable
|
||||
|
||||
<!--
|
||||
### Feature state code
|
||||
|
||||
The displayed Kubernetes version defaults to that of the page or the site. You can change the
|
||||
feature state version by passing the `for_k8s_version` shortcode parameter. For example:
|
||||
-->
|
||||
### 功能状态代码
|
||||
|
||||
所显示的 Kubernetes 默认为该页或站点版本。
|
||||
修改 <code>for_k8s_version</code> 短代码参数可以调整要显示的版本。例如
|
||||
|
||||
```
|
||||
{{</* feature-state for_k8s_version="v1.10" state="beta" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
Renders to:
|
||||
-->
|
||||
会转换为：
|
||||
|
||||
{{< feature-state for_k8s_version="v1.10" state="beta" >}}
|
||||
|
||||
<!--
|
||||
## Glossary
|
||||
There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`.
|
||||
|
||||
You can reference glossary terms with an inclusion that automatically updates
|
||||
and replaces content with the relevant links from [our glossary](/docs/reference/glossary/).
|
||||
When the glossary term is moused-over, the glossary entry displays a tooltip.
|
||||
The glossary term also displays as a link.
|
||||
|
||||
As well as inclusions with tooltips, you can reuse the definitions from the glossary in
|
||||
page content.
|
||||
-->
|
||||
## 词汇
|
||||
|
||||
有两种词汇表提示：`glossary_tooltip` 和 `glossary_definition`。
|
||||
|
||||
你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容
|
||||
（[我们的词汇库](/zh/docs/reference/glossary/)）
|
||||
在浏览在线文档时，术语会显示为超链接的样式，当鼠标移到术语上时，其解释就会显示在提示框中。
|
||||
|
||||
除了包含工具提示外，你还可以重用页面内容中词汇表中的定义。
|
||||
<!--
|
||||
The raw data for glossary terms is stored at
|
||||
[the glossary directory](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary),
|
||||
with a content file for each glossary term.
|
||||
-->
|
||||
|
||||
词汇术语的原始数据保存在[词汇目录](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary)，
|
||||
每个内容文件对应相应的术语解释。
|
||||
|
||||
<!--
|
||||
### Glossary demo
|
||||
|
||||
For example, the following include within the Markdown renders to
|
||||
{{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
|
||||
-->
|
||||
### 词汇演示
|
||||
|
||||
例如下面的代码在 Markdown 中将会转换为
|
||||
{{< glossary_tooltip text="cluster" term_id="cluster" >}}，然后在提示框中显示。
|
||||
|
||||
```
|
||||
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
|
||||
```
|
||||
<!--
|
||||
Here's a short glossary definition:
|
||||
-->
|
||||
这是一个简短的词汇表定义：
|
||||
|
||||
```
|
||||
{{</* glossary_definition prepend="A cluster is" term_id="cluster" length="short" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
which renders as:
|
||||
{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}
|
||||
-->
|
||||
呈现为：
|
||||
{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}
|
||||
|
||||
<!--
|
||||
You can also include a full definition:
|
||||
-->
|
||||
你也可以包括完整的定义：
|
||||
|
||||
```
|
||||
{{</* glossary_definition term_id="cluster" length="all" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
which renders as:
|
||||
-->
|
||||
呈现为：
|
||||
{{< glossary_definition term_id="cluster" length="all" >}}
|
||||
|
||||
<!--
|
||||
## Links to API Reference
|
||||
-->
|
||||
## 链接至 API 参考 {#links-to-api-reference}
|
||||
|
||||
<!--
|
||||
You can link to a page of the Kubernetes API reference using the
|
||||
`api-reference` shortcode, for example to the
|
||||
{{< api-reference page="workload-resources/pod-v1" >}} reference:
|
||||
-->
|
||||
你可以使用 `api-reference` 短代码链接到 Kubernetes API 参考页面，例如
|
||||
Pod
|
||||
{{< api-reference page="workload-resources/pod-v1" >}} 参考文件：
|
||||
|
||||
```
|
||||
{{</* api-reference page="workload-resources/pod-v1" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
The content of the `page` parameter is the suffix of the URL of the API reference page.
|
||||
-->
|
||||
本语句中 `page` 参数的内容是 API 参考页面的 URL 后缀。
|
||||
|
||||
|
||||
<!--
|
||||
You can link to a specific place into a page by specifying an `anchor`
|
||||
parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
|
||||
reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
|
||||
section of the page:
|
||||
-->
|
||||
你可以通过指定 `anchor` 参数链接到页面中的特定位置，例如到
|
||||
{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} 参考，或页面的
|
||||
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
|
||||
部分。
|
||||
|
||||
```
|
||||
{{</* api-reference page="workload-resources/pod-v1" anchor="PodSpec" */>}}
|
||||
{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" */>}}
|
||||
```
|
||||
|
||||
|
||||
<!--
|
||||
You can change the text of the link by specifying a `text` parameter, for
|
||||
example by linking to the
|
||||
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}}
|
||||
section of the page:
|
||||
-->
|
||||
你可以通过指定 `text` 参数来更改链接的文本，例如通过链接到页面的
|
||||
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量">}}
|
||||
部分：
|
||||
|
||||
```
|
||||
{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量" */>}}
|
||||
```
|
||||
|
||||
|
||||
<!--
|
||||
## Table captions
|
||||
|
||||
You can make tables more accessible to screen readers by adding a table caption. To add a
|
||||
[caption](https://www.w3schools.com/tags/tag_caption.asp) to a table,
|
||||
enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
|
||||
|
||||
{{< note >}}
|
||||
Table captions are visible to screen readers but invisible when viewed in standard HTML.
|
||||
{{< /note >}}
|
||||
|
||||
Here's an example:
|
||||
-->
|
||||
## 表格标题 {#table-captions}
|
||||
|
||||
通过添加表格标题，你可以让表格能够被屏幕阅读器读取。
|
||||
要向表格添加[标题（Caption）](https://www.w3schools.com/tags/tag_caption.asp)，
|
||||
可用 `table` 短代码包围表格定义，并使用 `caption` 参数给出表格标题。
|
||||
|
||||
{{< note >}}
|
||||
表格标题对屏幕阅读器是可见的，但在标准 HTML 中查看时是不可见的。
|
||||
{{< /note >}}
|
||||
|
||||
下面是一个例子：
|
||||
|
||||
<!--
|
||||
```go-html-template
|
||||
{{</* table caption="Configuration parameters" >}}
|
||||
Parameter | Description | Default
|
||||
`timeout` | The timeout for requests | `30s`
|
||||
`logLevel` | The log level for log output | `INFO`
|
||||
{{< /table */>}}
|
||||
|
||||
The rendered table looks like this:
|
||||
|
||||
{{< table caption="Configuration parameters" >}}
|
||||
Parameter | Description | Default
|
||||
`timeout` | The timeout for requests | `30s`
|
||||
`logLevel` | The log level for log output | `INFO`
|
||||
{{< /table >}}
|
||||
-->
|
||||
|
||||
```go-html-template
|
||||
{{</* table caption="配置参数" >}}
|
||||
参数 | 描述 | 默认值
|
||||
:---------|:------------|:-------
|
||||
`timeout` | 请求的超时时长 | `30s`
|
||||
`logLevel` | 日志输出的级别 | `INFO`
|
||||
{{< /table */>}}
|
||||
```
|
||||
|
||||
所渲染的表格如下：
|
||||
|
||||
{{< table caption="配置参数" >}}
|
||||
参数 | 描述 | 默认值
|
||||
:---------|:------------|:-------
|
||||
`timeout` | 请求的超时时长 | `30s`
|
||||
`logLevel` | 日志输出的级别 | `INFO`
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
If you inspect the HTML for the table, you should see this element immediately
|
||||
after the opening `<table>` element:
|
||||
|
||||
```html
|
||||
<caption style="display: none;">Configuration parameters</caption>
|
||||
```
|
||||
-->
|
||||
如果你查看表格的 HTML 输出结果，你会看到 `<table>` 元素
|
||||
后面紧接着下面的元素：
|
||||
|
||||
```html
|
||||
<caption style="display: none;">配置参数</caption>
|
||||
```
|
||||
|
||||
<!--
|
||||
## Tabs
|
||||
|
||||
In a markdown page (`.md` file) on this site, you can add a tab set to display
|
||||
multiple flavors of a given solution.
|
||||
|
||||
The `tabs` shortcode takes these parameters:
|
||||
-->
|
||||
## 标签页
|
||||
|
||||
在本站的 Markdown 页面（`.md` 文件）中，你可以加入一个标签页集来显示
|
||||
某解决方案的不同形式。
|
||||
|
||||
标签页的短代码包含以下参数：
|
||||
|
||||
<!--
|
||||
* `name`: The name as shown on the tab.
|
||||
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo
|
||||
what code language to use for highlighting.
|
||||
* `include`: The file to include in the tab. If the tab lives in a Hugo
|
||||
[leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles),
|
||||
the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself.
|
||||
If not, the content page that needs to be included is looked up relative to the current page.
|
||||
Note that with the `include`, you do not have any shortcode inner content and must use the
|
||||
self-closing syntax. For example,
|
||||
`{{</* tab name="Content File #1" include="example1" /*/>}}`. The language needs to be specified
|
||||
under `codelang` or the language is taken based on the file name.
|
||||
Non-content files are code-highlighted by default.
|
||||
-->
|
||||
* `name`： 标签页上显示的名字。
|
||||
* `codelang`: 如果要在 `tab` 短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。
|
||||
* `include`: 标签页中所要包含的文件。如果标签页是在 Hugo 的
|
||||
[叶子包](https://gohugo.io/content-management/page-bundles/#leaf-bundles)中定义，
|
||||
Hugo 会在包内查找文件（可以是 Hugo 所支持的任何 MIME 类型文件）。
|
||||
否则，Hugo 会在当前路径的相对路径下查找所要包含的内容页面。
|
||||
注意，在 `include` 页面中不能包含短代码内容，必须要使用自结束（self-closing）语法。
|
||||
例如 `{{</* tab name="Content File #1" include="example1" /*/>}}`。
|
||||
如果没有在 `codelang` 进行声明的话，Hugo 会根据文件名推测所用的语言。
|
||||
默认情况下，非内容文件将会被代码高亮。
|
||||
<!--
|
||||
* If your inner content is markdown, you must use the `%`-delimiter to surround the tab.
|
||||
For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
|
||||
* You can combine the variations mentioned above inside a tab set.
|
||||
-->
|
||||
* 如果内部内容是 Markdown，你必须要使用 `%` 分隔符来包装标签页。
|
||||
例如，`{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`。
|
||||
* 可以在标签页集中混合使用上面的各种变形。
|
||||
|
||||
<!--
|
||||
Below is a demo of the tabs shortcode.
|
||||
|
||||
The tab **name** in a `tabs` definition must be unique within a content page.
|
||||
-->
|
||||
下面是标签页短代码的示例。
|
||||
|
||||
{{< note >}}
|
||||
内容页面下的 **tabs** 定义中的标签页 **name** 必须是唯一的。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Tabs demo: Code highlighting
|
||||
-->
|
||||
### 标签页演示：代码高亮
|
||||
|
||||
```go-text-template
|
||||
{{</* tabs name="tab_with_code" >}}
|
||||
{{{< tab name="Tab 1" codelang="bash" >}}
|
||||
echo "This is tab 1."
|
||||
{{< /tab >}}
|
||||
{{< tab name="Tab 2" codelang="go" >}}
|
||||
println "This is tab 2."
|
||||
{{< /tab >}}}
|
||||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
Renders to:
|
||||
-->
|
||||
会转换为：
|
||||
|
||||
{{< tabs name="tab_with_code" >}}
|
||||
{{< tab name="Tab 1" codelang="bash" >}}
|
||||
echo "This is tab 1."
|
||||
{{< /tab >}}
|
||||
{{< tab name="Tab 2" codelang="go" >}}
|
||||
println "This is tab 2."
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
<!--
|
||||
### Tabs demo: Inline Markdown and HTML
|
||||
-->
|
||||
### 标签页演示：内联 Markdown 和 HTML
|
||||
|
||||
```go-html-template
|
||||
{{</* tabs name="tab_with_md" >}}
|
||||
{{% tab name="Markdown" %}}
|
||||
这是 **一些 markdown。**
|
||||
{{< note >}}
|
||||
它甚至可以包含短代码。
|
||||
{{< /note >}}
|
||||
{{% /tab %}}
|
||||
{{< tab name="HTML" >}}
|
||||
<div>
|
||||
<h3>纯 HTML</h3>
|
||||
<p>这是一些 <i>纯</i> HTML。</p>
|
||||
</div>
|
||||
{{< /tab >}}
|
||||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
Renders to:
|
||||
-->
|
||||
会转换为：
|
||||
|
||||
{{< tabs name="tab_with_md" >}}
|
||||
{{% tab name="Markdown" %}}
|
||||
这是 **一些 markdown。**
|
||||
{{< note >}}
|
||||
它甚至可以包含短代码。
|
||||
{{< /note >}}
|
||||
{{% /tab %}}
|
||||
{{< tab name="HTML" >}}
|
||||
<div>
|
||||
<h3>纯 HTML</h3>
|
||||
<p>这是一些 <i>纯</i> HTML。</p>
|
||||
</div>
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
<!--
|
||||
### Tabs demo: File include
|
||||
-->
|
||||
### 标签页演示：文件嵌套
|
||||
|
||||
```go-text-template
|
||||
{{</* tabs name="tab_with_file_include" >}}
|
||||
{{< tab name="Content File #1" include="example1" />}}
|
||||
{{< tab name="Content File #2" include="example2" />}}
|
||||
{{< tab name="JSON File" include="podtemplate" />}}
|
||||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
Renders to:
|
||||
-->
|
||||
会转换为：
|
||||
|
||||
{{< tabs name="tab_with_file_include" >}}
|
||||
{{< tab name="Content File #1" include="example1" />}}
|
||||
{{< tab name="Content File #2" include="example2" />}}
|
||||
{{< tab name="JSON File" include="podtemplate.json" />}}
|
||||
{{< /tabs >}}
|
||||
|
||||
<!--
|
||||
## Third party content marker
|
||||
-->
|
||||
## 第三方内容标记 {#third-party-content-marker}
|
||||
|
||||
<!--
|
||||
Running Kubernetes requires third-party software. For example: you
|
||||
usually need to add a
|
||||
[DNS server](/docs/tasks/administer-cluster/dns-custom-nameservers/#introduction)
|
||||
to your cluster so that name resolution works.
|
||||
-->
|
||||
运行 Kubernetes 需要第三方软件。例如：你通常需要将
|
||||
[DNS 服务器](/zh/docs/tasks/administer-cluster/dns-custom-nameservers/#introduction)
|
||||
添加到集群中，以便名称解析工作。
|
||||
|
||||
<!--
|
||||
When we link to third-party software, or otherwise mention it,
|
||||
we follow the [content guide](/docs/contribute/style/content-guide/)
|
||||
and we also mark those third party items.
|
||||
-->
|
||||
当我们链接到第三方软件或以其他方式提及它时，我们会遵循[内容指南](/zh/docs/contribute/style/content-guide/)
|
||||
并标记这些第三方项目。
|
||||
|
||||
<!--
|
||||
Using these shortcodes adds a disclaimer to any documentation page
|
||||
that uses them.
|
||||
-->
|
||||
使用这些短代码会向使用它们的任何文档页面添加免责声明。
|
||||
|
||||
<!--
|
||||
### Lists {#third-party-content-list}
|
||||
-->
|
||||
### 列表 {#third-party-content-list}
|
||||
|
||||
<!--
|
||||
For a list of several third-party items, add:
|
||||
-->
|
||||
对于有关几个第三方项目的列表，请添加：
|
||||
```
|
||||
{{%/* thirdparty-content */%}}
|
||||
```
|
||||
<!--
|
||||
just below the heading for the section that includes all items.
|
||||
-->
|
||||
在包含所有项目的段落标题正下方。
|
||||
|
||||
<!--
|
||||
### Items {#third-party-content-item}
|
||||
-->
|
||||
### 项目 {#third-party-content-item}
|
||||
|
||||
<!--
|
||||
If you have a list where most of the items refer to in-project
|
||||
software (for example: Kubernetes itself, and the separate
|
||||
[Descheduler](https://github.com/kubernetes-sigs/descheduler)
|
||||
component), then there is a different form to use.
|
||||
-->
|
||||
如果你有一个列表，其中大多数项目引用项目内软件（例如：Kubernetes 本身，以及单独的
|
||||
[Descheduler](https://github.com/kubernetes-sigs/descheduler)
|
||||
组件），那么可以使用不同的形式。
|
||||
|
||||
<!--
|
||||
Add the shortcode:
|
||||
|
||||
before the item, or just below the heading for the specific item.
|
||||
-->
|
||||
在项目之前，或在特定项目的段落下方添加此短代码：
|
||||
```
|
||||
{{%/* thirdparty-content single="true" */%}}
|
||||
```
|
||||
|
||||
|
||||
<!--
|
||||
## Version strings
|
||||
|
||||
To generate a version string for inclusion in the documentation, you can choose from
|
||||
several version shortcodes. Each version shortcode displays a version string derived from
|
||||
the value of a version parameter found in the site configuration file, `config.toml`.
|
||||
The two most commonly used version parameters are `latest` and `version`.
|
||||
-->
|
||||
## 版本号信息
|
||||
|
||||
要在文档中生成版本号信息，可以从以下几种短代码中选择。每个短代码可以基于站点配置文件
|
||||
`config.toml` 中的版本参数生成一个版本号取值。最常用的参数为 `latest` 和 `version`。
|
||||
|
||||
<!--
|
||||
### `{{</* param "version" */>}}`
|
||||
|
||||
The `{{</* param "version" */>}}` shortcode generates the value of the current
|
||||
version of the Kubernetes documentation from the `version` site parameter. The
|
||||
`param` shortcode accepts the name of one site parameter, in this case:
|
||||
`version`.
|
||||
-->
|
||||
### `{{</* param "version" */>}}`
|
||||
|
||||
`{{</* param "version" */>}}` 短代码可以基于站点参数 `version` 生成 Kubernetes
|
||||
文档的当前版本号取值。短代码 `param` 允许传入一个站点参数名称，在这里是 `version`。
|
||||
|
||||
<!--
|
||||
{{< note >}}
|
||||
In previously released documentation, `latest` and `version` parameter values
|
||||
are not equivalent. After a new version is released, `latest` is incremented
|
||||
and the value of `version` for the documentation set remains unchanged. For
|
||||
example, a previously released version of the documentation displays `version`
|
||||
as `v1.19` and `latest` as `v1.20`.
|
||||
{{< /note >}}
|
||||
-->
|
||||
{{< note >}}
|
||||
在先前已经发布的文档中，`latest` 和 `version` 参数值并不完全等价。新版本文档发布后，参数
|
||||
`latest` 会增加，而 `version` 则保持不变。例如，在上一版本的文档中使用 `version` 会得到
|
||||
`v1.19`，而使用 `latest` 则会得到 `v1.20`。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
Renders to:
|
||||
-->
|
||||
转换为：
|
||||
|
||||
{{< param "version" >}}
|
||||
|
||||
<!--
|
||||
### `{{</* latest-version */>}}`
|
||||
|
||||
The `{{</* latest-version */>}}` shortcode returns the value of the `latest` site parameter.
|
||||
The `latest` site parameter is updated when a new version of the documentation is released.
|
||||
This parameter does not always match the value of `version` in a documentation set.
|
||||
|
||||
Renders to:
|
||||
-->
|
||||
### `{{</* latest-version */>}}`
|
||||
|
||||
`{{</* latest-version */>}}` 返回站点参数 `latest` 的取值。每当新版本文档发布时，该参数均会被更新。
|
||||
因此，参数 `latest` 与 `version` 并不总是相同。
|
||||
|
||||
转换为：
|
||||
|
||||
{{< latest-version >}}
|
||||
|
||||
<!--
|
||||
### `{{</* latest-semver */>}}`
|
||||
|
||||
The `{{</* latest-semver */>}}` shortcode generates the value of `latest`
|
||||
without the "v" prefix.
|
||||
|
||||
Renders to:
|
||||
-->
|
||||
### `{{</* latest-semver */>}}`
|
||||
|
||||
`{{</* latest-semver */>}}` 短代码可以生成站点参数 `latest` 不含前缀 `v` 的版本号取值。
|
||||
|
||||
转换为：
|
||||
|
||||
{{< latest-semver >}}
|
||||
|
||||
<!--
|
||||
### `{{</* version-check */>}}`
|
||||
|
||||
The `{{</* version-check */>}}` shortcode checks if the `min-kubernetes-server-version`
|
||||
page parameter is present and then uses this value to compare to `version`.
|
||||
|
||||
Renders to:
|
||||
-->
|
||||
### `{{</* version-check */>}}`
|
||||
|
||||
`{{</* version-check */>}}` 会检查是否设置了页面参数 `min-kubernetes-server-version`
|
||||
并将其与 `version` 进行比较。
|
||||
|
||||
转换为：
|
||||
|
||||
{{< version-check >}}
|
||||
|
||||
<!--
|
||||
### `{{</* latest-release-notes */>}}`
|
||||
|
||||
The `{{</* latest-release-notes */>}}` shortcode generates a version string
|
||||
from `latest` and removes the "v" prefix. The shortcode prints a new URL for
|
||||
the release note CHANGELOG page with the modified version string.
|
||||
|
||||
Renders to:
|
||||
-->
|
||||
### `{{</* latest-release-notes */>}}`
|
||||
|
||||
`{{</* latest-release-notes */>}}` 短代码基于站点参数 `latest` 生成不含前缀 `v`
|
||||
的版本号取值，并输出该版本更新日志的超链接地址。
|
||||
|
||||
转换为：
|
||||
|
||||
{{< latest-release-notes >}}
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* Learn about [Hugo](https://gohugo.io/).
|
||||
* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/).
|
||||
* Learn about [page content types](/docs/contribute/style/page-content-types/).
|
||||
* Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/).
|
||||
* Learn about [advanced contributing](/docs/contribute/advanced/).
|
||||
-->
|
||||
|
||||
* 了解 [Hugo](https://gohugo.io/)。
|
||||
* 了解[撰写新的话题](/zh/docs/contribute/style/write-new-topic/)。
|
||||
* 了解[使用页面内容类型](/zh/docs/contribute/style/page-content-types/)。
|
||||
* 了解[发起 PR](/zh/docs/contribute/new-content/open-a-pr/)。
|
||||
* 了解[进阶贡献](/zh/docs/contribute/advanced/)。
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"apiVersion": "v1",
|
||||
"kind": "PodTemplate",
|
||||
"metadata": {
|
||||
"name": "nginx"
|
||||
},
|
||||
"template": {
|
||||
"metadata": {
|
||||
"labels": {
|
||||
"name": "nginx"
|
||||
},
|
||||
"generateName": "nginx-"
|
||||
},
|
||||
"spec": {
|
||||
"containers": [{
|
||||
"name": "nginx",
|
||||
"image": "dockerfile/nginx",
|
||||
"ports": [{"containerPort": 80}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,412 @@
|
||||
---
|
||||
title: 页面内容类型
|
||||
content_type: concept
|
||||
weight: 30
|
||||
card:
|
||||
name: contribute
|
||||
weight: 30
|
||||
---
|
||||
<!--
|
||||
title: Page content types
|
||||
content_type: concept
|
||||
weight: 30
|
||||
card:
|
||||
name: contribute
|
||||
weight: 30
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
The Kubernetes documentation follows several types of page content:
|
||||
|
||||
- Concept
|
||||
- Task
|
||||
- Tutorial
|
||||
- Reference
|
||||
-->
|
||||
Kubernetes 文档包含以下几种页面内容类型：
|
||||
|
||||
- 概念（Concept）
|
||||
- 任务（Task）
|
||||
- 教程（Tutorial）
|
||||
- 参考（Reference）
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Content sections
|
||||
|
||||
Each page content type contains a number of sections defined by
|
||||
Markdown comments and HTML headings. You can add content headings to
|
||||
your page with the `heading` shortcode. The comments and headings help
|
||||
maintain the structure of the page content types.
|
||||
|
||||
Examples of Markdown comments defining page content sections:
|
||||
-->
|
||||
## 内容章节 {#content-sections}
|
||||
|
||||
每种页面内容类型都有一些使用 Markdown 注释和 HTML 标题定义的章节。
|
||||
你可以使用 `heading` 短代码将内容标题添加到你的页面中。
|
||||
注释和标题有助于维护对应页面内容类型的结构组织。
|
||||
|
||||
定义页面内容章节的 Markdown 注释示例：
|
||||
|
||||
```markdown
|
||||
<!-- overview -->
|
||||
```
|
||||
|
||||
```markdown
|
||||
<!-- body -->
|
||||
```
|
||||
|
||||
<!--
|
||||
To create common headings in your content pages, use the `heading` shortcode with
|
||||
a heading string.
|
||||
|
||||
Examples of heading strings:
|
||||
|
||||
- whatsnext
|
||||
- prerequisites
|
||||
- objectives
|
||||
- cleanup
|
||||
- synopsis
|
||||
- seealso
|
||||
- options
|
||||
|
||||
For example, to create a `whatsnext` heading, add the heading shortcode with the "whatsnext" string:
|
||||
-->
|
||||
要在内容页面中创建通用的标题，可以使用 `heading` 短代码加上标题字符串。
|
||||
|
||||
标题字符串示例：
|
||||
|
||||
- whatsnext
|
||||
- prerequisites
|
||||
- objectives
|
||||
- cleanup
|
||||
- synopsis
|
||||
- seealso
|
||||
- options
|
||||
|
||||
例如，要创建一个 `whatsnext` 标题，添加 heading 短代码并指定 "whatsnext" 字符串：
|
||||
|
||||
```none
|
||||
## {{%/* heading "whatsnext" */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
You can declare a `prerequisites` heading as follows:
|
||||
-->
|
||||
你可以像下面这样声明一个 `prerequisites` 标题：
|
||||
|
||||
```none
|
||||
## {{%/* heading "prerequisites" */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
The `heading` shortcode expects one string parameter.
|
||||
The heading string parameter matches the prefix of a variable in the `i18n/<lang>.toml` files.
|
||||
For example:
|
||||
-->
|
||||
短代码 `heading` 需要一个字符串参数。
|
||||
该字符串参数要与 `i18n/<语言>.toml` 文件中以其为前缀的某个变量匹配。
|
||||
例如：
|
||||
|
||||
`i18n/en.toml`:
|
||||
|
||||
```toml
|
||||
[whatsnext_heading]
|
||||
other = "What's next"
|
||||
```
|
||||
|
||||
`i18n/ko.toml`:
|
||||
|
||||
```toml
|
||||
[whatsnext_heading]
|
||||
other = "다음 내용"
|
||||
```
|
||||
|
||||
<!--
|
||||
## Content types
|
||||
|
||||
Each content type informally defines its expected page structure.
|
||||
Create page content with the suggested page sections.
|
||||
-->
|
||||
## 内容类型 {#content-types}
|
||||
|
||||
每种内容类型都非正式地定义了期望的页面结构组织。
|
||||
请按照所建议的页面章节来创建内容页面。
|
||||
|
||||
<!--
|
||||
### Concept
|
||||
|
||||
A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application once it is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/concepts` directory, with the following characteristics:
|
||||
|
||||
Concept pages are divided into three sections:
|
||||
|
||||
| Page section |
|
||||
|----------------|
|
||||
| overview |
|
||||
| body |
|
||||
| whatsnext |
|
||||
-->
|
||||
### 概念 {#concept}
|
||||
|
||||
概念页面用来解释 Kubernetes 的某些方面。例如，概念页面可以用来描述 Kubernetes
|
||||
中的 Deployment 对象，解释其作为应用的角色如何部署、扩缩和更新。
|
||||
通常，概念页面不需要包含步骤序列，但包含指向任务或教程的链接。
|
||||
|
||||
要编写一个新的概念页面，在 `/content/en/docs/concepts` 目录下面的子目录中新建
|
||||
一个 Markdown 文件。该文件具有以下特点。
|
||||
|
||||
概念页面分为三个章节：
|
||||
|
||||
| 页面章节 |
|
||||
|--------------------|
|
||||
| overview （概述） |
|
||||
| body (主体） |
|
||||
| whatsnext (接下来）|
|
||||
|
||||
<!--
|
||||
The `overview` and `body` sections appear as comments in the concept page.
|
||||
You can add the `whatsnext` section to your page with the `heading` shortcode.
|
||||
|
||||
Fill each section with content. Follow these guidelines:
|
||||
|
||||
- Organize content with H2 and H3 headings.
|
||||
- For `overview`, set the topic's context with a single paragraph.
|
||||
- For `body`, explain the concept.
|
||||
- For `whatsnext`, provide a bulleted list of topics (5 maximum) to learn more about the concept.
|
||||
|
||||
[Annotations](/docs/concepts/overview/working-with-objects/annotations/) is a
|
||||
published example of a concept page.
|
||||
-->
|
||||
其中的 `overview` 和 `body` 章节在概念页面中显示为注释。
|
||||
你可以使用 `heading` 短代码向页面添加 `wahtsnext` 节。
|
||||
|
||||
在为每个章节撰写内容时，遵从一些规定：
|
||||
|
||||
- 使用二级和三级标题（H2、H3）来组织内容
|
||||
- 在 `overview` 节中，使用一段文字来为主体部分铺陈上下文；
|
||||
- 在 `body` 节中，详细解释对应概念；
|
||||
- 对于 `whatsnext` 节，提供一个项目符号列表（最多 5 个），帮助读者进一步学习掌握概念
|
||||
|
||||
[注解](/zh/docs/concepts/overview/working-with-objects/annotations/)页面是一个已经
|
||||
上线的概念页面的例子。
|
||||
|
||||
<!--
|
||||
### Task
|
||||
|
||||
A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.
|
||||
|
||||
To write a new task page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tasks` directory, with the following characteristics:
|
||||
|
||||
| Page section |
|
||||
|----------------|
|
||||
| overview |
|
||||
| prerequisites |
|
||||
| steps |
|
||||
| discussion |
|
||||
| whatsnext |
|
||||
-->
|
||||
### 任务（Task） {#task}
|
||||
|
||||
任务页面讲解如何完成某项工作，通常包含由为数不多的几个步骤组成的序列。
|
||||
任务页面的讲解文字很少，不过通常会包含指向概念主题的链接，以便读者
|
||||
能够了解相关的背景和知识。
|
||||
|
||||
编写新的任务页面时，在 `/content/en/docs/tasks` 目录下的子目录中创建一个
|
||||
新的 Markdown 文件。该文件特点如下。
|
||||
|
||||
| 页面章节 |
|
||||
|---------------------------|
|
||||
| overview （概述） |
|
||||
| prerequisites （准备工作）|
|
||||
| steps （步骤） |
|
||||
| discussion （讨论） |
|
||||
| whatsnext （接下来） |
|
||||
|
||||
<!--
|
||||
The `overview`, `steps`, and `discussion` sections appear as comments in the task page.
|
||||
You can add the `prerequisites` and `whatsnext` sections to your page
|
||||
with the `heading` shortcode.
|
||||
|
||||
Within each section, write your content. Use the following guidelines:
|
||||
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `prerequisites`, use bullet lists when possible. Start adding additional
|
||||
prerequisites below the `include`. The default prerequisites include a running Kubernetes cluster.
|
||||
- For `steps`, use numbered lists.
|
||||
- For discussion, use normal content to expand upon the information covered
|
||||
in `steps`.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published task topic is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/extend-kubernetes/http-proxy-access-api/).
|
||||
-->
|
||||
其中的 `overview`、`steps` 和 `discussion` 节在任务页面中显示为注释。
|
||||
你可以使用 `heading` 短代码添加 `prerequisites` 和 `whatsnext` 小节。
|
||||
|
||||
在每个小节内撰写内容时注意以下规定：
|
||||
|
||||
- 最低使用二级标题（H2，标题行前带两个 `#` 字符）。每个小节都会由模版自动给出标题。
|
||||
- 在 `overview` 节中，用一个段落为整个任务主体设定语境；
|
||||
- 在 `prerequisites` 节中，尽可能使用项目符号列表。
|
||||
额外的环境准备条件要加在 `include` 短代码之后。
|
||||
默认的环境准备条件是拥有一个在运行的 Kubernetes 集群。
|
||||
- 在 `steps` 节中，使用编号符号列表。
|
||||
- 在 `discussion` 节中，使用正常文字内容来对 `steps` 节中内容展开叙述。
|
||||
- 在 `whatsnext` 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣
|
||||
阅读的主题。
|
||||
|
||||
已上线的任务主题示例之一是[使用 HTTP 代理来访问 Kubernetes API](/zh/docs/tasks/extend-kubernetes/http-proxy-access-api/)。
|
||||
|
||||
<!--
|
||||
### Tutorial
|
||||
|
||||
A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tutorials` directory, with the following characteristics:
|
||||
|
||||
| Page section |
|
||||
|----------------|
|
||||
| overview |
|
||||
| prerequisites |
|
||||
| objectives |
|
||||
| lessoncontent |
|
||||
| cleanup |
|
||||
| whatsnext |
|
||||
-->
|
||||
### 教程（Tutorial） {#tutorial}
|
||||
|
||||
教程页面描述如果完成一个比单一任务规模更大的目标。通常教程页面会有多个小节，
|
||||
每个小节由一系列步骤组成。例如，每个教程可能提供对代码示例的讲解，便于用户
|
||||
了解 Kubernetes 的某个功能特性。教程可以包含表面层面的概念解释，对于更深层面
|
||||
的概念主题应该使用链接。
|
||||
|
||||
撰写新的教程页面时，在 `/content/en/docs/tutorials` 目录下面的子目录中创建新的
|
||||
Markdown 文件。该文件有以下特点。
|
||||
|
||||
| 页面节区 |
|
||||
|---------------------------|
|
||||
| overview （概述） |
|
||||
| prerequisites （环境准备）|
|
||||
| objectives （目标） |
|
||||
| lessoncontent （教程内容）|
|
||||
| cleanup （清理工作） |
|
||||
| whatsnext （接下来） |
|
||||
|
||||
<!--
|
||||
The `overview`, `objectives`, and `lessoncontent` sections appear as comments in the tutorial page.
|
||||
You can add the `prerequisites`, `cleanup`, and `whatsnext` sections to your page
|
||||
with the `heading` shortcode.
|
||||
|
||||
Within each section, write your content. Use the following guidelines:
|
||||
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by default.
|
||||
- For `objectives`, use bullet lists.
|
||||
- For `lessoncontent`, use a mix of numbered lists and narrative content as
|
||||
appropriate.
|
||||
- For `cleanup`, use numbered lists to describe the steps to clean up the
|
||||
state of the cluster after finishing the task.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published tutorial topic is
|
||||
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
-->
|
||||
教程页面的 `overview`、`objectives` 和 `lessoncontent` 小节显示为注释形式。
|
||||
你可以使用 `heading` 短代码根据需要添加 `prerequisites`、`cleanup` 和
|
||||
`whatsnext` 小节。
|
||||
|
||||
在每个小节中编写内容时，请注意以下规定：
|
||||
|
||||
- 最低使用二级标题（H2，标题前面有两个 `#` 字符）。模版会自动为每个小节设置标题。
|
||||
- 在 `overview` 节中，用一个段落为整个主题设定语境；
|
||||
- 在 `prerequisites` 节中，尽可能使用项目符号列表。
|
||||
额外的环境准备条件要加在已包含的条件之后。
|
||||
- 在 `objectives` 节中，使用项目符号列表。
|
||||
- 在 `lessoncontent` 节中，结合使用编号符号列表和叙述性文字。
|
||||
- 在 `cleanup` 节中，使用编号符号列表来描述任务结束后清理集群状态所需要的步骤。
|
||||
- 在 `whatsnext` 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣
|
||||
阅读的主题。
|
||||
|
||||
已发布的教程主题的一个例子是
|
||||
[使用 Deployment 运行无状态应用](/zh/docs/tasks/run-application/run-stateless-application-deployment/).
|
||||
|
||||
<!--
|
||||
### Reference
|
||||
|
||||
A component tool reference page shows the description and flag options output for
|
||||
a Kubernetes component tool. Each page generates from scripts using the component tool commands.
|
||||
|
||||
A tool reference page has several possible sections:
|
||||
|
||||
| Page section |
|
||||
|--------------------------------|
|
||||
| synopsis |
|
||||
| options |
|
||||
| options from parent commands |
|
||||
| examples |
|
||||
| seealso |
|
||||
|
||||
Examples of published tool reference pages are:
|
||||
|
||||
- [kubeadm init](/docs/reference/setup-tools/kubeadm/kubeadm-init/)
|
||||
- [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
- [kubectl](/docs/reference/kubectl/kubectl/)
|
||||
-->
|
||||
### 参考（Reference） {#reference}
|
||||
|
||||
组件工具的参考页面给出的是某个 Kubernetes 组件工具的描述和参数选项输出。
|
||||
每个页面都是使用组件工具命令基于脚本生成的。
|
||||
|
||||
每个工具参考页面可能包含以下小节：
|
||||
|
||||
| 页面小节 |
|
||||
|-----------------|
|
||||
| synopsis (用法）|
|
||||
| options（选项） |
|
||||
| options from parent commands (从父命令集成的选项） |
|
||||
| examples （示例）|
|
||||
| seealso （参考）|
|
||||
|
||||
已发布的工具参考页面示例包括：
|
||||
|
||||
- [kubeadm init](/zh/docs/reference/setup-tools/kubeadm/kubeadm-init/)
|
||||
- [kube-apiserver](/zh/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
- [kubectl](/zh/docs/reference/kubectl/kubectl/)
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
- Learn about the [Style guide](/docs/contribute/style/style-guide/)
|
||||
- Learn about the [Content guide](/docs/contribute/style/content-guide/)
|
||||
- Learn about [content organization](/docs/contribute/style/content-organization/)
|
||||
-->
|
||||
- 了解[样式指南](/zh/docs/contribute/style/style-guide/)
|
||||
- 了解[内容指南](/zh/docs/contribute/style/content-guide/)
|
||||
- 了解[内容组织](/zh/docs/contribute/style/content-organization/)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,307 @@
|
||||
---
|
||||
title: 撰写新主题
|
||||
content_type: task
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: Writing a new topic
|
||||
content_type: task
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
This page shows how to create a new topic for the Kubernetes docs.
|
||||
-->
|
||||
本页面展示如何为 Kubernetes 文档库创建新主题。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
<!--
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Start contributing](/docs/contribute/start/).
|
||||
-->
|
||||
如[发起 PR](/zh/docs/contribute/new-content/open-a-pr/)中所述，创建 Kubernetes 文档库的派生副本。
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Choosing a page type
|
||||
|
||||
As you prepare to write a new topic, think about the page type that would fit your content the best:
|
||||
-->
|
||||
## 选择页面类型
|
||||
|
||||
当你准备编写一个新的主题时，考虑一下最适合你的内容的页面类型：
|
||||
|
||||
<!--
|
||||
Guidelines for choosing a page type
|
||||
Type | Description
|
||||
:--- | :----------
|
||||
Concept | A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.
|
||||
Task | A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a>
|
||||
Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
|
||||
-->
|
||||
|
||||
{{< table caption = "选择页面类型的说明" >}}
|
||||
类型 | 描述
|
||||
:--- | :----------
|
||||
概念（Concept） | 概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。概念主题的示例可参见 <a href="/zh/docs/concepts/architecture/nodes/">节点</a>。
|
||||
任务（Task） | 任务页面展示如何完成特定任务。其目的是给读者提供一系列的步骤，让他们在阅读时可以实际执行。任务页面可长可短，前提是它始终围绕着某个主题展开。在任务页面中，可以将简短的解释与要执行的步骤混合在一起。如果需要提供较长的解释，则应在概念主题中进行。相关联的任务和概念主题应该相互链接。一个简短的任务页面的实例可参见 <a href="/zh/docs/tasks/configure-pod-container/configure-volume-storage/">配置 Pod 使用卷存储</a>。一个较长的任务页面的实例可参见 <a href="/zh/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">配置活跃性和就绪性探针</a>。
|
||||
教程（Tutorial） | 教程页面展示如何实现某个目标，该目标将若干 Kubernetes 功能特性联系在一起。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的讲解。教程可以包括对 Kubernetes 几个关联特性的简要解释，但有关更深入的特性解释应该链接到相关概念主题。
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
Use a [content type](/docs/contribute/style/page-content-types/) for each new page
|
||||
that you write. Using page type helps ensure
|
||||
consistency among topics of a given type.
|
||||
-->
|
||||
为每个新页面选择其[内容类型](/zh/docs/contribute/style/page-content-types/)。
|
||||
使用页面类型有助于确保给定类型的各主题之间保持一致。
|
||||
|
||||
<!--
|
||||
## Choosing a title and filename
|
||||
|
||||
Choose a title that has the keywords you want search engines to find.
|
||||
Create a filename that uses the words in your title separated by hyphens.
|
||||
For example, the topic with title
|
||||
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
|
||||
has filename `http-proxy-access-api.md`. You don't need to put
|
||||
"kubernetes" in the filename, because "kubernetes" is already in the
|
||||
URL for the topic, for example:
|
||||
-->
|
||||
## 选择标题和文件名
|
||||
|
||||
选择一个标题，确保其中包含希望搜索引擎发现的关键字。
|
||||
确定文件名时请使用标题中的单词，由连字符分隔。
|
||||
例如，标题为[Using an HTTP Proxy to Access Kubernetes API](/zh/docs/tasks/extend-kubernetes/http-proxy-access-api/)
|
||||
的主题的文件名为 `http-proxy-access-api.md`。
|
||||
你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了，
|
||||
例如：
|
||||
|
||||
/docs/tasks/extend-kubernetes/http-proxy-access-api/
|
||||
|
||||
<!--
|
||||
## Adding the topic title to the front matter
|
||||
|
||||
In your topic, put a `title` field in the
|
||||
[front matter](https://gohugo.io/content-management/front-matter/).
|
||||
The front matter is the YAML block that is between the
|
||||
triple-dashed lines at the top of the page. Here's an example:
|
||||
|
||||
```
|
||||
title: Using an HTTP Proxy to Access the Kubernetes API
|
||||
```
|
||||
-->
|
||||
## 在页面前言中添加主题标题
|
||||
|
||||
在你的主题中，在[前言（front-matter）](https://gohugo.io/content-management/front-matter/)
|
||||
中设置一个 `title` 字段。
|
||||
前言是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子：
|
||||
|
||||
```
|
||||
---
|
||||
title: 使用 HTTP 代理访问 Kubernetes API
|
||||
---
|
||||
```
|
||||
|
||||
<!--
|
||||
## Choosing a directory
|
||||
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
-->
|
||||
## 选择目录
|
||||
|
||||
根据页面类型，将新文件放入其中一个子目录中：
|
||||
|
||||
* /content/en/docs/tasks/
|
||||
* /content/en/docs/tutorials/
|
||||
* /content/en/docs/concepts/
|
||||
|
||||
<!--
|
||||
You can put your file in an existing subdirectory, or you can create a new
|
||||
subdirectory.
|
||||
-->
|
||||
你可以将文件放在现有的子目录中，也可以创建一个新的子目录。
|
||||
|
||||
<!--
|
||||
## Placing your topic in the table of contents
|
||||
|
||||
The table of contents is built dynamically using the directory structure of the
|
||||
documentation source. The top-level directories under `/content/en/docs/` create
|
||||
top-level navigation, and subdirectories each have entries in the table of
|
||||
contents.
|
||||
-->
|
||||
## 将主题放在目录中
|
||||
|
||||
目录是使用文档源的目录结构动态构建的。
|
||||
`/content/en/docs/` 下的顶层目录用于创建顶层导航条目，
|
||||
这些目录和它们的子目录在网站目录中都有对应条目。
|
||||
|
||||
<!--
|
||||
Each subdirectory has a file `_index.md`, which represents the "home" page for
|
||||
a given subdirectory's content. The `_index.md` does not need a template. It
|
||||
can contain overview content about the topics in the subdirectory.
|
||||
-->
|
||||
每个子目录都有一个 `_index.md` 文件，它表示的是该子目录内容的主页面。
|
||||
`_index.md` 文件不需要模板。它可以包含各子目录中主题的概述内容。
|
||||
|
||||
<!--
|
||||
Other files in a directory are sorted alphabetically by default. This is almost
|
||||
never the best order. To control the relative sorting of topics in a
|
||||
subdirectory, set the `weight:` front-matter key to an integer. Typically, we
|
||||
use multiples of 10, to account for adding topics later. For instance, a topic
|
||||
with weight `10` will come before one with weight `20`.
|
||||
-->
|
||||
默认情况下，目录中的其他文件按字母顺序排序。这一般不是最好的顺序。
|
||||
要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数值。
|
||||
通常我们使用 10 的倍数，添加后续主题时 `weight` 值递增。
|
||||
例如，`weight` 为 `10` 的主题将位于 `weight` 为 `20` 的主题之前。
|
||||
|
||||
<!--
|
||||
## Embedding code in your topic
|
||||
|
||||
If you want to include some code in your topic, you can embed the code in your
|
||||
file directly using the markdown code block syntax. This is recommended for the
|
||||
following cases (not an exhaustive list):
|
||||
-->
|
||||
## 在主题中嵌入代码
|
||||
|
||||
如果你想在主题中嵌入一些代码，可以直接使用 Markdown 代码块语法将代码嵌入到文件中。
|
||||
建议在以下场合（并非详尽列表）使用嵌入代码：
|
||||
|
||||
<!--
|
||||
- The code shows the output from a command such as
|
||||
`kubectl get deploy mydeployment -o json | jq '.status'`.
|
||||
- The code is not generic enough for users to try out. As an example, you can
|
||||
embed the YAML
|
||||
file for creating a Pod which depends on a specific
|
||||
[FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation.
|
||||
- The code is an incomplete example because its purpose is to highlight a
|
||||
portion of a larger file. For example, when describing ways to
|
||||
customize the [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
|
||||
for some reasons, you can provide a short snippet directly in your topic file.
|
||||
- The code is not meant for users to try out due to other reasons. For example,
|
||||
when describing how a new attribute should be added to a resource using the
|
||||
`kubectl edit` command, you can provide a short example that includes only
|
||||
the attribute to add.
|
||||
-->
|
||||
|
||||
- 代码显示来自命令的输出，例如 `kubectl get deploy mydeployment -o json | jq '.status'`。
|
||||
- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定
|
||||
[FlexVolume](/zh/docs/concepts/storage/volumes#flexvolume) 实现的 Pod。
|
||||
- 该代码是一个不完整的示例，因为其目的是突出展现某个大文件中的部分内容。
|
||||
例如，在描述出于某些原因定制
|
||||
[PodSecurityPolicy](/zh/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
|
||||
的方法时，你可以在主题文件中直接提供一个短的代码段。
|
||||
- 由于某些其他原因，该代码不适合用户验证。
|
||||
例如，当使用 `kubectl edit` 命令描述如何将新属性添加到资源时，
|
||||
你可以提供一个仅包含要添加的属性的简短示例。
|
||||
|
||||
<!--
|
||||
## Including code from another file
|
||||
|
||||
Another way to include code in your topic is to create a new, complete sample
|
||||
file (or group of sample files) and then reference the sample from your topic.
|
||||
Use this method to include sample YAML files when the sample is generic and
|
||||
reusable, and you want the reader to try it out themselves.
|
||||
-->
|
||||
## 引用来自其他文件的代码
|
||||
|
||||
在主题中引用代码的另一种方法是创建一个新的、完整的示例文件（或文件组），
|
||||
然后在主题中引用这些示例。当示例是通用的和可重用的，并且你希望读者自己验证时，
|
||||
使用此方法引用示例 YAML 文件。
|
||||
|
||||
<!--
|
||||
When adding a new standalone sample file, such as a YAML file, place the code in
|
||||
one of the `<LANG>/examples/` subdirectories where `<LANG>` is the language for
|
||||
the topic. In your topic file, use the `codenew` shortcode:
|
||||
-->
|
||||
添加新的独立示例文件（如 YAML 文件）时，将代码放在 `<LANG>/examples/` 的某个子目录中，
|
||||
其中 `<LANG>` 是该主题的语言。在主题文件中使用 `codenew` 短代码：
|
||||
|
||||
```none
|
||||
{{</* codenew file="<RELPATH>/my-example-yaml>" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
where `<RELPATH>` is the path to the file to include, relative to the
|
||||
`examples` directory. The following Hugo shortcode references a YAML
|
||||
file located at `/content/en/examples/pods/storage/gce-volume.yaml`.
|
||||
-->
|
||||
|
||||
`<RELPATH>` 是要引用的文件的路径，相对于 `examples` 目录。以下 Hugo
|
||||
短代码引用了位于 `/content/en/examples/pods/storage/gce-volume.yaml` 的 YAML
|
||||
文件。
|
||||
|
||||
```none
|
||||
{{</* codenew file="pods/storage/gce-volume.yaml" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
To show raw Hugo shortcodes as in the above example and prevent Hugo
|
||||
from interpreting them, use C-style comments directly after the `<` and before
|
||||
the `>` characters. View the code for this page for an example.
|
||||
-->
|
||||
{{< note >}}
|
||||
要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释，
|
||||
请直接在 `<` 字符之后和 `>` 字符之前使用 C 样式注释。请查看此页面的代码。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Showing how to create an API object from a configuration file
|
||||
|
||||
If you need to demonstrate how to create an API object based on a
|
||||
configuration file, place the configuration file in one of the subdirectories
|
||||
under `<LANG>/examples`.
|
||||
|
||||
In your topic, show this command:
|
||||
-->
|
||||
## 显示如何从配置文件创建 API 对象
|
||||
|
||||
如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 `<LANG>/examples`
|
||||
下的某个子目录中。
|
||||
|
||||
在主题中展示以下命令：
|
||||
|
||||
```
|
||||
kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
|
||||
```
|
||||
|
||||
<!--
|
||||
When adding new YAML files to the `<LANG>/examples` directory, make
|
||||
sure the file is also included into the `<LANG>/examples_test.go` file. The
|
||||
Travis CI for the Website automatically runs this test case when PRs are
|
||||
submitted to ensure all examples pass the tests.
|
||||
-->
|
||||
{{< note >}}
|
||||
将新的 YAML 文件添加到 `<LANG>/examples` 目录时，请确保该文件也在
|
||||
`<LANG>/examples_test.go` 文件中被引用。
|
||||
当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
For an example of a topic that uses this technique, see
|
||||
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).
|
||||
-->
|
||||
有关使用此技术的主题的示例，请参见
|
||||
[运行单实例有状态的应用](/zh/docs/tasks/run-application/run-single-instance-stateful-application/)。
|
||||
|
||||
<!--
|
||||
## Adding images to a topic
|
||||
|
||||
Put image files in the `/images` directory. The preferred image format is SVG.
|
||||
-->
|
||||
## 向主题添加图片
|
||||
|
||||
将图片文件放入 `/images` 目录。首选的图片格式是 SVG。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
* Learn about [using page content types](/docs/contribute/style/page-content-types/).
|
||||
* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).
|
||||
-->
|
||||
* 了解[使用页面内容类型](/zh/docs/contribute/style/page-content-types/).
|
||||
* 了解[创建 PR](/zh/docs/contribute/new-content/open-a-pr/).
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
title: 提出内容改进建议
|
||||
slug: suggest-improvements
|
||||
content_type: concept
|
||||
weight: 10
|
||||
card:
|
||||
name: contribute
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: Suggesting content improvements
|
||||
slug: suggest-improvements
|
||||
content_type: concept
|
||||
weight: 10
|
||||
card:
|
||||
name: contribute
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
If you notice an issue with Kubernetes documentation or have an idea for new content, then open an issue. All you need is a [GitHub account](https://github.com/join) and a web browser.
|
||||
|
||||
In most cases, new work on Kubernetes documentation begins with an issue in GitHub. Kubernetes contributors
|
||||
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 文档中存在问题或者你有一个关于新内容的想法，可以考虑
|
||||
提出一个问题（issue）。你只需要具有 [GitHub 账号](https://github.com/join)和 Web
|
||||
浏览器就可以完成这件事。
|
||||
|
||||
在大多数情况下，Kubernetes 文档的新工作都是开始于 GitHub 上的某个问题。
|
||||
Kubernetes 贡献者会审阅这些问题并根据需要对其分类、打标签。
|
||||
接下来，你或者别的 Kubernetes 社区成员就可以发起一个带有变更的拉取请求，
|
||||
以解决这一问题。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Opening an issue
|
||||
|
||||
If you want to suggest improvements to existing content or notice an error, then open an issue.
|
||||
|
||||
1. Go to the bottom of the page and click the **Create an Issue** button. This redirects you
|
||||
to a GitHub issue page pre-populated with some headers.
|
||||
2. Describe the issue or suggestion for improvement. Provide as many details as you can.
|
||||
3. Click **Submit new issue**.
|
||||
|
||||
After submitting, check in on your issue occasionally or turn on GitHub notifications.
|
||||
Reviewers and other community members might ask questions before
|
||||
they can take action on your issue.
|
||||
-->
|
||||
## 创建问题 {#opening-an-issue}
|
||||
|
||||
如果你希望就改进已有内容提出建议或者在文档中发现了错误，请创建一个问题（issue）。
|
||||
|
||||
1. 滚动到页面底部，点击“报告问题”按钮。浏览器会重定向到一个 GitHub 问题页面，其中
|
||||
包含了一些预先填充的内容。
|
||||
1. 请描述遇到的问题或关于改进的建议。尽可能提供细节信息。
|
||||
1. 点击 **提交新问题**.
|
||||
|
||||
提交之后，偶尔查看一下你所提交的问题，或者开启 GitHub 通知。
|
||||
评审人（reviewers）和其他社区成员可能在针对所提问题采取行动之前，问一些问题。
|
||||
|
||||
<!--
|
||||
## Suggesting new content
|
||||
|
||||
If you have an idea for new content, but you aren't sure where it should go, you can
|
||||
still file an issue. Either:
|
||||
|
||||
- Choose an existing page in the section you think the content belongs in and click **Create an issue**.
|
||||
- Go to [GitHub](https://github.com/kubernetes/website/issues/new/) and file the issue directly.
|
||||
-->
|
||||
## 关于新内容的建议
|
||||
|
||||
如果你对新内容有想法，但是你有不确定这些内容应该放在哪里，你仍可以提出问题。
|
||||
|
||||
- 在预期的节区中选择一个现有页面，点击 **创建 issue**.
|
||||
- 前往 [GitHub Issues 页面](https://github.com/kubernetes/website/issues/new/)，
|
||||
直接记录问题。
|
||||
|
||||
<!--
|
||||
## How to file great issues
|
||||
|
||||
Keep the following in mind when filing an issue:
|
||||
|
||||
- Provide a clear issue description. Describe what specifically is missing, out of date,
|
||||
wrong, or needs improvement.
|
||||
- Explain the specific impact the issue has on users.
|
||||
- Limit the scope of a given issue to a reasonable unit of work. For problems
|
||||
with a large scope, break them down into smaller issues. For example, "Fix the security docs"
|
||||
is too broad, but "Add details to the 'Restricting network access' topic" is specific enough
|
||||
to be actionable.
|
||||
- Search the existing issues to see if there's anything related or similar to the
|
||||
new issue.
|
||||
- If the new issue relates to another issue or pull request, refer to it
|
||||
either by its full URL or by the issue or pull request number prefixed
|
||||
with a `#` character. For example, `Introduced by #987654`.
|
||||
- Follow the [Code of Conduct](/community/code-of-conduct/). Respect your
|
||||
fellow contributors. For example, "The docs are terrible" is not
|
||||
helpful or polite feedback.
|
||||
-->
|
||||
|
||||
## 如何更好地记录问题
|
||||
|
||||
在记录问题时，请注意以下事项：
|
||||
|
||||
- 提供问题的清晰描述，描述具体缺失的内容、过期的内容、错误的内容或者需要改进的文字。
|
||||
- 解释该问题对用户的特定影响。
|
||||
- 将给定问题的范围限定在一个工作单位范围内。如果问题牵涉的领域较大，可以将其分解为多个
|
||||
小一点的问题。例如："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" 就是无用且无礼的反馈。
|
||||
|
||||
Reference in New Issue
Block a user