whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Switch language name 'zh' to 'zh-cn'

Browse Source 
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
2022-06-10 20:25:27 +08:00
parent 3d345b1816
commit c52818c03d
1347 changed files with 8 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/zh-cn/docs/contribute/new-content/_index.md
+200
View File
@@ -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)目录中包含了一些工具，
有助于使你的贡献过程更为顺畅。
content/zh-cn/docs/contribute/new-content/blogs-case-studies.md
+311
View File
@@ -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 请求。
content/zh-cn/docs/contribute/new-content/new-features.md
+280
View File
@@ -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 >}}` 分支，
请与负责管理该发行版本的文档团队成员一起合作，在截止期限之前将其合并。
如果功能特性需要文档，而文档并未就绪，该特性可能会被从里程碑中去除。
content/zh-cn/docs/contribute/new-content/open-a-pr.md
+1024
View File
File diff suppressed because it is too large Load Diff