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:
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
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.
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.
<spanid="create-a-local-branch"></span><h2>Create a local branch<aclass="headerlink"href="#create-a-local-branch"title="Permalink to this headline">¶</a></h2>
<p>Paddle is currently using <aclass="reference external"href="http://nvie.com/posts/a-successful-git-branching-model/">Git-flow branching model</a>.</p>
<p>All feature and bug fix development work should be done on a new branch, generally create new branch from <codeclass="docutils literal"><spanclass="pre">develop</span></code> branch .</p>
<p>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 <codeclass="docutils literal"><spanclass="pre">git</span><spanclass="pre">status</span></code>.</p>
</div>
<divclass="section"id="using-pre-commit-hook">
<spanid="using-pre-commit-hook"></span><h2>Using <codeclass="docutils literal"><spanclass="pre">pre-commit</span></code> hook<aclass="headerlink"href="#using-pre-commit-hook"title="Permalink to this headline">¶</a></h2>
...
...
@@ -235,82 +229,140 @@ PR doesn’t fit hook can not be merged into Paddle.</p>
<p>To use <aclass="reference external"href="http://pre-commit.com/">pre-commit</a>, you should install it by
<codeclass="docutils literal"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">pre-commit</span></code>, and currently, Paddle uses <codeclass="docutils literal"><spanclass="pre">clang-format</span></code> to format
c/cpp sources. Please make sure clang-format 3.8+ installed.</p>
<p>Then just run <codeclass="docutils literal"><spanclass="pre">pre-commit</span><spanclass="pre">install</span></code> in your Paddle clone directory. When you
commit your code, the pre-commit hook will check the local code if there is
<p>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.</p>
</div>
<divclass="section"id="start-to-develop">
<spanid="start-to-develop"></span><h2>Start to develop<aclass="headerlink"href="#start-to-develop"title="Permalink to this headline">¶</a></h2>
<p>In this tutorial, I delete a line in README.md and created a new file.</p>
<p>We can use <codeclass="docutils literal"><spanclass="pre">git</span><spanclass="pre">status</span></code> to inspect the changes of current directory, <codeclass="docutils literal"><spanclass="pre">git</span><spanclass="pre">diff</span></code> to see difference.</p>
<divclass="highlight-bash"><divclass="highlight"><pre><span></span>➜ git status
On branch <spanclass="nb">test</span>
Changes not staged <spanclass="k">for</span> commit:
<spanclass="o">(</span>use <spanclass="s2">"git add <file>..."</span> to update what will be committed<spanclass="o">)</span>
<spanclass="o">(</span>use <spanclass="s2">"git checkout -- <file>..."</span> to discard changes in working directory<spanclass="o">)</span>
modified: README.md
Untracked files:
<spanclass="o">(</span>use <spanclass="s2">"git add <file>..."</span> to include in what will be committed<spanclass="o">)</span>
<spanclass="nb">test</span>
no changes added to commit <spanclass="o">(</span>use <spanclass="s2">"git add"</span> and/or <spanclass="s2">"git commit -a"</span><spanclass="o">)</span>
</pre></div>
</div>
</div>
<divclass="section"id="build-and-test">
<spanid="build-and-test"></span><h2>Build and Test<aclass="headerlink"href="#build-and-test"title="Permalink to this headline">¶</a></h2>
<p>We package PaddlePaddle’s compile environment into a Docker image, called the develop image named <codeclass="docutils literal"><spanclass="pre">paddle:dev</span></code>, it contains all compiling tools that PaddlePaddle needs.</p>
<p>If you want to build the develop image, just run:</p>
<p>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.</p>
<p>Then we can generate the production image by copying the compiled PaddlePaddle program into the image by</p>
<p>For more details, you can read <aclass="reference external"href="https://github.com/PaddlePaddle/Paddle/blob/develop/doc/getstarted/build_and_install/docker_install_en.rst">this doc</a>.</p>
</div>
<divclass="section"id="commit">
<spanid="commit"></span><h2>Commit<aclass="headerlink"href="#commit"title="Permalink to this headline">¶</a></h2>
<p>Commit your changes by following command lines:</p>
<divclass="highlight-shell"><divclass="highlight"><pre><span></span><spanclass="c1"># show the working tree status</span>
git status
<spanclass="c1"># add modified files</span>
git add xx
env <spanclass="nv">EDITOR</span><spanclass="o">=</span>vim git commit <spanclass="c1"># You can write your comments by vim/nano/emacs.</span>
<p>Next we cancel the changes to the README.md file and then commit our changes by following command lines:</p>
<spanclass="o">(</span>use <spanclass="s2">"git add <file>..."</span> to include in what will be committed<spanclass="o">)</span>
<spanclass="nb">test</span>
nothing added to commit but untracked files present <spanclass="o">(</span>use <spanclass="s2">"git add"</span> to track<spanclass="o">)</span>
➜ git add <spanclass="nb">test</span>
</pre></div>
</div>
<p>We should write a description of each commit by <codeclass="docutils literal"><spanclass="pre">git</span><spanclass="pre">commit</span></code> to allow others to know
<p>The first line of commit infomation is the title. The second and later lines
are the details if any.</p>
</div>
<divclass="section"id="keeping-fork-up-to-date">
<spanid="keeping-fork-up-to-date"></span><h2>Keeping Fork Up to Date<aclass="headerlink"href="#keeping-fork-up-to-date"title="Permalink to this headline">¶</a></h2>
<p>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:</p>
<divclass="highlight-shell"><divclass="highlight"><pre><span></span><spanclass="c1"># see the current configured remote repository</span>
<spanid="create-an-issue-and-a-pull-request"></span><h2>Create an issue and a Pull Request<aclass="headerlink"href="#create-an-issue-and-a-pull-request"title="Permalink to this headline">¶</a></h2>
<p>Create an Issue to describe the problem and record its number.</p>
<p>Go to the page for your fork on GitHub, select your development branch,
and click the <strong>pull request button</strong>.</p>
and click the <codeclass="docutils literal"><spanclass="pre">New</span><spanclass="pre">pull</span><spanclass="pre">request</span></code>.</p>
<p><imgwidth="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"></p>
<p>Then select the target branch:</p>
<p><imgwidth="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"></p>
<p>We can add <codeclass="docutils literal"><spanclass="pre">resolve</span><spanclass="pre">#Issue</span><spanclass="pre">number</span></code> in PR description to close the issue automatically after the PR is merge. More details in <aclass="reference external"href="https://help.github.com/articles/closing-issues-via-commit-messages/">https://help.github.com/articles/closing-issues-via-commit-messages/</a>.</p>
<p>Then wait for review, if there need to modify, refer to the above steps to update the corresponding origin branch.</p>
<spanid="update-your-pull-request-with-the-lastest-version"></span><h2>Update your pull request with the lastest version<aclass="headerlink"href="#update-your-pull-request-with-the-lastest-version"title="Permalink to this headline">¶</a></h2>
<p>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
<spanclass="c1"># You may need to resolve the conflict according to the git prompt.</span>
<spanclass="c1"># Make and test your code.</span>
git push origin MY_COOL_STUFF_BRANCH
<divclass="section"id="delete-origin-branch">
<spanid="delete-origin-branch"></span><h2>Delete origin branch<aclass="headerlink"href="#delete-origin-branch"title="Permalink to this headline">¶</a></h2>
<p>After the PR is merge into the main repository, we can delete the remote branch on the PR page.</p>
<p><imgwidth="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"></p>
<p>Now your Pull Request is updated with the latest version.</p>
</div>
<divclass="section"id="revise-your-pull-request">
<spanid="revise-your-pull-request"></span><h2>Revise your pull request<aclass="headerlink"href="#revise-your-pull-request"title="Permalink to this headline">¶</a></h2>
<p>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.</p>
git pull upstream develop <spanclass="c1"># update local to newest code base.</span>
<spanclass="c1"># May be some conflicts will occured.</span>
<spanclass="c1"># And develop your cool stuff</span>
env <spanclass="nv">EDITOR</span><spanclass="o">=</span>vim git commit <spanclass="c1"># add your revise log</span>
git push origin MY_COOL_STUFF_BRANCH
<divclass="section"id="delete-local-branch">
<spanid="delete-local-branch"></span><h2>Delete local branch<aclass="headerlink"href="#delete-local-branch"title="Permalink to this headline">¶</a></h2>
