search

cloudnativeto / kubebuilder

Kubebuilder Chinese docs 官方文档中文版
http://cloudnative.to/kubebuilder
Apache License 2.0
63 stars 22 forks source link

Kubebuilder 官方文档翻译指导手册 #10

Closed majinghe closed 4 years ago

majinghe commented 4 years ago

切记，Kubebuilder的 zh 分支用来存放中文翻译文档，所有翻译都应该基于 zh 分支进行。

Kubebuilder 官方文档翻译指导手册

概要

云原生已经毫无争议的成了云计算发展的下一段旅程，而Kubernetes又毫无疑问的是云原生的重要技术之一。越来越多的企业借助于Kubernetes的强扩展能力来构建稳定高、伸缩性强的企业应用，在这个过程中CRD、Operator等成为了关键技术。基于此，云原生社区决定将大家常用的 kubebuilder 的官方文档进行翻译，便于国内云原生爱好者能够快速的学习与Operator相关的技术。

翻译计划

Kubebuiler 官方文档总共4大章，28小节。计划每周翻译7小节，一个月内结束翻译工作。每周末，会提前创建好下一周需要翻译章节的issue(一个小节对应一个issue)，然后大家以认领issue的方式进行翻译。会每天统计并公布 issue 的认领情况。

翻译负责人

责任范围 人员 GitHub 账号
翻译跟踪、文档更新 马景贺 lhb008
翻译跟踪、文档更新 梁斌 zhliangbin
翻译跟踪、文档更新 申红磊 shenhonglei

翻译志愿者信息登记

请翻译志愿者在此地址先进行信息登记：翻译志愿者信息登记

基本流程

整个翻译的基本流程包括下面几个步骤：

我们通过校对、终审两轮 review 保证翻译的质量；通过预览保证显示的准确性。翻译人员在整个流程中需要做的是领取任务，翻译，提交 PR，预览自查这几步。

翻译指南

下面具体介绍一下如何进行翻译工作。

准备工作

翻译流程

Step1：任务浏览

访问任务列表，会看到待领取任务。领取自己感兴趣的issue时，请注意看issue的注释，如果没有被assign给别人就可以领取。

Step2：任务领取

找到未经认领的任务（issue 注释里面没有认领内容），在issue中(或者在微信群里)@负责人，负责人会手动把issue assign给个人。

注意：由于 Kubebuilder 内容不是很多，原则上，每个人每个翻译周期(一周)内只能领取一个任务，待翻译任务被成功merge到master分钟，方可领取下一个任务。

Step3：本地构建和预览

翻译结束后可以先在本地构建进行预览。有两种方式可以完成构建：

用mdbook二进制包进行预览调试

在mdbook 官网上下载对应系统(Ubuntu, macOS)所需版本的二进制压缩包，解压后将二进制文件 mdbook放置到 PATH 路径下即可。本文以最新版本 v0.4.1 为例，在Ubuntu上进行安装示范。

$ wget https://github.com/rust-lang/mdBook/releases/download/v0.4.1/mdbook-v0.4.1-x86_64-unknown-linux-gnu.tar.gz
$ tar -zxvf mdbook-v0.4.1-x86_64-unknown-linux-gnu.tar.gz
$ chmod +x mdbook
$ mv mdbook /usr/local/bin

确认mdbook是否安装成功

mdbook v0.4.1
Mathieu David <mathieudavid@mathieudavid.org>
Creates a book from markdown files

