From 6719b87cb940a71eecfadffb794aabb9c9a91988 Mon Sep 17 00:00:00 2001 From: Gau Liang Date: Mon, 2 Mar 2020 23:15:26 +0800 Subject: [PATCH] zh-translation:/content/zh/about/contribute/github/index.md (#6658) * zh-trans: contribute * Fix: lint errors. * Fix: link `#add` to `/add-content` * Fix: lint errors. --- content/zh/about/contribute/diagrams/index.md | 2 +- content/zh/about/contribute/github/index.md | 99 +++++++------------ 2 files changed, 36 insertions(+), 65 deletions(-) diff --git a/content/zh/about/contribute/diagrams/index.md b/content/zh/about/contribute/diagrams/index.md index fc12e1c9e8..86c371c4a8 100644 --- a/content/zh/about/contribute/diagrams/index.md +++ b/content/zh/about/contribute/diagrams/index.md @@ -21,7 +21,7 @@ keywords: [contribute,diagram,documentation,guide] 1. 用适当的线条连接 shape。 1. 用简短的描述性文字标记 shape 和线条。 1. 为多次应用的标签添加图例。 -1. 将您的图表 [贡献](/zh/about/contribute/github/#add) 给我们的文档。 +1. 将您的图表 [贡献](/zh/about/contribute/add-content) 给我们的文档。 如果您是在 Google Draw 中创建图表，请参照下面的步骤： diff --git a/content/zh/about/contribute/github/index.md b/content/zh/about/contribute/github/index.md index 009802b681..77e718d31d 100644 --- a/content/zh/about/contribute/github/index.md +++ b/content/zh/about/contribute/github/index.md @@ -1,6 +1,6 @@ --- title: 使用 GitHub 参与社区活动 -description: 向您展示如何使用 GitHub 处理 Istio 文档。 +description: 向您展示如何使用 GitHub 参与贡献 Istio 文档。 weight: 30 aliases: - /zh/docs/welcome/contribute/creating-a-pull-request.html @@ -12,95 +12,66 @@ aliases: keywords: [contribute,community,github,pr] --- -我们很高兴您对改进和扩展 Istio 文档感兴趣！在开始之前，请花一些时间来熟悉改进与拓展 Istio 文档的流程。 +Istio 文档协作遵循标准的 [GitHub 协作流](https://guides.github.com/introduction/flow/)。这种成熟的协作模式有助于开源项目管理以下类型的贡献： -要处理 Istio 文档，您需要： +- [添加](/zh/about/contribute/add-content)新文件到存储库。 +- [编辑](#quick-edit)现有文件。 +- [审阅](/zh/about/contribute/review)添加或修改的文件。 +- 管理多个发布或开发[分支](#branching-strategy)。 -1. 创建一个 [GitHub 账户](https://github.com)。 +该贡献指南假定您可以完成以下任务： -1. 签署[贡献者许可协议](https://github.com/istio/community/blob/master/CONTRIBUTING.md#contributor-license-agreements). +- Fork [Istio 文档存储库](https://github.com/istio/istio.io)。 +- 为您的更改创建分支。 +- 向该分支添加提交。 +- 打开一个 PR 分享您的贡献。 -该文档是根据 [Apache 2.0](https://github.com/istio/istio.io/blob/master/LICENSE) 协议许可发布的。 +## 开始之前{#how-to-contribute} -## 如何贡献{#how-to-contribute} +要为 Istio 贡献文档，您需要： -您可以通过以下三种方式为 Istio 文档做出贡献： +1. 创建 [GitHub 帐户](https://github.com)。 -* 如果您想要编辑现有页面，可以在浏览器中打开页面，然后从该页面右上方的齿轮菜单中选择**在 GitHub 上编辑此页面**选项，这将带您到 GitHub 页面进行编辑操作并提交相应的更改。 +1. 签署 [贡献者许可协议](https://github.com/istio/community/blob/master/CONTRIBUTING.md#contributor-license-agreements)。 -* 如果您想使用通用的方式在站点上工作，请遵循我们的[如何添加内容](#add)中的步骤。 +1. 安装 [Docker](https://www.docker.com/get-started)，以预览和测试您的文档更改。 -* 如果您想对现有的 pull request（PR）进行评审，请遵循我们[如何查看内容](#review)中的步骤。 +文档是根据 [Apache 2.0](https://github.com/istio/istio.io/blob/master/LICENSE) 协议许可发布的。 -合并您的更改后，您的更改会立即显示在 `preliminary.istio.io` 上。但是，更改仅在下一次我们发布一个新版本的时候才会在 `istio.io` 上显示，该更改大约每季度一次。 +## 快速编辑 {#quick-edit} -### 如何添加内容{#add} +任何签署了 CLA 的 GitHub 帐户，都可以对 Istio 网站上的任何页面进行修改并提交贡献。这个过程非常简单： -要添加内容，您必须创建存储库的分支，并从该分支向文档主存储库提交 PR。以下步骤描述了该过程： +1. 访问您要编辑的页面。 +1. 将 `preliminary` 添加到 URL 的开头。例如，要编辑 `https://istio.io/about`，新 URL 应为 `https://preliminary.istio.io/about`。 +1. 单击右下角的铅笔图标。 +1. 在 GitHub UI 上进行编辑。 +1. 创建 Pull Request 提交您的修改。 -浏览 Istio 网站的源代码 - -1. 单击上方的按钮访问 GitHub Istio 仓库。 - -1. 单击屏幕右上角的**Fork**按钮，以在您的 GitHub 帐户中创建我们的 Istio 仓库的副本。 - -1. 克隆您的 fork 到本地，然后进行所需的任何更改。 - -1. 当您准备将这些更改发送给我们时，请将更改推送到您的 fork 仓库。 - -1. 进入 fork 仓库的索引页面，然后单击**New Pull Request**提交 PR。 - -### 如何评审内容{#review} - -如果您的评论内容很少，请直接在 PR 上发表评论。如果您评论的内容很详细，请按照以下步骤操作： - -1. 在 PR 上评论 `/hold` 。此命令可防止 PR 在完成审阅之前被合并。 - -1. 在 PR 中评论具体信息。如果可以的话，请在受影响的文件和文件行上直接评论特定的具体信息。 - -1. 适当的时候，在评论中向 PR 提交者与参与者提供建议。例如： - - {{< text markdown >}} - 使用现在时可避免动词一致问题并使文本更易于理解： - - &96;&96;&96;suggestion - - Pilot maintains an abstract model of the mesh. - - &96;&96;&96; - {{< /text >}} - -1. 发布您的评论，与 PR 参与者分享您的评论和建议。 - - {{< warning >}} - 如果您不发布评论，则 PR 所有参与者者和社区将看不到您的评论。 - {{< /warning >}} - -1. 发布评论后，大家经过讨论一致同意合并 PR，请在文本上留下：`/hold cancel`。该命令将取消阻止 PR 合并。 +请参阅我们在[贡献新内容](/zh/about/contribute/add-content)或[内容审查](/zh/about/contribute/review)中的指南， +以了解有关提交更多实质性更改的详细信息。 ## 分支策略{#branching-strategy} -当您提交 pull request 时，您在 GitHub 上的 PR 页面会显示一个指向为您的 PR 自动构建的登入站点的链接，这对于您查看最终用户的最终页面看起来很有用。这个临时的网站，可以确保页面预览看起来正常。 +文档内容的维护在 `istio/istio.io` 仓库 Master 分支进行，Istio 发布当天，我们基于 Master 创建发布分支。以下链接指向我们在 GitHub 上的存储库： -如果您创建了 Istio 仓库的分支，则可以在本地预览更改效果。 -有关说明，请参阅 [README](https://github.com/istio/istio.io/blob/master/README.md)。 +查看站点源码 -## 分支{#branching} +Istio 文档存储库使用多个分支发布所有 Istio 版本的文档。每个 Istio 发布都有相应的文档分支。例如，类似 `release-1.0`、`release-1.1`、`release-1.2` 等分支，都是在相应的发布日创建的。若要查看特定版本的文档，请参阅[存档页](https://archive.istio.io/)。 -我们使用多个分支来跟踪不同版本的 Istio 的文档。master 分支是接受文档更新的地方，通常应在此处进行更改。 +这种分支策略允许我们提供以下 Istio 在线资源： -在 Istio 发行日，我们从 master 分支创建 Release 分支以发布新版本。例如，有命名 -为 `release-1.0`、`release-1.1`、`release-1.2` 的分支。 +- [发布站点](/zh/docs/) 提供当前最新发布分支的内容。 -`istio.io` 站点内容对应最新的 Release 分支生成； -`preliminary.istio.io` 站点内容对应当前 master 分支的内容生成； -`archive.istio.io` 站点内容对应所有以前的 Release 分支内容生成。 +- 预备站点 `https://preliminary.istio.io` 发布了当前 Master 分支上的最新内容。 + +- [存档站点](https://archive.istio.io) 提供所有已发布分支的内容。 考虑到分支的工作原理，如果您提交修改到 master 分支，在 Istio 的下一个 major 版本发布前，这些更改都不会被应用到 istio.io。 如果您的文档更改和当前 Istio 版本密切相关，也可以将更改应用到当前版本的 Release 分支。您可以通过在文档的 PR 上使用 cherry-pick 标签，自动地执行此操作。 例如，如果您在 PR 中向 master 分支引入了更正，则可以通过 `cherrypick/release-1.4` 标签以将此更改合并到 `release-1.4` 分支。 -一旦您的初始PR被合并，将自动在 Release 分支创建一个包含您的更改的 PR。为了使 CLA 机器人可以继续工作，您可能需要在 PR 上添加一个内容为 `@googlebot I consent` 的评论。 +一旦您的初始PR被合并，将自动在 Release 分支创建一个包含您的更改的 PR。为了使 `CLA` 机器人可以继续工作，您可能需要在 PR 上添加一个内容为 `@googlebot I consent` 的评论。 在极少数情况下，cherry picks 功能可能无效。发生这种情况时，自动化程序将在原始 PR 中留下一条注释，表明它已失败。发生这种情况时，您将需要手动创建 cherry pick，并处理阻止该过程自动运行的合并问题。