Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[zh] Update contribute & style-guide with main #881

Merged
merged 5 commits into from
May 12, 2022
Merged

[zh] Update contribute & style-guide with main #881

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
55fa645
feat: --20220511 update contribute with main
May 11, 2022
93e7514
feat: --20220511 update style-guide with main
May 11, 2022
6d486f5
fix: --20220511 correct symble & hyperlink
May 11, 2022
32b75f1
Update _index.md
Rocksnake May 11, 2022
38ed49a
fix: --20220512 correct links
May 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 61 additions & 46 deletions content/zh-cn/contribute/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,101 +6,116 @@ menu:
weight: 10
---

Cloud Native Glossary 内容存储在 [this GitHub repo](https://github.com/cncf/glossary) 中, 您可以在其中找到关于 glossary 的 [issues](https://github.com/cncf/glossary/issues), [PRs](https://github.com/cncf/glossary/pulls), 和 [discussions](https://github.com/cncf/glossary/discussions).
云原生词汇表的内容存储在这个 [GitHub 仓库](https://github.com/cncf/glossary)中，在这里你可以找到关于词汇表的 [议题](https://github.com/cncf/glossary/issues)、[PR](https://github.com/cncf/glossary/pulls) 和 [讨论](https://github.com/cncf/glossary/discussions) 的列表。

您可以通过三种方式做出贡献:
你可以通过四种方式做出贡献：

1) 提出新术语
2) 更新现有术语
3) 帮助翻译词汇表
1) [在现有的议题上工作](#在现有的议题上工作)
2) [提出新术语](#提出新术语)
3) [更新现有术语](#更新现有术语)
4) [云原生词汇表翻译帮助](#云原生词汇表翻译帮助)

## 加入 Glossary 社区!
如果您想定期投稿, 请考虑加入我们的每月词汇表工作组会议. 您可以在 [CNCF calendar](https://www.cncf.io/calendar/) 找到会议详情. 您还可以在 CNCF Slack 上的 #glossary 频道中与维护者和其他贡献者联系 — 期待美好相遇!
如果你想定期做出贡献，可以考虑加入我们每月的词汇工作组会议。你可以在 [CNCF 日历](https://www.cncf.io/calendar/) 中找到会议细节。你也可以在 CNCF Slack 的 [#glossary](https://cloud-native.slack.com/archives/C02TX20MQBB) 频道中与维护者和其他贡献者联系，我们很乐意见到你!

## 提出新术语
您可以提出一个新术语供其他人使用或自己创建一个新定义. 无论哪种方式, 您都将从创建问题开始(请注意, 您需要一个 GitHub 帐户来执行此操作).
## 在现有的议题上工作
进入云原生词汇表 GitHub 仓库的 [议题](https://github.com/cncf/glossary/issues)。在那里你会看到一个所有议题的列表。你可以通过标签来过滤（例如，English language, help needed, good first issue）。请注意，你需要一个 GitHub 账户来做这些事情。

![Issue 和 labels](/images/how-to/issue-and-labels.png)

确保你感兴趣的术语还没有分配给某人。这里你可以看到，前三个术语是可用的，而下一个术语已经被分配了：

![分配一个术语](/images/how-to/howto-04.png)

以下是针对尚未熟悉 GitHub 的人的分步指南. **如果你是 GitHub Pro 账户**, 请快速查看以确保您使用我们的问题模板、适当的命名约定、在 Slack 上声明 PR（否则我们可能会错过它）以及在哪里可以找到文件模板. 在开始之前, 请务必阅读 [Style Guide](/zh-cn/style-guide/).
一旦你找到了一个你想做的术语，就在议题中说出来。点击它并添加一个评论。

### 创建 issue
前往 [Glossary GitHub repo](https://github.com/cncf/glossary/issues) 并点击 "new issue".
![提出一个议题](/images/how-to/claiming-an-issue.png)

此外，请加入 CNCF Slack 的 [#glossary](https://cloud-native.slack.com/archives/C02TX20MQBB) 频道，让维护者知道你为一个新术语提出了一个议题（最好标记 <em>@Catherine Paganini</em>, <em>@jmo</em>, <em>@Seokho Son</em>, <em>@Jihoon Seo</em>, 和/或 <em>@iamnoah<em> 以确保他们不会错过它）。请注意，你一次只能认领一个术语。如果你想做多个术语，请在申请下一个术语之前完成前一个术语。

一旦他们把它分配给你，你就可以开始工作了。接下来的步骤，请参考 [提交一个新术语（创建一个PR）](#submitting-a-new-term)部分。

## 提出新术语
你可以提出一个新的术语让别人去研究，或者自己创造一个新的定义。无论哪种方式，你都要从创建一个议题开始。请注意，术语必须符合 [CNCF的云原生定义](https://github.com/cncf/toc/blob/main/DEFINITION.md)。唯一的例外是理解云原生概念所需的基础性术语。

![issues](/images/how-to/howto-01.png)
以下是为那些还不熟悉 GitHub 的人提供的分步指南。**如果你是 GitHub 的专业人员**，请**特别**看一下，确保你使用我们的议题模板，适当的命名惯例，在 Slack 上声明一个 PR（否则我们可能会错过它），以及在哪里找到文件模板。在开始之前，请确保阅读 [风格指南](/zh-cn/style-guide/)--谢谢!

您将看到各种模板. 要使用中文提出新术语, 请选择“Chinese Language Glossary Request”.
### 创建议题
进入云原生词汇表 GitHub 仓库的 [议题](https://github.com/cncf/glossary/issues)，点击 "new issue"。

![templates](/images/how-to/howto-02.png)
![议题](/images/how-to/howto-01.png)

添加您建议的单词并点击“submit new issue”. 如果您只是提出一个新术语, 那么您就完成了! 要处理它, 请按照以下步骤操作.
你会看到各种各样的模板。要提出一个中文的新术语，请选择 "Chinese Language Glossary Request"。

![new issue](/images/how-to/howto-03.png)
![模板](/images/how-to/english-issue-template.jpg)

请加入 CNCF Slack 上的 #glossary 频道, 让@Catherine Paganini、@jmo 和@Seokho Son 知道您已经提交了一个问题并希望解决它. 他们会将问题分配给您, 向其他所有人发出该术语已被占用的信号.
添加你所建议的词，回答下面的两个议题，勾选复选框，然后点击 "submit new issue"。如果你只是提出一个新词，你就完成了! 要进行工作，请按照接下来的步骤进行。

在这里, 您可以看到前三个术语可用, 而下一个术语已分配给某人.
### 分流你的议题
接下来，维护者将对该议题进行分流。这意味着他们将评估该术语是否应成为术语表的一部分（注意，不是每个术语都会被接受。术语应该是既定的、广泛使用的云计算原生术语）。

![assigning a term](/images/how-to/howto-04.png)
请让维护者知道你已经在 Slack 上提交了一个术语，否则他们可能会错过它。最好标记 <em>@Catherine Paganini</em>, <em>@jmo</em>, <em>@Seokho Son</em>, <em>@Jihoon Seo</em>, 和/或 <em>@iamnoah<em>。如果该术语被批准，并且你想从事该工作，他们会将其分配给你。

请注意, 您一次只能申请一个术语. 如果您想按多个条款工作, 请先完成一个条款, 然后再申请下一个术语.
请注意，你一次只能申请一个术语。如果你想做多个术语，请在申请下一个术语之前完成前一个术语。

### 提交新术语 (创建 PR)
### 提交新术语 (创建 PR) {#submitting-a-new-term}

在开始之前, 请阅读 [Style Guide](/zh-cn/style-guide/) — 它将帮助减少来回次数. 如样式指南中所述, 我们强烈建议从 Google 或 Word 文档开始.
在开始之前，请阅读 [风格指南](/zh-cn/style-guide/)--它将有助于减少来回奔波。正如风格指南中所述，我们强烈建议从 Google 或 Word 文档开始。

准备好提交术语后, 转到内容(在代码中)...
一旦术语准备好提交，进入 content（在代码下）...

![content](/images/how-to/howto-05.png)

...然后是“zh”(或您要提交的语言)...
...然后是 "zh-cn"（或你要提交的语言）...

![language folder](/images/how-to/howto-06.png)
![语言文件夹](/images/how-to/howto-06.png)

...然后选择 _TEMPLATE.md

![template](/images/how-to/howto-07.png)
![模板](/images/how-to/howto-07.png)

拷贝内容
复制内容...

![copy content](/images/how-to/howto-08.png)
![复制内容](/images/how-to/howto-08.png)

...返回“en”文件夹. 点击“添加文件”并选择“创建新文件”.
...然后回到 "zh-cn"文件夹。点击 "add file " 并选择 "create new file"。

![create new file](/images/how-to/howto-09.png)
![创建新文件](/images/how-to/howto-09.png)

在 URL 中添加术语名称(无大写和无空格)和末尾的 .md(注意：如果您的预览不起作用, 您可能忘记在末尾添加 .md). 现在粘贴下面的模板内容. 将您的定义复制并粘贴到文件中. 请注意, GitHub 使用 markdown 来格式化文本(例如, 超链接、粗体、斜体). 请参考这份 [markdown cheat sheet](https://www.markdownguide.org/cheat-sheet/). 要验证您是否按预期使用了markdown, 请转到“预览”.
在URL中添加术语名称（不要大写，不要空格），并在末尾添加 .md（注意：如果你的预览不工作，你可能忘记在末尾添加.md）。现在粘贴下面的模板内容。复制并粘贴你的定义到文件中。为了方便审查，请 **使用 [语义换行符](https://sembr.org/)**（例如每句一行）。注意，GitHub 使用 markdown 来格式化文本（例如，超链接、粗体、斜体）。请参考这个 [markdown 小抄](https://www.markdownguide.org/cheat-sheet/)。为了验证你是否按照预期使用了markdown，请转到 "preview"。

![finalize term](/images/how-to/howto-10.png)
![最终确定术语](/images/how-to/howto-10.png)

当您准备好提交时, 向下滚动并命名新的提交文件. 您现在即将将该术语提交到您自己的分支. 提交 PR 需要多一步. 点击“commit new file”...
向下滚动，当你准备提交时，命名新的提交文件。现在你即将把术语提交到你自己的分支。提交 PR 还需要一个步骤。点击 "commit new file"，然后...

![commit new file](/images/how-to/howto-11.png)
![提交新文件](/images/how-to/howto-11.png)

...现在你在创建 PR:
...现在你正在创建一个PR。

![create a pr](/images/how-to/howto-12.png)
![创建一个PR](/images/how-to/howto-12.png)

你应该可以在"Pull requests"下看到你的 PR.
你现在应该在 "Pull requests" 下看到你的PR。

![prs](/images/how-to/howto-13.png)

## 更新现有术语
要更新现有术语, 您可以通过问题提出更改建议, 也可以通过提交拉取请求 (PR) 直接更新术语.
要更新现有术语，您可以通过议题提出更改建议，也可以通过提交拉取请求 (PR) 直接更新术语。

### 通过 issue 请求更改
如果您想标记一个术语的问题, 但不知道如何或想自己修复它, 请单击 "report issue."
如果您想标记一个术语的议题，但不知道如何或想自己修复它，请单击 "report issue"。

![report issue](/images/how-to/howto-14.png)
![报告议题](/images/how-to/howto-14.png)

这将直接打开一个问题. 请详细说明需要进行哪些更改以及原因. 点击提交, 就是这样.
这将直接打开一个议题。请详细说明需要进行哪些更改以及原因。点击提交，就是这样。

![submit issue](/images/how-to/howto-15.png)
![提交议题](/images/how-to/howto-15.png)

### 直接更新术语
如要直接更改术语, 请转到“编辑此页面”.
如要直接更改术语，请转到“edit this page”。

![edit this page](/images/how-to/howto-16.png)
![编辑此页面](/images/how-to/howto-16.png)

这将打开术语的 GitHub 页面. 进行更改并提交 PR. 有关详细说明, 请参阅上面的“提交新术语”(跳转到有关降价的部分).
这将打开术语的 GitHub 页面。进行更改并提交 PR。有关详细说明，请参阅上面的“提交新术语”(跳转到有关降价的部分)。

## 云原生词汇表翻译帮助
为了帮助将云原生词汇表翻译成您的母语, 请加入 CNCF Slack 上的 #glossary-localizations 频道并告诉我们. 您可以加入现有团队或创建新团队（要查看需要什么, 请查看 [Localization Guide](https://github.com/cncf/glossary/blob/main/LOCALIZATION.md)). 也请参加我们每月的词汇表工作组会议. 你可以在 [CNCF calendar](https://www.cncf.io/calendar/) 中找到会议详情. 我们期待在那里与您见面！
为了帮助将云原生词汇表翻译成您的母语，请加入 CNCF Slack 上的 #glossary-localizations 频道并告诉我们。您可以加入现有团队或创建新团队（要查看需要什么，请查看 [Localization Guide](https://github.com/cncf/glossary/blob/main/LOCALIZATION.md)）。也请参加我们每月的词汇表工作组会议。你可以在 [CNCF 日历](https://www.cncf.io/calendar/) 中找到会议详情。我们期待在那里与您见面！
66 changes: 51 additions & 15 deletions content/zh-cn/style-guide/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,16 @@ menu:

云原生词汇遵循位于CNCF资源库中的 [默认风格指南](https://github.com/cncf/foundation/blob/master/style-guide.md)。 此外，它还遵循以下规则：

1. [避免使用俗语](https://en.wikipedia.org/wiki/Colloquialism)
2. [使用字面和具体的语言](https://guidetogrammar.org/grammar/composition/abstract.htm)
3. [省略缩略语](https://en.wikipedia.org/wiki/Contraction_(grammar))
4. [少用被动语态](https://www.ef.com/ca/english-resources/english-grammar/passive-voice/)
5. [力求以积极的形式表述](https://examples.yourdictionary.com/positive-sentence-examples.html)
6. [引号外不加感叹号](https://www.grammarly.com/blog/exclamation-mark/)
7. 不要夸大其词
8. 避免重复
9. 要简明扼要
1. 使用简单、易懂的语言，避免技术术语和流行语
2. [避免使用俗语](https://en.wikipedia.org/wiki/Colloquialism)
3. [使用字面和具体的语言](https://guidetogrammar.org/grammar/composition/abstract.htm)
4. [省略缩略语](https://en.wikipedia.org/wiki/Contraction_(grammar))
5. [少用被动语态](https://www.ef.com/ca/english-resources/english-grammar/passive-voice/)
6. [力求以积极的形式表述](https://examples.yourdictionary.com/positive-sentence-examples.html)
7. [引号外不加感叹号](https://www.grammarly.com/blog/exclamation-mark/)
8. 不要夸大其词
9. 避免重复
10. 要简明扼要

## Definition Template

Expand Down Expand Up @@ -91,13 +92,48 @@ category: 概念

该定义包含三个小标题，为读者提供背景："是什么"，"解决的问题"，以及 "如何帮助"。对于技术和概念类的术语来说，这三个标题都是必须的，然而，属性类的定义则不需要这些标题。

## 受众
#### 三个小标题

云原生词汇表是为技术和非技术的受众准备的。因此，请确保用简单的术语解释定义，不要假设有技术知识。在适当的时候，使用现实世界的例子，帮助读者（尤其是非技术性读者）更好地理解你所解释的概念在什么时候和为什么是相关的。
另外，在你的定义中使用术语时，要直接链接到词汇表（只有第一次提到时才应该有超链接），并确保通过拼写检查程序运行你的文本。
**技术** 和 **概念** 类别的定义包含三个小标题。

作为一个例子，看看 [服务网状](/zh-cn/service_mesh/)的“是什么”部分。它链接到了微服务、服务、可靠性和可观察性的定义，并使用了一个真实世界的例子，所以（非技术）读者可以更好地与网络挑战相联系（将其与每个人都熟悉的 wifi 网络相比较）。
- **是什么**：对我们正在谈论的内容提供一个简短而清晰的概述。
- **解决的问题**：关注问题，而不是解决方案（这在下一节会有）。事实上，避免提及所定义的术语。问题的重点是 *什么* 导致我们需要那个东西。
- **如何帮助**：现在，回到这个术语上。它是如何解决上面描述的问题的？

在开始之前，请阅读本网站上的一些已发表的术语，这样你就能感觉到详细程度和难度，以及何时举例合适。
注意，**属性** 不需要单独的章节。一个定义就足够了。

术语的定义应基于文献、学术文章、讲座和白皮书中公布的当代用法的经验证据。在某些情况下，一个术语会出现混淆、不精确的用法，或者更糟糕的是，定义完全冲突。在这些情况下，云原生词汇表委员会将逐一考虑建议的澄清或重点定义。
为了便于审查，请使用 **语义的换行符**（每行一句话）。

#### 质量是最重要的

如果被合并，你的提交将成为该术语的 CNCF 官方定义（直到其他人改进它）。创建一个符合CNCF高标准的术语不能操之过急，质量需要时间和努力。

**做你的研究**：即使你确信你知道这个术语，也要验证你是否得到了它。我们经常在组织中以某种方式使用术语，但这可能并不反映全貌。当你做研究时，特别是当你对这个术语不是100%熟悉时，要使用多种资源。许多定义是片面的，尤其是由供应商提供的定义。词汇表必须包含供应商中立的、全球公认的定义。

**不要剽窃**：同样的规则适用于词汇表和任何其他严肃的出版物。不要复制和粘贴其他人的作品，除非你是引用和贡献给他们的。如果你喜欢某个定义的某个部分，请用你自己的话来转述它。

**参考权威资源**：在可能的情况下，链接到权威的资源，如项目文件。注意，我们不能链接到供应商开发的内容。

#### 保持简单

本词汇表旨在 **用简单的文字解释复杂的概念** --这是一项令人惊讶的艰巨任务，可能需要多次修订。在起草你的定义时，要始终牢记受众。避免使用行业术语和流行语--你可能会发现自己又回到了这些术语和流行语，而且可能需要自动更正。

在适当的时候，使用 **现实世界的例子**，帮助读者（尤其是非技术性的）更好地理解你所解释的概念在 *什么时候* 和 *为什么* 是相关的。

当在你的定义中使用时，一定要 **链接到现有的词汇表术语**（只有第一次提到的时候应该有超链接）。

**例子**：看看 [服务网状](/zh-cn/service_mesh/)的 "是什么 "部分。它链接到了微服务、服务、可靠性和可观察性的定义。此外，它还使用了一个真实的例子，将微服务环境中的网络挑战（非技术人员无法理解的问题）与 wifi 问题（使用笔记本电脑的人都能理解的问题）进行比较。在可能的情况下，尝试建立这种联系。

#### 从谷歌或Word文档开始

我们建议从 Google 或 Word 文档开始，让它静置几天，然后再重新审视。这将使你能够抓住那些可以用更简单和更容易理解的方式来表达的短语或表达方式。此外，确保在提交公关前进行拼写检查。

为了确保在工作期间没有其他人提交PR，请确保申请一个问题（或创建一个），并将其分配给你。 更多信息请参见 [如何贡献](/zh-cn/contribute/) 文档。

在开始之前，请阅读一些已发表的词汇表术语，以了解其详细程度和难度，以及何时举例合适。

## 评审过程：期待什么

请注意，我们目前只有三个维护者在业余时间做这个工作。偶尔，我们会很快审查术语；在其他情况下，可能需要一些时间--我们感谢你的耐心。如果你有任何问题，请在 #glossary Slack 频道与我们联系（关于在哪里以及如何找到该频道，请参考我们的 [如何贡献](/zh-cn/contribute/) 文档）。

我们的目标是让云原生词汇表成为尽可能最好的资源。一旦你提交了一个 PR，我们可能会要求进行一次或多次修改。不要感到沮丧--许多 PR 都是这样的情况。这些来回的修改和我们的合作将确保你的贡献成为一个真正有用的定义，被全球各地的读者所阅读和参考。