USAGE:
    mdbook [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    build    Builds a book from its markdown files
    clean    Deletes a built book
    help     Prints this message or the help of the given subcommand(s)
    init     Creates the boilerplate structure and files for a new book
    serve    Serves a book at http://localhost:3000, and rebuilds it on changes
    test     Tests that a book's Rust code samples compile
    watch    Watches a book's files and rebuilds it on changes

For more information about a specific command, try `mdbook <command> --help`
The source code for mdBook is available at: https://github.com/rust-lang/mdBook

将fork的Kubebuilder的库中代码clone 至本地，并进至 docs/book/ 目录下，然后运行 mdbook server 启动本地调试。

$ mdbook serve -p 8000 -n 0.0.0.0
2020-07-22 05:04:12 [INFO] (mdbook::book): Book building has started
+ ../../bin/literate-go supports html
+ ../../bin/literate-go
+ ../../bin/marker-docs supports html
+ ../../bin/marker-docs
2020-07-22 05:04:13 [INFO] (mdbook::book): Running the html backend
2020-07-22 05:04:14 [INFO] (mdbook::cmd::serve): Serving on: http://0.0.0.0:8000
2020-07-22 05:04:14 [INFO] (warp::server): listening on http://0.0.0.0:8000
2020-07-22 05:04:14 [INFO] (mdbook::cmd::watch): Listening for changes...

然后在浏览器中访问 http://localhost:8000(如果mdbook安装在本地，就用localhost，如果是远端服务器，则直接用远端服务器IP地址）,可以看到book的内容

以docker方式运行mdbook进行预览调试

将fork的Kubebuilder的库中代码clone 至本地，并进至 docs/book/ 目录下，然后运行以下命令来启动 mdbook 的docker容器

$ docker run --name book -v $PWD:/opt -p 8000:8000 cloudnativeto/kubebuilder-book serve . -p 8000 -n 0.0.0.0
2020-07-22 05:07:39 [INFO] (mdbook::book): Book building has started
2020-07-22 05:07:39 [WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "literatego" preprocessor installed?
2020-07-22 05:07:39 [WARN] (mdbook::preprocess::cmd):   Command: ./litgo.sh
2020-07-22 05:07:39 [WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "markerdocs" preprocessor installed?
2020-07-22 05:07:39 [WARN] (mdbook::preprocess::cmd):   Command: ./markerdocs.sh
2020-07-22 05:07:39 [INFO] (mdbook::book): Running the html backend
2020-07-22 05:07:40 [INFO] (mdbook::cmd::serve): Serving on: http://0.0.0.0:8000
2020-07-22 05:07:40 [INFO] (ws): Listening for new connections on 0.0.0.0:3001.
2020-07-22 05:07:40 [INFO] (mdbook::cmd::watch): Listening for changes...

同样地，运行http://locahost:8000 (如果mdbook安装在本地，就用localhost，如果是远端服务器，则直接用远端服务器IP地址)，即可看到调试界面。

Step4：提交 PR

如果本地调试预览没有问题，确保前面的remote add upsteam已经添加，提交pr之前先fetch upstream，再rebase upsteam。将所修改的内容以pr提交(中文翻译对应的分支是zh 所以对应的PR也须对应zh分支)，我们已选择GitHub Action 为持续集成的构建工具，在提交完PR以后，请再pr页面及时关注GitHub Action和netlify的构建结果，netlify的bot会回复一个预览链接，无论你后续rebase如何修改pr，都可通过点击该链接预览实时的更新。

将Kubebuilder库 fork至个人仓库时，GitHub Action 的相关配置文件也已经fork过去，自己也可以利用自己仓库的GitHub Action功能进行构建检查。

提交 PR

如果检查通过，PR 被合并后就可以通过 Kubebuiler 中文文档网站预览页面看到被合并后的页面。为方便管理和辨识，请遵守下面的模板定义您的 PR：

标题：
zh-translation:<file_full_path>
内容：
ref: https://github.com/cloudnativeto/kubebuilder/issues/<issueID>
[ ] Configuration Infrastructure
[x] Docs
[ ] Installation
[ ] Networking
[ ] Performance and Scalability
[ ] Policies and Telemetry
[ ] Security
[ ] Test and Release
[ ] User Experience
[ ] Developer Infrastructure

其中，标题中的是翻译的源文件路径；内容中的 ref 是当前翻译任务的 issue 链接。

Step5：校对（review）

校对工作由没有翻译过当前文档的其他翻译人员执行，即翻译人员互为校对人员。为保证质量，我们设置了两轮 Review：

所有翻译人员互为校对人员，分配一个翻译任务同时要确定校对任务；

参与 Review：所有 Kubebuilder 的 PR 都会通过 Github 机器人同步在钉钉群里，如果看到感兴趣的 PR 就在本项目中对应的 issue 回复一下，我们社区的 maintainer 会通过 /assign命令手动将 Review 工作指派给您。

Review 的基本流程

Step7：任务完成

通过终审后的任务会被管理员 approve，并合并到 Kubebuilder 的官方仓库中。需要您在对应的 Issue 中输入指令 /merged，Bot 会设置 Issue 的状态为 finished，并关闭 Issue。整个翻译任务就算正式完成了。您可以继续领取新的任务进行翻译，或参与校对工作。

zhangguanzhang commented 4 years ago

就等你把这段写成docs/book/README.md文件了

luffyao commented 4 years ago

我觉得Kubebuiler 官方网站提交 PR 这个改成kubebuilder 中文官方网站提交，比较好，没有什么歧义。

cuisongliu commented 4 years ago

建议在翻译同时 把英文原文也写上。这样可以同步中文文档和英文文档。

majinghe commented 4 years ago

@zhangguanzhang 馆长，现在在等官余鹏 做一些自动化打标签之类的测试，明天应该能ok。完了会把文档放到 docs/book 下面。

majinghe commented 4 years ago

我觉得Kubebuiler 官方网站提交 PR 这个改成kubebuilder 中文官方网站提交，比较好，没有什么歧义。

有道理，我修改一下。以免混淆。

majinghe commented 4 years ago

@cuisongliu zh 分支存放中文文档， master 分支存放英文文档。

cuisongliu commented 4 years ago

@lhb008 

<!--
- Review [open pull requests](https://github.com/kubernetes/website/pulls) daily for quality and adherence to the [style guide](/docs/contribute/style/style-guide/).
    - Review the smallest PRs (`size/XS`) first, then iterate towards the largest (`size/XXL`).
    - Review as many PRs as you can.
- Ensure that the CLA is signed by each contributor.
    - Help new contributors sign the [CLA](https://github.com/kubernetes/community/blob/master/CLA.md).
    - Use [this](https://github.com/zparnold/k8s-docs-pr-botherer) script to automatically remind contributors that haven’t signed the CLA to sign the CLA.
- Provide feedback on proposed changes and help facilitate technical reviews from members of other SIGs.
    - Provide inline suggestions on the PR for the proposed content changes.
    - If you need to verify content, comment on the PR and request more details.
    - Assign relevant `sig/` label(s).
    - If needed, assign reviewers from the `reviewers:` block in the file's front matter.
    - Assign `Docs Review` and `Tech Review` labels to indicate the PR's review status.
    - Assign `Needs Doc Review` or `Needs Tech Review` for PRs that haven't yet been reviewed.
    - Assign `Doc Review: Open Issues` or `Tech Review: Open Issues` for PRs that have been reviewed and require further input or action before merging.
    - Assign `/lgtm` and `/approve` labels to PRs that can be merged. 
- Merge PRs when they are ready, or close PRs that shouldn’t be accepted.
- Triage and tag incoming issues daily. See [Intermediate contributing](/docs/contribute/intermediate/) for guidelines on how SIG Docs uses metadata.
-->
- 每天检查[悬决的 PR](https://github.com/kubernetes/website/pulls) 的质量并确保它们遵守[样式指南](/zh/docs/contribute/style/style-guide/)和[内容指南](/zh/docs/contribute/style/content-guide/)。
    - 首先查看最小的 PR（`size/XS`），然后逐渐扩展到最大的 PR（`size/XXL`）。
    - 尽可能多地审阅 PR。
- 确保每个贡献者完成 CLA 签署。
    - 指导新的贡献者签署 [CLA](https://github.com/kubernetes/community/blob/master/CLA.md)。
    - 使用[此脚本](https://github.com/zparnold/k8s-docs-pr-botherer)自动提醒尚未签署 CLA 的贡献者签署 CLA。
- 针对所建议的更改提供反馈，并帮助协调其他 SIG 成员进行技术审核。
    - 为 PR 所建议的内容更改提供在线反馈。
    - 如果您需要验证内容，请在 PR 上发表评论并要求贡献者提供更多细节。
    - 设置相关的 `sig/` 标签。
    - 如果需要，请从文件开头的 `reviewers:` 块中指定审阅者。
    - 设置 `Docs Review` 和 `Tech Review` 标签以标示 PR 的审阅状态。
    - 为尚未审阅的 PR 设置 `Needs Doc Review` 或者 `Needs Tech Review` 标签。
    - 为已审阅的但在合并前需要更多信息的或采取措施的 PR 设置 `Doc Review: Open Issues` 或者 `Tech Review: Open Issues` 标签。
    - 为可以合并的 PR 添加 `/lgtm` 和 `/approve` 标签。
- 合并已经就绪的，或关闭不应该接受的 PR。
- 每天对新增的 Issue 报告进行分类和判别。有关 SIG 文档如何使用 metadata 的准则，请参见
  [对 Issue 进行分类](/zh/docs/contribute/review/for-approvers/#triage-and-categorize-issues)。

像这样 跟k8s官方一样 英文作为注释，中文作为正式文稿。

majinghe commented 4 years ago

已经将翻译文档放到了 docs/book/README 中，关闭此issue。