contribute_to_paddle_en.html



<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Contribute Code &mdash; PaddlePaddle  documentation</title>
  

    <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  

        <link rel="index" title="Index"
              href="../genindex.html"/>
        <link rel="search" title="Search" href="../search.html"/>
    <link rel="top" title="PaddlePaddle  documentation" href="../index.html"/>
        <link rel="up" title="Development" href="index_en.html"/>
        <link rel="next" title="Contribute Documentation" href="write_docs_en.html"/>
        <link rel="prev" title="Development" href="index_en.html"/> 
<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "//hm.baidu.com/hm.js?b9a314ab40d04d805655aab1deee08ba";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>


  <script src="../_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

            <a href="../index_en.html" class="icon icon-home"> PaddlePaddle
          

          </a>

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
<nav class="doc-menu-vertical" role="navigation">

<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../getstarted/index_en.html">GET STARTED</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../getstarted/quickstart_en.html">Quick Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="../getstarted/concepts/use_concepts_en.html">Basic Concept</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../build_and_install/index_en.html">Install and Build</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../build_and_install/pip_install_en.html">Install using pip</a></li>
<li class="toctree-l2"><a class="reference internal" href="../build_and_install/docker_install_en.html">Run in Docker Containers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../build_and_install/build_from_source_en.html">Build from Sources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../howto/index_en.html">HOW TO</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../howto/cmd_parameter/index_en.html">Set Command-line Parameters</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../howto/cmd_parameter/use_case_en.html">Use Case</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/cmd_parameter/arguments_en.html">Argument Outline</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/cmd_parameter/detail_introduction_en.html">Detail Description</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../howto/cluster/index_en.html">Distributed Training</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../howto/cluster/preparations_en.html">Preparations</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/cluster/cmd_argument_en.html">Command-line arguments</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/cluster/multi_cluster/index_en.html">Use different clusters</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../howto/cluster/multi_cluster/fabric_en.html">Fabric</a></li>
<li class="toctree-l4"><a class="reference internal" href="../howto/cluster/multi_cluster/openmpi_en.html">OpenMPI</a></li>
<li class="toctree-l4"><a class="reference internal" href="../howto/cluster/multi_cluster/k8s_en.html">Kubernetes</a></li>
<li class="toctree-l4"><a class="reference internal" href="../howto/cluster/multi_cluster/k8s_aws_en.html">Kubernetes on AWS</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../howto/capi/index_en.html">C-API Prediction Library</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../howto/capi/compile_paddle_lib_en.html">Install and Build</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/capi/organization_of_the_inputs_en.html">Input/Output Data Organization</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/capi/workflow_of_capi_en.html">C-API Workflow</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../howto/rnn/index_en.html">RNN Models</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../howto/rnn/rnn_config_en.html">RNN Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/rnn/recurrent_group_en.html">Recurrent Group Tutorial</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/rnn/hierarchical_layer_en.html">Layers supporting hierarchical sequence as input</a></li>
<li class="toctree-l3"><a class="reference internal" href="../howto/rnn/hrnn_rnn_api_compare_en.html">API comparision between RNN and hierarchical RNN</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../howto/optimization/gpu_profiling_en.html">Tune GPU Performance</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="reference internal" href="index_en.html">Development</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Contribute Code</a></li>
<li class="toctree-l2"><a class="reference internal" href="write_docs_en.html">Contribute Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="new_layer_en.html">Write New Layers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index_en.html">FAQ</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../faq/build_and_install/index_en.html">Install, Build and Unit test</a></li>
<li class="toctree-l2"><a class="reference internal" href="../faq/model/index_en.html">Model Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../faq/parameter/index_en.html">Parameter Setting</a></li>
<li class="toctree-l2"><a class="reference internal" href="../faq/local/index_en.html">Local Training and Prediction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../faq/cluster/index_en.html">Cluster Training and Prediction</a></li>
</ul>
</li>
</ul>

</nav>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="../index_en.html">PaddlePaddle</a>
      </nav>


      <div class="wy-nav-content">
        <div class="rst-content">
          

