Merge pull request #27654 from tengqm/zh-sync-contribute
[zh] Resync contribute section for Chinese localization
This commit is contained in:
Kubernetes Prow Robot
GitHub
commit
c765642679
|
|
@ -359,9 +359,9 @@ For weekly meetings, copypaste the previous week's notes into the "Past meetings
|
|||
<!--
|
||||
### Recording meetings on Zoom
|
||||
|
||||
When you’re ready to start the recording, click Record to Cloud.
|
||||
When you're ready to start the recording, click Record to Cloud.
|
||||
|
||||
When you’re ready to stop recording, click Stop.
|
||||
When you're ready to stop recording, click Stop.
|
||||
|
||||
The video uploads automatically to YouTube.
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ First, consult the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/p
|
|||
|
||||
### Fork and clone the repo
|
||||
|
||||
First, [create your own fork](/docs/contribute/start/#improve-existing-content) of the [kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
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.
|
||||
-->
|
||||
### 找到两个字母的语言代码
|
||||
|
||||
|
|
@ -122,11 +122,11 @@ The `@kubernetes/sig-docs-**-reviews` team automates review assignment for new P
|
|||
`@kubernetes/sig-docs-**-reviews` 团队被自动分派新 PR 的审阅任务。
|
||||
|
||||
<!--
|
||||
Members of `@kubernetes/website-maintainers` can create new development branches to coordinate translation efforts.
|
||||
Members of `@kubernetes/website-maintainers` can create new localization branches to coordinate translation efforts.
|
||||
|
||||
Members of `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-maintainers` 成员可以创建新的本地化分支来协调翻译工作。
|
||||
|
||||
`@kubernetes/website-milestone-maintainers` 成员可以使用 `/milestone`
|
||||
[Prow 命令](https://prow.k8s.io/command-help) 为 issues 或 PR 设定里程碑。
|
||||
|
|
@ -394,26 +394,40 @@ To ensure accuracy in grammar and meaning, members of your localization team sho
|
|||
<!--
|
||||
### Source files
|
||||
|
||||
Localizations must be based on the English files from the most recent release, {{< latest-version >}}.
|
||||
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 the most recent release:
|
||||
To find source files for your target version:
|
||||
|
||||
1. Navigate to the Kubernetes website repository at https://github.com/kubernetes/website.
|
||||
2. Select the `release-1.X` branch for the most recent version.
|
||||
2. Select a branch for your target version from the following table:
|
||||
Target version | Branch
|
||||
-----|-----
|
||||
Next version | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})
|
||||
Latest version | [`master`](https://github.com/kubernetes/website/tree/master)
|
||||
Previous version | `release-*.**`
|
||||
|
||||
The latest version is {{< latest-version >}}, so the most recent release branch is [`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}}).
|
||||
The `master` branch holds content for the current release `{{< latest-version >}}`. The release team will create `{{< release-branch >}}` branch shortly before the next release: v{{< skew nextMinorVersion >}}.
|
||||
-->
|
||||
### 源文件
|
||||
|
||||
本地化必须基于最新版本 {{< latest-version >}} 中的英文文件。
|
||||
本地化必须基于本地化团队所针对的特定发行版本中的英文文件。
|
||||
每个本地化团队可以决定要针对哪个发行版本，在下文中称作目标版本（target version）。）
|
||||
|
||||
要查找最新版本的源文件：
|
||||
要查找你的目标版本的源文件：
|
||||
|
||||
1. 导航到 Kubernetes website 仓库，网址为 https://github.com/kubernetes/website。
|
||||
1. 选择最新版本的 `release-1.X` 分支。
|
||||
2. 从下面的表格中选择你的目标版本分支：
|
||||
|
||||
最新版本是 {{< latest-version >}}，所以最新的发行分支是
|
||||
[`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}})。
|
||||
目标版本 | 分支
|
||||
-----|-----
|
||||
下一个版本 | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})
|
||||
最新版本 | [`master`](https://github.com/kubernetes/website/tree/master)
|
||||
之前的版本 | `release-*.**`
|
||||
|
||||
`master` 分支中保存的是当前发行版本 `{{< latest-version >}}` 的内容。
|
||||
发行团队会在下一个发行版本 v{{< skew nextMinorVersion >}} 出现之前创建
|
||||
`{{< release-branch >}}` 分支。
|
||||
|
||||
<!--
|
||||
### Site strings in i18n/
|
||||
|
|
@ -460,28 +474,29 @@ Some language teams have their own language-specific style guide and glossary. F
|
|||
<!--
|
||||
## Branching strategy
|
||||
|
||||
Because localization projects are highly collaborative efforts, we encourage teams to work in shared development branches.
|
||||
Because localization projects are highly collaborative efforts, we encourage teams to work in shared localization branches.
|
||||
|
||||
To collaborate on a development branch:
|
||||
To collaborate on a localization branch:
|
||||
-->
|
||||
### 分支策略
|
||||
因为本地化项目是高度协同的工作，所以我们鼓励团队基于共享的开发分支工作。
|
||||
### 分支策略 {#branching-strategy}
|
||||
|
||||
在开发分支上协作需要：
|
||||
因为本地化项目是高度协同的工作，所以我们鼓励团队基于共享的本地化分支工作。
|
||||
|
||||
在本地化分支上协作需要：
|
||||
|
||||
<!--
|
||||
1. A team member of [@kubernetes/sig-docs-l10n-admins](https://github.com/orgs/kubernetes/teams/sig-docs-l10n-admins) opens a development branch from a source branch on https://github.com/kubernetes/website.
|
||||
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 `sig-docs-l10n-admins` team when you [added your localization team](#add-your-localization-team-in-github) to the `kubernetes/org` repository.
|
||||
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 development branch `dev-1.12-de.1` directly against the k/website repository, based on the source branch for Kubernetes v1.12.
|
||||
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 原有分支新建一个开发分支。
|
||||
中的团队成员从 https://github.com/kubernetes/website 原有分支新建一个本地化分支。
|
||||
当你给 `kubernetes/org` 仓库[添加你的本地化团队](#add-your-localization-team-in-github)时，
|
||||
你的团队批准人便加入了 `@kubernetes/website-maintainers` 团队。
|
||||
|
||||
|
|
@ -490,52 +505,72 @@ To collaborate on a development branch:
|
|||
`dev-<source version>-<language code>.<team milestone>`
|
||||
|
||||
例如，一个德语本地化团队的批准人基于 Kubernetes v1.12 版本的源分支，
|
||||
直接新建了 k/website 仓库的开发分支 `dev-1.12-de.1`。
|
||||
直接新建了 k/website 仓库的本地化分支 `dev-1.12-de.1`。
|
||||
|
||||
<!--
|
||||
2. Individual contributors open feature branches based on the development branch.
|
||||
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 development branch.
|
||||
3. Approvers review and merge feature branches into the localization branch.
|
||||
|
||||
4. Periodically, an approver merges the development branch to its source branch by opening and approving a new pull request. Be sure to squash the commits before approving the pull request.
|
||||
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. 个人贡献者基于开发分支创建新的特性分支
|
||||
2. 个人贡献者基于本地化分支创建新的特性分支
|
||||
|
||||
例如，一个德语贡献者新建了一个拉取请求，并将 `username:local-branch-name` 更改为 `kubernetes:dev-1.12-de.1`。
|
||||
|
||||
3. 批准人审查功能分支并将其合并到开发分支中。
|
||||
3. 批准人审查功能分支并将其合并到本地化分支中。
|
||||
|
||||
4. 批准人会定期发起并批准新的 PR，将开发分支合并到其源分支。在批准 PR 之前，请确保先 squash commits。
|
||||
4. 批准人会定期发起并批准新的 PR，将本地化分支合并到其源分支。
|
||||
在批准 PR 之前，请确保先 squash commits。
|
||||
|
||||
<!--
|
||||
Repeat steps 1-4 as needed until the localization is complete. For example, subsequent German development branches would be: `dev-1.12-de.2`, `dev-1.12-de.3`, etc.
|
||||
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，直到完成本地化工作。例如，随后的德语开发分支将是：
|
||||
根据需要重复步骤 1-4，直到完成本地化工作。例如，随后的德语本地化分支将是：
|
||||
`dev-1.12-de.2`、`dev-1.12-de.3`，等等。
|
||||
|
||||
<!--
|
||||
Teams must merge localized content into the same release branch from which the content was sourced. For example, a development branch sourced from {{< release-branch >}} must be based on {{< release-branch >}}.
|
||||
Teams must merge localized content into the same branch from which the content was sourced.
|
||||
|
||||
An approver must maintain a development branch by keeping it current with its source branch and resolving merge conflicts. The longer a development branch stays open, the more maintenance it typically requires. Consider periodically merging development branches and opening new ones, rather than maintaining one extremely long-running development branch.
|
||||
For example:
|
||||
|
||||
- a localization branch sourced from `master` must be merged into `master`.
|
||||
- a localization branch sourced from `release-1.19` must be merged into `release-1.19`.
|
||||
|
||||
{{< note >}}
|
||||
If your localization branch was created from `master` branch but it is not merged into `master` before new release branch `{{< release-branch >}}` created, merge it into both `master` 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 >}}
|
||||
-->
|
||||
团队必须将本地化内容合入到发布分支中，该发布分支也正是内容的来源。
|
||||
例如，源于 {{< release-branch >}} 的开发分支必须基于 {{< release-branch >}}。
|
||||
团队必须将本地化内容合入到发布分支中，该发布分支是内容的来源。
|
||||
|
||||
approver 必须通过使开发分支与源分支保持最新并解决合并冲突来维护开发分支。
|
||||
开发分支的存在时间越长，通常需要的维护工作就越多。
|
||||
考虑定期合并开发分支并新建分支，而不是维护一个持续时间很长的开发分支。
|
||||
例如：
|
||||
|
||||
- 源于 `master` 分支的本地化分支必须被合并到 `master`。
|
||||
- 源于 `release-1.19` 的本地化分支必须被合并到 `release-1.19`。
|
||||
|
||||
如果你的本地化分支是基于 `master` 分支创建的，但最终没有在新的发行
|
||||
分支 `{{< release-branch >}}` 被创建之前合并到 `master` 中，需要将其
|
||||
同时将其合并到 `master` 和新的发行分支 `{{< 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 development branch and the current development 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/master/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/master/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 development branch and merge pull requests, anyone can open a pull request for a new development branch. No special permissions are required.
|
||||
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/master/scripts#upstream_changespy)
|
||||
对于检查对某个文件的变更很有用。
|
||||
[`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/master/scripts#diff_l10n_branchespy)
|
||||
可以用来为某个特定本地化分支创建过时文件的列表。
|
||||
|
||||
在团队每个里程碑的起点，创建一个 issue 来比较先前的开发分支和当前的开发分支之间的上游变化很有帮助。
|
||||
虽然只有批准人才能创建新的开发分支并合并 PR，但任何人都可以为新的开发分支提交一个拉取请求（PR）。
|
||||
不需要特殊权限。
|
||||
虽然只有批准人才能创建新的本地化分支并合并 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).
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ Kubernetes 博客用于项目发布新功能特性、社区报告以及其他一
|
|||
### 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](https://kubernetes.io/docs/contribute/style/content-guide/#what-s-allowed) for what is typically allowed on Kubernetes properties.
|
||||
- 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.
|
||||
-->
|
||||
|
|
@ -100,8 +100,8 @@ Kubernetes 博客用于项目发布新功能特性、社区报告以及其他一
|
|||
Kubernetes 博客上阅读的内容。
|
||||
<!--
|
||||
- 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/master/LICENSE) for the blog does allow commercial use of the content for commercial purposes, just not the other way around.
|
||||
- The official blog is not for repurposing existing content from a third party as new content.
|
||||
- The [license](https://github.com/kubernetes/website/blob/master/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.
|
||||
|
|
@ -144,7 +144,7 @@ SIG Docs [博客子项目](https://github.com/kubernetes/community/tree/master/s
|
|||
|
||||
要提交博文，你可以遵从以下指南：
|
||||
<!--
|
||||
- [Open a pull request](/docs/contribute/new-content/new-content/#fork-the-repo) with a new blog post. New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts) directory.
|
||||
- [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/master/content/en/blog/_posts) directory.
|
||||
|
||||
- Ensure that your blog post follows the correct naming conventions and the following frontmatter (metadata) information:
|
||||
|
||||
|
|
|
|||
|
|
@ -149,15 +149,14 @@ Beta 或 Stable）、负责实现该特性的 SIG 和个人、是否该特性需
|
|||
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 and
|
||||
just because a feature is not marked as needing docs doesn't mean it doesn't
|
||||
need them.
|
||||
- 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
|
||||
|
|
@ -185,24 +184,28 @@ SIG Docs 一起工作，确保这一新功能在发行之前已经为之撰写
|
|||
<!--
|
||||
### Open a placeholder PR
|
||||
|
||||
1. Open a pull request against the
|
||||
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.
|
||||
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. Use the Prow command `/milestone {{< skew nextMinorVersion >}}` to
|
||||
assign the PR to the relevant milestone. This alerts the docs person managing
|
||||
this release that the feature docs are coming.
|
||||
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 >}}`
|
||||
分支提交一个 PR，其中包含较少的、待以后慢慢补齐的提交内容。
|
||||
分支提交一个**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. 使用 Prow 命令 `/milestone {{< skew nextMinorVersion >}}`
|
||||
将 PR指派到对应的里程碑。这样做会提醒负责管理对应发行版本的文档团队成员，有
|
||||
新的功能特性要合并到将来版本。
|
||||
1. 在对应的 [kubernetes/enhancements](https://github.com/kubernetes/enhancements)
|
||||
issue 上添加评论，附上新 PR 的链接以便管理此发行版本的人员能够得到通知，
|
||||
了解特性的文档正在被撰写，在新的发行版本中要跟踪其进展。
|
||||
|
||||
<!--
|
||||
If your feature does not need
|
||||
|
|
@ -219,7 +222,9 @@ milestone.
|
|||
<!--
|
||||
### PR ready for review
|
||||
|
||||
When ready, populate your placeholder PR with feature documentation.
|
||||
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.
|
||||
|
|
@ -227,15 +232,13 @@ 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.
|
||||
|
||||
If your feature needs documentation and the first draft content is not
|
||||
received, the feature may be removed from the milestone.
|
||||
Use their suggestions to get the content to a release ready state.
|
||||
-->
|
||||
### PR 准备好评阅
|
||||
### PR 准备好评阅 {#pr-ready-for-review}
|
||||
|
||||
时机成熟时，你可以在你的占位 PR 中完成功能特性文档。
|
||||
时机成熟时，你可以在你的占位 PR 中完成功能特性文档，并将 PR 的状态
|
||||
从草案状态更改为 **Ready for Review**。要将一个拉取请求标记为预备
|
||||
评阅，转到页面的 merge 框，点击 **Ready for review**。
|
||||
|
||||
尽可能为功能特性提供详尽文档以及使用说明。如果你需要文档组织方面的帮助，请
|
||||
在 `#sig-docs` Slack 频道中提问。
|
||||
|
|
@ -244,8 +247,22 @@ received, the feature may be removed from the milestone.
|
|||
为了确保技术准确性，内容可能还需要相应 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
|
||||
|
|
@ -254,20 +271,10 @@ If your PR has not yet been merged into the `dev-{{< skew nextMinorVersion >}}`
|
|||
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.
|
||||
|
||||
If your feature is an Alpha 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. If your feature is moving out of Alpha, make sure to
|
||||
remove it from that table.
|
||||
-->
|
||||
### 所有 PR 均经过评审且合并就绪
|
||||
### 所有 PR 均经过评审且合并就绪 {#all-prs-reviewd-and-ready-to-merge}
|
||||
|
||||
如果你的 PR 在发行截止日期之前尚未合并到 `dev-{{< skew nextMinorVersion >}}` 分支，
|
||||
请与负责管理该发行版本的文档团队成员一起合作，在截止期限之前将其合并。
|
||||
如果功能特性需要文档，而文档并未就绪，该特性可能会被从里程碑中去除。
|
||||
|
||||
如果你的功能特性是 Alpha 阶段，并且受到某个特性门控的保护，在你的 PR 中，请确保将
|
||||
该特性门控添加到
|
||||
[Alpha/Beta 特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features)
|
||||
表格中。
|
||||
如果你的功能特性不再是 Alpha 阶段，请确保特性门控状态得到更新。
|
||||
|
|
|
|||
|
|
@ -11,11 +11,11 @@ weight: 20
|
|||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
SIG Docs [approvers](/docs/contribute/participating/roles-and-responsibilites/#approvers) take week-long shifts [managing pull requests](https://github.com/kubernetes/website/wiki/PR-Wranglers) for the repository.
|
||||
SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilites/#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/participating/#approvers)们每周轮流负责
|
||||
SIG Docs 的[批准人（Approvers）](/zh/docs/contribute/participate/roles-and-responsibilites/#approvers)们每周轮流负责
|
||||
[管理仓库的 PRs](https://github.com/kubernetes/website/wiki/PR-Wranglers)。
|
||||
|
||||
本节介绍 PR 管理者的职责。关于如何提供较好的评审意见，可参阅
|
||||
|
|
@ -94,6 +94,7 @@ These queries exclude localization PRs. All queries are against the main 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)：
|
||||
|
|
@ -108,12 +109,28 @@ These queries exclude localization PRs. All queries are against the main branch
|
|||
列举针对主分支的、没有明确合并障碍的 PR。
|
||||
在浏览 PR 时，可以将 "XS" 尺寸标签更改为 "S"、"M"、"L"、"XL"、"XXL"。
|
||||
|
||||
- [非主分支的 PR](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3Alanguage%2Fen+-base%3Amaster)：
|
||||
- [非主分支的 PR](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3Alanguage%2Fen+-base%3Amaster): 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.
|
||||
如果 PR 针对 `dev-` 分支，则表示它适用于即将发布的版本。
|
||||
请添加带有 `/assign @<负责人的 github 账号>`，将其指派给
|
||||
[发行版本负责人](https://github.com/kubernetes/sig-release/tree/master/release-team)。
|
||||
[发行版本负责人](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
|
||||
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ Members can:
|
|||
- 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, simply commenting "LGTM" works too!
|
||||
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
|
||||
|
|
@ -98,10 +98,11 @@ Members can:
|
|||
- 执行[任何人](#anyone)节区所列举操作
|
||||
- 使用 `/lgtm` 评论添加 LGTM (looks good to me（我觉得可以）) 标签到某个 PR
|
||||
|
||||
{{< note >}}
|
||||
使用 `/lgtm` 会触发自动化机制。如果你希望提供不拘约束力的批准意见，
|
||||
直接回复 "LGTM" 也是可以的。
|
||||
{{< /note >}}
|
||||
{{< note >}}
|
||||
使用 `/lgtm` 会触发自动化机制。如果你希望提供不拘约束力的批准意见，
|
||||
直接回复 "LGTM" 也是可以的。
|
||||
{{< /note >}}
|
||||
|
||||
- 利用 `/hold` 评论来阻止某个 PR 被合并
|
||||
- 使用 `/assign` 评论为某个 PR 指定评审人
|
||||
- 对 PR 提供非约束性的评审意见
|
||||
|
|
|
|||
|
|
@ -430,4 +430,3 @@ https://github.com/kubernetes/kubernetes/issues.
|
|||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,6 @@ title: 例子 #1
|
|||
<!--
|
||||
title: Example #1
|
||||
-->
|
||||
|
||||
<!--
|
||||
This is an **example** content file inside the **includes** leaf bundle.
|
||||
-->
|
||||
|
|
@ -17,4 +16,3 @@ Included content files can also contain shortcodes.
|
|||
{{< note >}}
|
||||
被包含的内容文件也可以包含短代码。
|
||||
{{< /note >}}
|
||||
|
||||
|
|
|
|||
|
|
@ -79,74 +79,82 @@ Kubernetes 文档已经被翻译为多个语种
|
|||
|
||||
### Use upper camel case for API objects
|
||||
|
||||
When you refer specifically to interacting with an API object, use [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also
|
||||
known as Pascal Case. When you are generally discussing an API object, use [sentence-style capitalization]
|
||||
(https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).
|
||||
When you refer specifically to interacting with an API object, use [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as Pascal Case. You may see different capitalization, such as "configMap", in the [API reference](/docs/reference/kubernetes-api/). When writing general documentation, it's better to use upper camel case, calling it "ConfigMap" instead.
|
||||
|
||||
Don't split the API object name into separate words. For example, use
|
||||
PodTemplateList, not Pod Template List.
|
||||
When you are generally discussing an API object, use [sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).
|
||||
|
||||
Refer to API objects without saying "object," unless omitting "object"
|
||||
leads to an awkward construction.
|
||||
You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.
|
||||
|
||||
Don't split an API object name into separate words. For example, use PodTemplateList, not Pod Template List.
|
||||
|
||||
The following examples focus on capitalization. For more information about formatting API object names, review the related guidance on [Code Style](#code-style-inline-code).
|
||||
-->
|
||||
## 文档格式标准 {#documentation-formatting-standards}
|
||||
|
||||
### 对 API 对象使用大写驼峰式命名法 {#use-upper-camel-case-for-api-objects}
|
||||
|
||||
当你与指定的 API 对象进行交互时，使用 [大写驼峰式命名法](https://en.wikipedia.org/wiki/Camel_case)，
|
||||
也被称为帕斯卡拼写法.
|
||||
通常在讨论 API 对象时，使用
|
||||
[句子式大写](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).
|
||||
当你与指定的 API 对象进行交互时，使用 [大写驼峰式命名法](https://en.wikipedia.org/wiki/Camel_case)，也被称为帕斯卡拼写法（PascalCase）.
|
||||
你可能在 [API 参考](/docs/reference/kubernetes-api/) 中看到不同的大小写形式，
|
||||
例如 "configMap"。在一般性的文档中，最好使用大写驼峰形式，将之称作 "ConfigMap"。
|
||||
|
||||
在一般性地讨论 API 对象时，使用
|
||||
[句子式大写](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization)。
|
||||
|
||||
你可以使用“资源”、“API”或者“对象”这类词汇来进一步在句子中明确所指的是
|
||||
一个 Kubernetes 资源类型。
|
||||
|
||||
不要将 API 对象的名称切分成多个单词。例如，使用 PodTemplateList，不要
|
||||
使用 Pod Template List。
|
||||
|
||||
引用 API 对象时不必强调 “object（对象）”，除非省略“object（object）”
|
||||
会使得文字读起来很别扭。
|
||||
下面的例子关注的是大小写问题。关于如何格式化 API 对象的名称，
|
||||
有关详细细节可参考相关的[代码风格](#code-style-inline-code)指南。
|
||||
|
||||
<!--
|
||||
{{< table caption = "Do and Don't - API objects" >}}
|
||||
{{< table caption = "Do and Don't - Use Pascal case for API objects" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
The Pod has two containers. | The pod has two containers.
|
||||
The HorizontalPodAutoscaler is responsible for ... | The HorizontalPodAutoscaler object is responsible for ...
|
||||
A PodList is a list of Pods. | A Pod List is a list of pods.
|
||||
The two ContainerPorts ... | The two ContainerPort objects ...
|
||||
The two ContainerStateTerminated objects ... | The two ContainerStateTerminateds ...
|
||||
The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ...
|
||||
A PodList object is a list of pods. | A Pod List object is a list of pods.
|
||||
The Volume object contains a `hostPath` field. | The volume object contains a hostPath field.
|
||||
Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace.
|
||||
For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API.
|
||||
{{< /table >}}
|
||||
-->
|
||||
{{< table caption = "关于 API 对象的约定" >}}
|
||||
{{< table caption = "使用 Pascal 风格大小写来给出 API 对象的约定" >}}
|
||||
可以 | 不可以
|
||||
:--| :-----
|
||||
Pod 有两个容器 | pod 中有两个容器
|
||||
此 HorizontalPodAutoscaler 负责... | 此 HorizontalPodAutoscaler 对象负责 ...
|
||||
PodList 是 Pod 的列表 | Pod List 是 pods 的列表
|
||||
这两个 ContainerPorts ... | 这两个 ContainerPort 对象 ...
|
||||
这两个 ContainerStateTerminated 对象 ... | 这两个 ContainerStateTerminateds ...
|
||||
该 HorizontalPodAutoscaler 负责... | 该 HorizontalPodAutoscaler 负责...
|
||||
每个 PodList 是一个 Pod 组成的列表。 | 每个 Pod List 是一个由 pods 组成的列表。
|
||||
该 Volume 对象包含一个 `hostPath` 字段。 | 此卷对象包含一个 hostPath 字段。
|
||||
每个 ConfigMap 对象都是某个名字空间的一部分。| 每个 configMap 对象是某个名字空间的一部分。
|
||||
要管理机密数据，可以考虑使用 Secret API。 | 要管理机密数据，可以考虑使用秘密 API。
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
Use angle brackets for placeholders. Tell the reader what a placeholder
|
||||
represents.
|
||||
represents, for example:
|
||||
|
||||
1. Display information about a Pod:
|
||||
Display information about a Pod:
|
||||
|
||||
kubectl describe pod <pod-name> -n <namespace>
|
||||
```shell
|
||||
kubectl describe pod <pod-name> -n <namespace>
|
||||
```
|
||||
|
||||
If the namespace of the pod is `default`, you can omit the '-n' parameter.
|
||||
If the namespace of the pod is `default`, you can omit the '-n' parameter.
|
||||
-->
|
||||
### 在占位符中使用尖括号
|
||||
|
||||
在占位符中使用尖括号，并让读者知道其中代表的事物。例如：
|
||||
|
||||
1. 显示 Pod 信息：
|
||||
显示 Pod 信息：
|
||||
|
||||
kubectl describe pod <pod-名称> -n <名字空间>
|
||||
|
||||
如果名字空间被忽略，默认为 `default`，你可以忽略 '-n' 参数。
|
||||
```shell
|
||||
kubectl describe pod <pod-名称> -n <名字空间>
|
||||
```
|
||||
|
||||
如果名字空间被忽略，默认为 `default`，你可以忽略 '-n' 参数。
|
||||
|
||||
<!--
|
||||
### Use bold for user interface elements
|
||||
|
|
@ -236,13 +244,13 @@ document, use the backtick (`` ` ``).
|
|||
-->
|
||||
## 行间代码格式 {#inline-code-formatting}
|
||||
|
||||
### 为行间代码、命令与 API 对象使用代码样式
|
||||
### 为行间代码、命令与 API 对象使用代码样式 {#code-style-inline-code}
|
||||
|
||||
对于 HTML 文档中的行间代码，使用 `<code>` 标记。
|
||||
在 Markdown 文档中，使用反引号（`` ` ``）。
|
||||
|
||||
<!--
|
||||
{{< table caption = "Do and Don't - Use code style for inline code and commands" >}}
|
||||
{{< table caption = "Do and Don't - Use code style for inline code, commands and API objects" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod.
|
||||
|
|
@ -256,7 +264,7 @@ Use meaningful variable names that have a context. | Use variable names such as
|
|||
Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.
|
||||
{{< /table >}}
|
||||
-->
|
||||
{{< table caption = "行间代码和命令约定" >}}
|
||||
{{< table caption = "行间代码、命令和 API 对象约定" >}}
|
||||
可以 | 不可以
|
||||
:--| :-----
|
||||
`kubectl run` 命令会创建一个 `Pod` | "kubectl run" 命令会创建一个 pod。
|
||||
|
|
@ -409,12 +417,16 @@ kubectl get pods | $ kubectl get pods
|
|||
|
||||
Verify that the pod is running on your chosen node:
|
||||
|
||||
kubectl get pods --output=wide
|
||||
```shell
|
||||
kubectl get pods --output=wide
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
```console
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
```
|
||||
-->
|
||||
### 将命令和输出分开
|
||||
|
||||
|
|
@ -422,12 +434,16 @@ The output is similar to this:
|
|||
|
||||
验证 Pod 已经在你所选的节点上运行：
|
||||
|
||||
kubectl get pods --output=wide
|
||||
```shell
|
||||
kubectl get pods --output=wide
|
||||
```
|
||||
|
||||
输出类似于：
|
||||
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
```console
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
```
|
||||
|
||||
<!--
|
||||
### Versioning Kubernetes examples
|
||||
|
|
@ -531,17 +547,17 @@ Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create d
|
|||
|
||||
2. Use the following syntax to apply a style:
|
||||
|
||||
```
|
||||
{{</* note */>}}
|
||||
No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
|
||||
{{</* /note */>}}
|
||||
```
|
||||
```none
|
||||
{{</* note */>}}
|
||||
No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
The output is:
|
||||
The output is:
|
||||
|
||||
{{< note >}}
|
||||
The prefix you choose is the same text for the tag.
|
||||
{{< /note >}}
|
||||
{{< note >}}
|
||||
The prefix you choose is the same text for the tag.
|
||||
{{< /note >}}
|
||||
-->
|
||||
|
||||
## 短代码（Shortcodes） {#shortcodes}
|
||||
|
|
@ -553,17 +569,17 @@ Hugo [短代码（Shortcodes）](https://gohugo.io/content-management/shortcodes
|
|||
1. 将要突出显示的文字用短代码的开始和结束形式包围。
|
||||
2. 使用下面的语法来应用某种样式：
|
||||
|
||||
```
|
||||
{{</* note */>}}
|
||||
不需要前缀；短代码会自动添加前缀（注意：、小心：等）
|
||||
{{</* /note */>}}
|
||||
```
|
||||
```none
|
||||
{{</* note */>}}
|
||||
不需要前缀；短代码会自动添加前缀（注意：、小心：等）
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
输出的样子是：
|
||||
输出的样子是：
|
||||
|
||||
{{< note >}}
|
||||
你所选择的标记决定了文字的前缀。
|
||||
{{< /note >}}
|
||||
{{< note >}}
|
||||
你所选择的标记决定了文字的前缀。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Note
|
||||
|
|
@ -807,7 +823,7 @@ The output is:
|
|||
|
||||
1. Prepare the batter, and pour into springform pan.
|
||||
|
||||
{{< note >}}Grease the pan for best results.{{< /note >}}
|
||||
{{< note >}}Grease the pan for best results.{{< /note >}}
|
||||
|
||||
1. Bake for 20-25 minutes or until set.
|
||||
-->
|
||||
|
|
@ -830,7 +846,7 @@ The output is:
|
|||
|
||||
1. 预热到 350˚F
|
||||
1. 准备好面糊，倒入烘烤盘
|
||||
{{< note >}}给盘子抹上油可以达到最佳效果。{{< /note >}}
|
||||
{{< note >}}给盘子抹上油可以达到最佳效果。{{< /note >}}
|
||||
1. 烘烤 20 到 25 分钟，或者直到满意为止。
|
||||
|
||||
<!--
|
||||
|
|
@ -941,12 +957,13 @@ Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](
|
|||
|
||||
<!--
|
||||
### Lists
|
||||
|
||||
Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list.
|
||||
Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.
|
||||
|
||||
- End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.
|
||||
- End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.
|
||||
|
||||
{{< note >}} Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.{{< /note >}}
|
||||
{{< note >}} Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.{{< /note >}}
|
||||
-->
|
||||
### 列表 {#lists}
|
||||
|
||||
|
|
@ -955,32 +972,34 @@ Website navigation links can also be marked up as list items; after all they are
|
|||
用户可以使用箭头键来上下移动，浏览列表中条目。
|
||||
网站导航链接也可以标记成列表条目，因为说到底他们也是一组相互关联的链接而已。
|
||||
|
||||
- 如果列表中一个或者多个条目是完整的句子，则在每个条目末尾添加句号。
|
||||
出于一致性考虑，一般要么所有条目要么没有条目是完整句子。
|
||||
- 如果列表中一个或者多个条目是完整的句子，则在每个条目末尾添加句号。
|
||||
出于一致性考虑，一般要么所有条目要么没有条目是完整句子。
|
||||
|
||||
{{< note >}} 编号列表如果是不完整的介绍性句子的一部分，可以全部用小写字母，并按照
|
||||
每个条目都是句子的一部分来看待和处理。{{< /note >}}
|
||||
{{< note >}}
|
||||
编号列表如果是不完整的介绍性句子的一部分，可以全部用小写字母，并按照
|
||||
每个条目都是句子的一部分来看待和处理。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
- Use the number one (`1.`) for ordered lists.
|
||||
- Use the number one (`1.`) for ordered lists.
|
||||
|
||||
- Use (`+`), (`*`), or (`-`) for unordered lists.
|
||||
- Use (`+`), (`*`), or (`-`) for unordered lists.
|
||||
|
||||
- Leave a blank line after each list.
|
||||
- Leave a blank line after each list.
|
||||
|
||||
- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
|
||||
- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
|
||||
|
||||
- List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.
|
||||
- List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.
|
||||
-->
|
||||
- 在编号列表中，使用数字一（`1.`）
|
||||
- 在编号列表中，使用数字 1（`1.`）
|
||||
|
||||
- 对非排序列表，使用加号（`+`）、星号（`*`）、或者减号（`-`）
|
||||
- 对非排序列表，使用加号（`+`）、星号（`*`）、或者减号（`-`）
|
||||
|
||||
- 在每个列表之后留一个空行
|
||||
- 在每个列表之后留一个空行
|
||||
|
||||
- 对于嵌套的列表，相对缩进四个空格（例如，⋅⋅⋅⋅）。
|
||||
- 对于嵌套的列表，相对缩进四个空格（例如，⋅⋅⋅⋅）。
|
||||
|
||||
- 列表条目可能包含多个段落。每个后续段落都要缩进或者四个空格或者一个制表符。
|
||||
- 列表条目可能包含多个段落。每个后续段落都要缩进或者四个空格或者一个制表符。
|
||||
|
||||
<!--
|
||||
### Tables
|
||||
|
|
@ -1009,7 +1028,7 @@ This section contains suggested best practices for clear, concise, and consisten
|
|||
{{< table caption = "Do and Don't - Use present tense" >}}
|
||||
Do | Don't
|
||||
This command starts a proxy. | This command will start a proxy.
|
||||
{{< /table >}}
|
||||
{{< /table >}}
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct
|
||||
meaning.
|
||||
|
|
@ -1180,6 +1199,20 @@ Avoid making promises or giving hints about the future. If you need to talk abou
|
|||
an alpha feature, put the text under a heading that identifies it as alpha
|
||||
information.
|
||||
|
||||
An exception to this rule is documentation about announced deprecations
|
||||
targeting removal in future versions. One example of documentation like this
|
||||
is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/).
|
||||
-->
|
||||
### 避免关于将来的陈述
|
||||
|
||||
要避免对将来作出承诺或暗示。如果你需要讨论的是 Alpha 功能特性，可以将相关文字
|
||||
放在一个单独的标题下，标示为 alpha 版本信息。
|
||||
|
||||
此规则的一个例外是对未来版本中计划移除的已废弃功能选项的文档。
|
||||
此类文档的例子之一是
|
||||
[已弃用 API 迁移指南](/docs/reference/using-api/deprecation-guide/)。
|
||||
|
||||
<!--
|
||||
### Avoid statements that will soon be out of date
|
||||
|
||||
Avoid words like "currently" and "new." A feature that is new today might not be
|
||||
|
|
@ -1191,10 +1224,6 @@ In version 1.4, ... | In the current version, ...
|
|||
The Federation feature provides ... | The new Federation feature provides ...
|
||||
{{< /table >}}
|
||||
-->
|
||||
### 避免关于将来的陈述
|
||||
|
||||
要避免对将来作出承诺或暗示。如果你需要讨论的是 Alpha 功能特性，可以将相关文字
|
||||
放在一个单独的标题下，标示为 alpha 版本信息。
|
||||
|
||||
### 避免使用很快就会过时的表达
|
||||
|
||||
|
|
@ -1208,8 +1237,37 @@ The Federation feature provides ... | The new Federation feature provides ...
|
|||
联邦功能特性提供 ... | 新的联邦功能特性提供 ...
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
### Avoid words that assume a specific level of understanding
|
||||
|
||||
Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value.
|
||||
|
||||
{{< table caption = "Do and Don't - Avoid insensitive words" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Include one command in ... | Include just one command in ...
|
||||
Run the container ... | Simply run the container ...
|
||||
You can easily remove ... | You can remove ...
|
||||
These simple steps ... | These steps ...
|
||||
{{< /table >}}
|
||||
-->
|
||||
### 避免使用隐含用户对某技术有一定理解的词汇
|
||||
|
||||
避免使用“只是”、“仅仅”、“简单”、“很容易地”、“很简单”这类词汇。
|
||||
这些词并没有提升文档的价值。
|
||||
|
||||
{{< table caption = "避免无意义词汇的注意事项" >}}
|
||||
可以 | 不可以
|
||||
:--| :-----
|
||||
在 ... 中包含一个命令 | 只需要在... 中包含一个命令
|
||||
运行容器 ... | 只需运行该容器...
|
||||
你可以很容易地移除... | 你可以移除...
|
||||
这些简单的步骤... | 这些步骤...
|
||||
{{< /table >}}
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* 了解[编写新主题](/zh/docs/contribute/style/write-new-topic/).
|
||||
* 了解[页面内容类型](/zh/docs/contribute/style/page-content-types/).
|
||||
* 了解[发起 PR](/zh/docs/contribute/new-content/open-a-pr/).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue