Skip to content

Home

Jump to bottom Edit New page
叮咚光军 edited this page Jun 6, 2018 · 6 revisions

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

Prerequisites

Prepare translation

  1. Fork the book repository to your own repository
  1. Clone the book repository

git clone [email protected]:${USER_NAME}/elasticsearch.git

  1. 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"

  1. 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!

checkout from cn branch!

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

  1. Translate

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

方法一：可以用 Atom 编辑， 下载 Asciidoc Preview 插件就可以实时翻译预览效果。

方法二：使用官方编译工具 git clone [email protected]:elastic/docs.git

编译所有文件： ./docs/build_docs.pl --doc index.asciidoc --out es-book-output/ --open --chunk=1

编译单个文件： ./docs/build_docs.pl --doc path/to/some/page.asciidoc --lenient --single --open

更多命令查看 https://github.com/elastic/docs

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

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

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

  3. Review and modify

  4. Wait for merge

  5. Merge to cn branch

  6. Resource

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 yourself. If you are unsure about giving your LGTM, feel free to add a comment like "I think @medcl should look at this too", and it is up to the PR author to make sure that they do so.>
Add a custom footer
Add a custom sidebar
Clone this wiki locally