如何为Elasticsearch6.x Reference中文版贡献翻译/审校

Elasticsearch6.x Reference中文版翻译工作已经得到官方授权并在翻译中，如有兴趣可以一起为Elasticsearch中文社区贡献自己的一份力量，最终翻译完成后中文版本将会同步到Elastic官网。

翻译流程如下，具体详见https://github.com/elasticsearch-cn/elasticsearch/wiki。

Prerequisites

• Github Account
• Forked version of Elasticsearch
• Write info https://yiqixie.com/s/home/fcADV-sYeZE8RITYnTtMztGpJ

Prepare translation

1. Fork the book repository to your own repository

• login and goto https://github.com/elasticsearch-cn/elasticsearch

• click Forkand choose your own personal account

2. Clone the book repository

git clone git@github.com:${USER_NAME}/elasticsearch.git

3. Add upstream to your repository

• git remote add upstream https://github.com/elasticsearch-cn/elasticsearch.git

• Add the “PullRequest” Git alias (macro) to your Git config edit .git/config and add the following lines:

方法一：

• git config --global alias.pr '!f() { git fetch upstream pull/$1/head:pr/$1; }; f'
• git config --global alias.review '!f() { git checkout cn && git pr $1 && git checkout cn && git pull --rebase upstream cn && git checkout pr/$1 && git rebase cn;}; f'

方法二：

[alias] pr = "!f() { git fetch upstream pull/$1/head:pr/$1; }; f"

[alias] review = "!f() { git checkout cn && git pr $1 && git checkout cn && git pull --rebase upstream cn && git checkout pr/$1 && git rebase cn;}; f"

4. Catch up with latest updates:

* git checkout cn

* git pull --rebase upstream cn # upstream should point to elasticsearch-cn/elasticsearch.git.git

• 确定好你目前正在翻译的章节，excel里面只粗分到章，原则是一个人负责一章，千万不要弄错了，先更新你的任务状态

Create a chapter branch -- Rule #1: Never work on master or cn!

*git checkout -b chapter/chapter1/getting-started.asciidocfor chapter #1 branch and the first doc in this chapter

5. Translate

6. Review locally （ https://github.com/elastic/docs ）

git clone git@github.com:elastic/docs.git

./docs/build_docs.pl --doc getting-started.asciidoc --out es-book-output/ --open --chunk=1

• Warning The output/dir/ will be deleted and recreated, so don’t point it at a directory with contents that you want to keep.

7. Send pull request（elasticsearch-cn:cn from ${USER_NAME}:${USER_BRANCH}）

8. Wait for review（ find some guy review for you）

9. Review and modify

10. Wait for merge

11. Merge to cn branch

12. Resource

    • 语法，编译工具：https://github.com/elastic/docs
    • 文档说明：https://www.elastic.co/blog/the-fine-manual
    • 文档编译工具：http://asciidoctor.org/docs/install-toolchain/
    • mac下文档编译工具：http://asciidoctor.org/docs/install-asciidoctor-macosx/
    • Chrome extension: Asciidoctor

Note about squashing commits

You should also **never squash commits during the review** process at Github, since that forces the reviewer to evaluate
hundreds of lines of code in a new, squashed commits, instead of just the changes in specific commits. In other words, during the review process, keep adding and pushing commits, and after the review is done, perform a final rebase/squash/reword/etc on the branch, before merging it.
```

git checkout your-chapter/chapters git merge-base your-chapter/chapters cn git rebase -i sha1 git rebase cn ```

Prepare push to your repo

* `git checkout cn`            # Go back to cn to get latest commits
* `git pull --rebase upstream cn` # Rebase the cn
* `git checkout chapter/chapter1`    # Go back to the translation branch
* `git rebase cn`            # Rebase feature branch using cn
* `git push origin chapter/chapter1` # Push to your remote

If you already pushed to your remote, and make changes to the history (like with rebase / squash), your push will be denied. In that case, you need to use the `--force` switch to overwrite the remote history:

```
git push origin chapter/chapter1 -f # Force push to your remote
```

Remember that it’s perfectly fine to overwrite your own history (ie. your fork, or private branch), but you must not (infact never!) overwrite shared history (ie. master, the cn branch, etc). In other words, force push to your fork or branch, but never to branches which you share with other developers and the world.

Prepare a pull-request for your fix

* Go to your Github account and open a pull request for the the branch you just committed and pushed.
  * 每个章节下面有很多页，我们可以分批提交，如第一章第一次提交的pr，（章节+部分+文件路径）标题：`chapter1_part1: /getting-started.asciidoc`
  * 如翻译完第二部分（另外一个文件）再来一个PR：`chapter2_part1: /setup/install.asciidoc`
* The pull-request will get an ID, which is the last number in the github URL:
    * https://github.com/elasticsearch-cn/elasticsearch/pull/2985

Fetch a PR and review locally

* If you are a reviewer you can pull the pull-request by running (2985 is your pr id):
    * `git review 2985`
    * or manually fetch PR
      * `git pr 2985` # Create a branch named “pr/2985” in your working copy (local)
      * `git checkout cn && git pull --rebase upstream cn` # Get latest changes
      * `git checkout pr/2985 && git rebase cn` # Rebase to latest cn
* Do your checking and review, please use web browser to view the final result
   `./docs/build_docs.pl --doc   getting-started.asciidoc  --out es-book-output/ --open --chunk=1`
* Go to pull thread and comment "LGTM"

* [DONT! do this now]`git checkout cn && git merge pr/2895` # Merge the commits into cn * [DONT! do this now]`git push upstream cn` # Push cn to the main repo  * Make sure to add the proper labels to the github issue/PR: see following section * Clean local branch `git branch -D pr/2985` * Done

Labelling pull requests & issues

  * `to be review` `review`  `to be merge` `done`

Translation Reviews

* Everybody does translation reviews.
* Everybody's translation gets reviewed before being merged.
* You should find a reviewer for your PR.
* You have to satisfy your reviewer.

As the reviewee:

When your translation is ready for review (which includes updating the documentation and modify), create a pull request on GitHub and add the `to be review` label.

Then find somebody to review your translation and assign the PR to that person.  You can find people who are interested in your PR touches in the [spreadsheet] or from QQ group: 109764489 .

Generally, most PRs should be reviewed by at least two other people:
* For the first review, try to choose a less experienced person so that they have a chance to learn.
* Once you have satisfied the first reviewer, find somebody with more experience in the area to give the final LGTM (looks good to me).
* Try not to choose the same people all the time - spread the load.
* If a reviewer takes too long, feel free to bug them or to choose a different reviewer, but it is up to you to get your PR reviewed.

Once you have two LGTM, go ahead and label your PR: 

Label your PR with `to be merged`, and with the chapter number (eg `chapter1`, `chaper2`, `chapter1_part1`)

For smaller PRs, a single review may be sufficient, but if you are not 100% sure, then make sure you get a second review.

As the reviewer:

If you have any questions, or suggestions, leave comments on the PR, remove the `review` label and unassign yourself.  It is up to the reviewee to make the appropriate corrections or to explain their choices to your satisfaction.

As part of the review, make sure that the PR is properly labelled according to the labelling section above.

Once you are satisfied, leave a LGTM (looks good to me) comment and, again, remove the `review` label and unassign your