<div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="../index_en.html">Docs</a> &raquo;</li>
      
          <li><a href="index_en.html">Development</a> &raquo;</li>
      
    <li>Contribute Code</li>
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../_sources/dev/contribute_to_paddle_en.md.txt" rel="nofollow"> View page source</a>
          
        
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="contribute-code">
<span id="contribute-code"></span><h1>Contribute Code<a class="headerlink" href="#contribute-code" title="Permalink to this headline">¶</a></h1>
<p>You are welcome to contribute to project PaddlePaddle. To contribute to PaddlePaddle, you have to agree with the
<a class="reference external" href="https://gist.github.com/wangkuiyi/0c22c7b1bd3bb7eb27d76f85c3a3e329">PaddlePaddle Contributor License Agreement</a>.</p>
<p>We sincerely appreciate your contribution.  This document explains our workflow and work style.</p>
<div class="section" id="workflow">
<span id="workflow"></span><h2>Workflow<a class="headerlink" href="#workflow" title="Permalink to this headline">¶</a></h2>
<p>PaddlePaddle uses this <a class="reference external" href="http://nvie.com/posts/a-successful-git-branching-model/">Git branching model</a>.  The following steps guide usual contributions.</p>
<ol>
<li><p class="first">Fork</p>
<p>Our development community has been growing fastly; it doesn&#8217;t make sense for everyone to write into the official repo.  So, please file Pull Requests from your fork.  To make a fork,  just head over to the GitHub page and click the <a class="reference external" href="https://help.github.com/articles/fork-a-repo/">&#8220;Fork&#8221; button</a>.</p>
</li>
<li><p class="first">Clone</p>
<p>To make a copy of your fork to your local computers, please run</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git clone https://github.com/your-github-account/paddle
<span class="nb">cd</span> paddle
</pre></div>
</div>
</li>
<li><p class="first">Create the local feature branch</p>
<p>For daily works like adding a new feature or fixing a bug, please open your feature branch before coding:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git checkout -b my-cool-stuff
</pre></div>
</div>
</li>
<li><p class="first">Commit</p>
<p>Before issuing your first <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span></code> command, please install <a class="reference external" href="http://pre-commit.com/"><code class="docutils literal"><span class="pre">pre-commit</span></code></a> by running the following commands:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>pip install pre-commit
pre-commit install
</pre></div>
</div>
<p>Our pre-commit configuration requires clang-format 3.8 for auto-formating C/C++ code and yapf for Python.</p>
<p>Once installed, <code class="docutils literal"><span class="pre">pre-commit</span></code> checks the style of code and documentation in every commit.  We will see something like the following when you run <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>➜  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
</pre></div>
</div>
</li>
<li><p class="first">Build and test</p>
<p>Users can build PaddlePaddle natively on Linux and Mac OS X.  But to unify the building environment and to make it easy for debugging, the recommended way is <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/blob/develop/doc/howto/dev/build_en.md">using Docker</a>.</p>
</li>
<li><p class="first">Keep pulling</p>
<p>An experienced Git user pulls from the official repo often &#8211; daily or even hourly, so they notice conflicts with others work early, and it&#8217;s easier to resolve smaller conflicts.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git remote add upstream https://github.com/PaddlePaddle/Paddle
git pull upstream develop
</pre></div>
</div>
</li>
<li><p class="first">Push and file a pull request</p>
<p>You can &#8220;push&#8221; your local work into your forked repo:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git push origin my-cool-stuff
</pre></div>
</div>
<p>The push allows you to create a pull request, requesting owners of this <a class="reference external" href="https://github.com/PaddlePaddle/Paddle">official repo</a> to pull your change into the official one.</p>
<p>To create a pull request, please follow <a class="reference external" href="https://help.github.com/articles/creating-a-pull-request/">these steps</a>.</p>
<p>If your change is for fixing an issue, please write <a class="reference external" href="https://help.github.com/articles/closing-issues-using-keywords/">&#8220;Fixes &lt;issue-URL&gt;&#8221;</a> in the description section of your pull request.  Github would close the issue when the owners merge your pull request.</p>
<p>Please remember to specify some reviewers for your pull request.  If you don&#8217;t know who are the right ones, please follow Github&#8217;s recommendation.</p>
</li>
</ol>
<ol>
<li><p class="first">Delete local and remote branches</p>
<p>To keep your local workspace and your fork clean, you might want to remove merged branches:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git push origin :my-cool-stuff
git checkout develop
git pull upstream develop
git branch -d my-cool-stuff
</pre></div>
</div>
</li>
</ol>
<div class="section" id="code-review">
<span id="code-review"></span><h3>Code Review<a class="headerlink" href="#code-review" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Please feel free to ping your reviewers by sending them the URL of your pull request via IM or email.  Please do this after your pull request passes the CI.</li>
<li>Please answer reviewers&#8217; every comment.  If you are to follow the comment, please write &#8220;Done&#8221;; please give a reason otherwise.</li>
<li>If you don&#8217;t want your reviewers to get overwhelmed by email notifications, you might reply their comments by <a class="reference external" href="https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/">in a batch</a>.</li>
<li>Reduce the unnecessary commits.  Some developers commit often.  It is recommended to append a sequence of small changes into one commit by running <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--amend</span></code> instead of <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span></code>.</li>
</ul>
</div>
</div>
<div class="section" id="coding-standard">
<span id="coding-standard"></span><h2>Coding Standard<a class="headerlink" href="#coding-standard" title="Permalink to this headline">¶</a></h2>
<div class="section" id="code-style">
<span id="code-style"></span><h3>Code Style<a class="headerlink" href="#code-style" title="Permalink to this headline">¶</a></h3>
<p>Our C/C++ code follows the <a class="reference external" href="http://google.github.io/styleguide/cppguide.html">Google style guide</a>.</p>
<p>Our Python code follows the <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP8 style guide</a>.</p>
<p>Our build process helps to check the code style.  In <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/blob/b84e8226514b8bb4405c3c28e54aa5077193d179/paddle/scripts/docker/build.sh#L42"><code class="docutils literal"><span class="pre">build.sh</span></code></a>, the entry point of our <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/blob/b84e8226514b8bb4405c3c28e54aa5077193d179/Dockerfile#L88">builder Docker image</a>, the CMake argument <code class="docutils literal"><span class="pre">WITH_STYLE_CHECK</span></code> is set to <code class="docutils literal"><span class="pre">ON</span></code> by default.  This flag is on</p>
<p>Please install pre-commit, which automatically reformat the changes to C/C++ and Python code whenever we run <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span></code>.  To check the whole codebase, we can run the command <code class="docutils literal"><span class="pre">pre-commit</span> <span class="pre">run</span> <span class="pre">-a</span></code>, as in the <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/blob/b84e8226514b8bb4405c3c28e54aa5077193d179/paddle/scripts/travis/check_style.sh#L30"><code class="docutils literal"><span class="pre">check_style.sh</span></code> file</a>, which is invoked by <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/blob/b84e8226514b8bb4405c3c28e54aa5077193d179/.travis.yml#L43">our Travis CI configuration</a>.</p>
</div>
<div class="section" id="unit-tests">
<span id="unit-tests"></span><h3>Unit Tests<a class="headerlink" href="#unit-tests" title="Permalink to this headline">¶</a></h3>
<p>Please remember to add related unit tests.</p>
<ul class="simple">
<li>For C/C++ code, please follow <a class="reference external" href="https://github.com/google/googletest/blob/master/googletest/docs/Primer.md"><code class="docutils literal"><span class="pre">google-test</span></code> Primer</a>.</li>
<li>For Python code, please use <a class="reference external" href="http://pythontesting.net/framework/unittest/unittest-introduction/">Python&#8217;s standard <code class="docutils literal"><span class="pre">unittest</span></code> package</a>.</li>
</ul>
</div>
<div class="section" id="writing-logs">
<span id="writing-logs"></span><h3>Writing Logs<a class="headerlink" href="#writing-logs" title="Permalink to this headline">¶</a></h3>
<p>We use <a class="reference external" href="https://github.com/google/glog">glog</a> for logging in our C/C++ code.</p>
<p>For general information, please use <code class="docutils literal"><span class="pre">LOG</span></code>.  For debug information, please use <a class="reference external" href="http://htmlpreview.github.io/?https://github.com/google/glog/blob/master/doc/glog.html#verbose"><code class="docutils literal"><span class="pre">VLOG</span></code></a>.  The reason is at <a class="reference external" href="https://groups.google.com/a/chromium.org/d/msg/chromium-dev/3NDNd1KzXeY/AZKMMx37fdQJ">here</a>.</p>
<p><code class="docutils literal"><span class="pre">VLOG</span></code> requires a <em>verbose level</em> parameter.  For example:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">VLOG</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="o">&lt;&lt;</span> <span class="s">&quot;Operator FC is taking &quot;</span> <span class="o">&lt;&lt;</span> <span class="n">num_inputs</span> <span class="o">&lt;&lt;</span> <span class="s">&quot;inputs.&quot;</span>
</pre></div>
</div>
<p>When we run a PaddlePaddle application or test, we can specify a verbose threshold.  For example:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="nv">GLOG_vmodule</span><span class="o">=</span><span class="nv">buddy_allocator</span><span class="o">=</span><span class="m">2</span> <span class="se">\</span>
<span class="nv">GLOG_v</span><span class="o">=</span><span class="m">10</span> <span class="se">\</span>
python <span class="se">\</span>
../python/paddle/v2/framework/tests/test_recurrent_op.py
</pre></div>
</div>
<p>This will enable VLOG messages generated by <code class="docutils literal"><span class="pre">buddy_allocator.{h,cc}</span></code> and in the verbose range of 0 to 3, so you will see above example VLOG message, which is in level 3.  This suggests that we output overall messages in lower verbose levels, so they display with higher probability.  When coding C++, please follow the verbose level convention as follows:</p>
<ul class="simple">
<li>verbose level 1: <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/framework">framework</a></li>
<li>verbose level 3: <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/operators">operators</a></li>
<li>verbose level 5: <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/memory">memory</a>, <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/platform">platform</a></li>
<li>verbose level 7: <a class="reference external" href="https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/math">math</a></li>
</ul>
</div>
</div>
</div>


           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="write_docs_en.html" class="btn btn-neutral float-right" title="Contribute Documentation" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="index_en.html" class="btn btn-neutral" title="Development" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, PaddlePaddle developers.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'../',
            VERSION:'',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true
        };
    </script>
      <script type="text/javascript" src="../_static/jquery.js"></script>
      <script type="text/javascript" src="../_static/underscore.js"></script>
      <script type="text/javascript" src="../_static/doctools.js"></script>
      <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

  
    <script type="text/javascript" src="../_static/js/theme.js"></script>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>