Skip to content

Home

Jump to bottom
Medcl edited this page Mar 9, 2016 · 22 revisions

如何为<Elasticsearch权威指南>中文版贡献翻译/审校

Prerequisites

  • Github Account
  • Forked version of Elasticsearch权威指南

Prepare translation

  1. Fork the book repository to your own repository
* login and goto https://github.com/elasticsearch-cn/elasticsearch-definitive-guide

* click `Fork` and choose your own personal account

  1. Clone the book repository

    • git clone git@github.com:${USER_NAME}/elasticsearch-definitive-guide.git

  2. Add upstream to your repository * git remote add upstream https://github.com/elasticsearch-cn/elasticsearch-definitive-guide.git * Add the “PullRequest” Git alias (macro) to your Git config edit .git/config and add the following lines:

[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-definitive-guide.git`

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

## Create a chapter branch -- _Rule #1: Never work on master or cn!_
* `git checkout -b chapter/chapter1_part1` for chapter #1 branch and the first doc in this chapter
  1. Translate
  2. Review locally （ https://github.com/elastic/docs ） ``` git clone git@github.com:elastic/docs.git

./docs/build_docs.pl --doc elasticsearch-definitive-guide/book.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
  8. Wait for review（ find some guy review for you）
  9. Review and modify
  9. Wait for merge
  10. Merge to cn branch (Medcl)
  11. 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: /010_intro/05_What_is_it.asciidoc`
      * 如翻译完第二部分（另外一个文件）再来一个PR：`chapter1_part2: /010_intro/10_Installing_ES.asciidoc`
    * The pull-request will get an ID, which is the last number in the github URL:
        * https://github.com/elasticsearch-cn/elasticsearch-definitive-guide/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   elasticsearch-definitive-guide/book.asciidoc --out es-book-output/ --open --chunk=1`
    * Go to pull thread and comment "LGTM"
<del>
    * [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
</del>
    * 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.
Clone this wiki locally