Merge pull request #2006 from livc/git_usage_en_version

update contribute_to_paddle_en.md

doc/howto/dev/contribute_to_paddle_cn.md

@@ -84,7 +84,7 @@ no changes added to commit (use "git add" and/or "git commit -a")
 ➜  docker build -t paddle:dev .
 ```
 
-随后可以用这个开发镜像开build PaddlePaddle的源码。比如如果要build一个不依赖GPU，但是支持AVX指令集，并且包括unit tests的PaddlePaddle，可以：
+随后可以用这个开发镜像开始build PaddlePaddle的源码。比如如果要build一个不依赖GPU，但是支持AVX指令集，并且包括unit tests的PaddlePaddle，可以：
 
 ```bash
 ➜  docker run -v $(pwd):/paddle -e "WITH_GPU=OFF" -e "WITH_AVX=ON" -e "WITH_TEST=ON" paddle:dev

doc/howto/dev/contribute_to_paddle_en.md

@@ -4,9 +4,9 @@ We sincerely appreciate your contributions. You can use fork and pull request
 workflow to merge your code.
 
 ## Code Requirements
-- Your code must be fully documented by
-  [doxygen](http://www.stack.nl/~dimitri/doxygen/) style.
-- Make sure the compiler option WITH\_STYLE\_CHECK is on and the compiler
+- Your code comments must be fully documented by
+  [Doxygen](http://www.stack.nl/~dimitri/doxygen/) style.
+- Make sure the compiler option `WITH_STYLE_CHECK` is on and the compiler
   passes the code style check.
 - All code must have unit test.
 - Pass all unit tests.
@@ -20,32 +20,25 @@ It's just that simple.
 
 ## Clone
 
-Paddle is currently using [git-flow branching model](http://nvie.com/posts/a-successful-git-branching-model/).
-The **develop** is the main branch, and other user's branches are feature branches.
+Clone remote repository.
 
-Once you've created a fork, you can use your favorite git client to clone your
-repo or just head straight to the command line:
-
-```shell
-# Clone your fork to your local machine
-git clone --branch develop https://github.com/USERNAME/Paddle.git
-```
-If your repository doesn't contain **develop** branch, just create it by your own.
-
-```shell
-git clone https://github.com/USERNAME/Paddle.git Paddle
-cd Paddle
-git checkout -b develop  # create develop branch.
-git remote add upstream https://github.com/PaddlePaddle/Paddle.git  # add upstream to baidu/Paddle
-git pull upstream develop  # update to upstream
+```bash
+➜  git clone https://github.com/USERNAME/Paddle
+➜  cd Paddle
 ```
 
-Then you can start to develop by making a local developement branch
+## Create a local branch
+
+Paddle is currently using [Git-flow branching model](http://nvie.com/posts/a-successful-git-branching-model/).
 
-```shell
-git checkout -b MY_COOL_STUFF_BRANCH
+All feature and bug fix development work should be done on a new branch, generally create new branch from `develop` branch .
+
+```bash
+➜  git checkout -b my-cool-stuff
 ```
 
+Before the checkout, you need to keep the current branch directory clean, otherwise the untracked file will be brought to the new branch, which can be inspected by `git status`.
+
 ## Using `pre-commit` hook
 
 Paddle developers use [pre-commit](http://pre-commit.com/) tool to manage git
@@ -58,89 +51,169 @@ To use [pre-commit](http://pre-commit.com/), you should install it by
 `pip install pre-commit`, and currently, Paddle uses `clang-format` to format
 c/cpp sources. Please make sure clang-format 3.8+ installed.
 
-Then just run `pre-commit install` in your Paddle clone directory. When you
-commit your code, the pre-commit hook will check the local code if there is
+Install and run it as follow:
+
+```bash
+➜  pip install pre-commit
+➜  pre-commit install
+```
+
+When you commit your code, the pre-commit hook will check the local code if there is
 anything not suitable to commit, and so on.
 
+## Start to develop
+
+In this tutorial, I delete a line in README.md and created a new file.
+
+We can use `git status` to inspect the changes of current directory, `git diff` to see difference.
+
+```bash
+➜  git status
+On branch test
+Changes not staged for commit:
+  (use "git add <file>..." to update what will be committed)
+  (use "git checkout -- <file>..." to discard changes in working directory)
+
+	modified:   README.md
+
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+
+	test
+
+no changes added to commit (use "git add" and/or "git commit -a")
+```
+## Build and Test
+
+We package PaddlePaddle's compile environment into a Docker image, called the develop image named `paddle:dev`, it contains all compiling tools that PaddlePaddle needs. 
+
+If you want to build the develop image, just run:
+
+```bash
+➜  docker build -t paddle:dev .
+```
+
+Then we can use the develop image to build PaddlePaddle source. For example:
+
+```bash
+➜  docker run -v $(pwd):/paddle -e "WITH_GPU=OFF" -e "WITH_AVX=ON" -e "WITH_TEST=ON" paddle:dev
+```
+
+The above command will compile PaddlePaddle and create a Dockerfile for building production image. All the generated files are in the build directory. "WITH_GPU" controls if the generated production image supports GPU. "WITH_AVX" controls if the generated production image supports AVX. "WITH_TEST" controls if the unit test will be generated.
+
+Then we can generate the production image by copying the compiled PaddlePaddle program into the image by
+
+```bash
+➜  docker build -t paddle:prod -f build/Dockerfile .
+```
+
+Run unit test finally:
+
+```bash
+➜  docker run -it -v $(pwd):/paddle paddle:dev bash -c "cd /paddle/build && ctest"
+```
+
+For more details, you can read [this doc](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/getstarted/build_and_install/docker_install_en.rst).
+
 ## Commit
 
-Commit your changes by following command lines:
+Next we cancel the changes to the README.md file and then commit our changes by following command lines:
+
+```bash
+➜  git checkout -- README.md
+➜  git status
+On branch test
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+
+	test
+
+nothing added to commit but untracked files present (use "git add" to track)
+➜  git add test
+```
 
-```shell
-# show the working tree status
-git status
-# add modified files
-git add xx
-env EDITOR=vim git commit  # You can write your comments by vim/nano/emacs.
+We should write a description of each commit by `git commit` to allow others to know
+the changes in these files.
+
+```bash
+➜  git commit
+CRLF end-lines remover...............................(no files to check)Skipped
+yapf.................................................(no files to check)Skipped
+Check for added large files..............................................Passed
+Check for merge conflicts................................................Passed
+Check for broken symlinks................................................Passed
+Detect Private Key...................................(no files to check)Skipped
+Fix End of Files.....................................(no files to check)Skipped
+clang-formater.......................................(no files to check)Skipped
+[my-cool-stuff c703c041] add test file
+ 1 file changed, 0 insertions(+), 0 deletions(-)
+ create mode 100644 233
 ```
-The first line of commit infomation is the title. The second and later lines
-are the details if any.
 
 ## Keeping Fork Up to Date
 
 Before pull your request, you should sync your code from the latest PaddlePaddle.
 To do this, you'll need to add a remote at first:
 
-```shell
-# see the current configured remote repository
-git remote -v
-# add upstream repository
-git remote add upstream https://github.com/PaddlePaddle/Paddle.git
-# verify the new upstream
-git remote -v
+```bash
+➜  git remote add upstream https://github.com/PaddlePaddle/Paddle
+➜  git remote
+origin
+upstream
 ```
 
 Update your fork with the latest upstream changes:
 
-```shell
-git pull --rebase upstream develop
+```bash
+➜  git fetch upstream
+➜  git pull upstream develop
 ```
 
-If there are no unique commits locally, git will simply perform a fast-forward.
-However, if you have been making changes (in the vast majority of cases you
-probably shouldn't be), you may have to deal with conflicts.
-
 Now, your local master branch is up-to-date with everything modified upstream.
 
 ## Push to GitHub
 
-```shell
+```bash
 # push to your repository in Github
-git push -u origin MY_COOL_STUFF_BRANCH  # create remote branch MY_COOL_STUFF_BRANCH to origin.
+➜  git push origin my-cool-stuff
 ```
 
-## Pull Request
+## Create an issue and a Pull Request
+
+Create an Issue to describe the problem and record its number.
 
 Go to the page for your fork on GitHub, select your development branch,
-and click the **pull request button**.
-
-## Update your pull request with the lastest version
-
-During the code review, your pull request may become stale because new commits in
-baidu/Paddle. GitHub allows autmotic update if there is no conflict. You can do this
-by clicking the "Update Branch" button in your pull request page. However, in the case
-of conflict, you need to do the update manually. You need to do the following on
-your local repository:
-```shell
-git checkout MY_COOL_STUFF_BRANCH
-git pull upstream develop
-# You may need to resolve the conflict according to the git prompt.
-# Make and test your code.
-git push origin MY_COOL_STUFF_BRANCH
+and click the `New pull request`.
+
+<img width="295" alt="screen shot 2017-04-26 at 9 09 28 pm" src="https://cloud.githubusercontent.com/assets/11692045/25436054/a6d98c66-2ac4-11e7-9cb1-18dd13150230.png">
+
+Then select the target branch:
+
+<img width="750" alt="screen shot 2017-04-26 at 9 11 52 pm" src="https://cloud.githubusercontent.com/assets/11692045/25436139/f83b1e6c-2ac4-11e7-8c0e-add499023c46.png">
+
+We can add `resolve #Issue number` in PR description to close the issue automatically after the PR is merge. More details in <https://help.github.com/articles/closing-issues-via-commit-messages/>.
+
+Then wait for review, if there need to modify, refer to the above steps to update the corresponding origin branch.
+
+## Delete origin branch
+
+After the PR is merge into the main repository, we can delete the remote branch on the PR page.
+
+<img width="775" alt="screen shot 2017-04-26 at 9 18 24 pm" src="https://cloud.githubusercontent.com/assets/11692045/25436457/e4cdd472-2ac5-11e7-9272-badc76c4a23e.png">
+
+Or just run:
+
+```bash
+➜  git push origin :my-cool-stuff
 ```
-Now your Pull Request is updated with the latest version.
 
-## Revise your pull request
+## Delete local branch
 
-When you revise your pull request according to reviewer's comments, please use 'git commit' instead of 'git commit --amend' to commit your changes so that the reviewers can see the difference between the new pull requrest and the old pull request.
+Finally, we delete local branch:
 
-The possible commands are
+```bash
+➜  git checkout develop 
 
-```shell
-git checkout MY_COOL_STUFF_BRANCH
-git pull upstream develop   # update local to newest code base.
-# May be some conflicts will occured.
-# And develop your cool stuff
-env EDITOR=vim git commit  # add your revise log
-git push origin MY_COOL_STUFF_BRANCH
+# delete my-cool-stuff branch
+➜  git branch -D my-cool-stuff
 ```