contribute_to_paddle_en.md 4.9 KB
Newer Older
L
Luo Tao 已提交
1
# Contribute Code
Z
zhangjinchao01 已提交
2 3

We sincerely appreciate your contributions. You can use fork and pull request
4 5
workflow to merge your code.

Z
zhangjinchao01 已提交
6
## Code Requirements
7
- Your code must be fully documented by
Z
zhangjinchao01 已提交
8 9 10 11 12 13 14
  [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.

The following tutorial guides you into submitting your contibution.
15

Z
zhangjinchao01 已提交
16
## [Creating a Fork](https://help.github.com/articles/fork-a-repo/)
17

Z
zhangjinchao01 已提交
18
Just head over to the GitHub page and click the "Fork" button.
19
It's just that simple.
Z
zhangjinchao01 已提交
20 21 22

## Clone

23 24 25
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.

Z
zhangjinchao01 已提交
26 27
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:
28

Z
zhangjinchao01 已提交
29 30
```shell
# Clone your fork to your local machine
31 32 33 34 35 36 37 38
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.
L
Liu Yiqun 已提交
39
git remote add upstream https://github.com/PaddlePaddle/Paddle.git  # add upstream to baidu/Paddle
40
git pull upstream develop  # update to upstream
41
```
42

43
Then you can start to develop by making a local developement branch
44

45
```shell
46
git checkout -b MY_COOL_STUFF_BRANCH
Z
zhangjinchao01 已提交
47 48
```

49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
## Using `pre-commit` hook

Paddle developers use [pre-commit](http://pre-commit.com/) tool to manage git
pre-commit hooks. It can help us format source codes (cpp, python), check some
basic thing before commit (only one EOL for each file, do not add a huge file
in git). `pre-commit` tests is a part of unit tests in Travis-CI now, every
PR doesn't fit hook can not be merged into Paddle.

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
anything not suitable to commit, and so on.

Z
zhangjinchao01 已提交
65 66 67 68 69 70 71 72 73
## Commit

Commit your changes by following command lines:

```shell
# show the working tree status
git status
# add modified files
git add xx
74
env EDITOR=vim git commit  # You can write your comments by vim/nano/emacs.
Z
zhangjinchao01 已提交
75 76 77 78 79 80
```
The first line of commit infomation is the title. The second and later lines
are the details if any.

## Keeping Fork Up to Date

81
Before pull your request, you should sync your code from the latest PaddlePaddle.
Z
zhangjinchao01 已提交
82 83 84 85 86 87
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
L
Liu Yiqun 已提交
88
git remote add upstream https://github.com/PaddlePaddle/Paddle.git
Z
zhangjinchao01 已提交
89 90 91 92 93 94 95
# verify the new upstream
git remote -v
```

Update your fork with the latest upstream changes:

```shell
96
git pull --rebase upstream develop
Z
zhangjinchao01 已提交
97 98 99 100
```

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
101
probably shouldn't be), you may have to deal with conflicts.
Z
zhangjinchao01 已提交
102 103 104 105 106 107 108

Now, your local master branch is up-to-date with everything modified upstream.

## Push to GitHub

```shell
# push to your repository in Github
109
git push -u origin MY_COOL_STUFF_BRANCH  # create remote branch MY_COOL_STUFF_BRANCH to origin.
Z
zhangjinchao01 已提交
110 111 112 113 114 115
```

## Pull Request

Go to the page for your fork on GitHub, select your development branch,
and click the **pull request button**.
116 117 118 119 120 121 122 123 124 125

## 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
126
git pull upstream develop
127 128
# You may need to resolve the conflict according to the git prompt.
# Make and test your code.
129
git push origin MY_COOL_STUFF_BRANCH
130 131
```
Now your Pull Request is updated with the latest version.
E
emailweixu 已提交
132 133 134 135

## Revise your pull request

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.
136 137 138 139 140 141 142 143 144 145 146

The possible commands are

```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
```