Google Git
Sign in
apache / singa-site / be983bc44db8673b80f36c133d1ceb12926645fd / . / content / en / develop / contribute-code.html
blob: 89b9deaaae1e5c4f380d50c8aba6e452efcee370 [file] [log] [blame]
<!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>How to Contribute Code &mdash; singa 2.0.0 documentation</title>
<script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.0.0',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="../_static/js/theme.js"></script>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="How to Contribute to Documentation" href="contribute-docs.html" />
<link rel="prev" title="Security" href="../security.html" />
<link href="../_static/style.css" rel="stylesheet" type="text/css">
<!--link href="../_static/fontawesome-all.min.css" rel="stylesheet" type="text/css"-->
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.0.13/css/all.css"
integrity="sha384-DNOHZ68U8hZfKXOrtjWvjxusGo9WQnrNx2sqG0tfsghAvtVlRW3tvkXWZh58N9jp" crossorigin="anonymous">
<style>
.fa:hover {
opacity: 0.7;
}
.fab:hover {
opacity: 0.7;
}
</style>
</head>
<body class="wy-body-for-nav">
<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.html" class="icon icon-home"> singa
<img src="../_static/singa.png" class="logo" alt="Logo"/>
</a>
<div class="version">
latest
</div>
<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">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../docs/index.html">Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../downloads.html">Download SINGA</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security.html">Security</a></li>
</ul>
<p class="caption"><span class="caption-text">Development</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">How to Contribute Code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#coding-style">Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="#jira-format">JIRA format</a></li>
<li class="toctree-l2"><a class="reference internal" href="#git-workflow">Git Workflow</a></li>
<li class="toctree-l2"><a class="reference internal" href="#developing-environment">Developing Environment</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="contribute-docs.html">How to Contribute to Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="how-to-release.html">How to prepare a release</a></li>
</ul>
<p class="caption"><span class="caption-text">Community</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../community/source-repository.html">Source Repository</a></li>
<li class="toctree-l1"><a class="reference internal" href="../community/mail-lists.html">Project Mailing Lists</a></li>
<li class="toctree-l1"><a class="reference internal" href="../community/issue-tracking.html">Issue Tracking</a></li>
<li class="toctree-l1"><a class="reference internal" href="../community/team-list.html">The SINGA Team</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">singa</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.html">Docs</a> &raquo;</li>
<li>How to Contribute Code</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
--><div class="section" id="how-to-contribute-code">
<h1>How to Contribute Code<a class="headerlink" href="#how-to-contribute-code" title="Permalink to this headline"></a></h1>
<div class="section" id="coding-style">
<h2>Coding Style<a class="headerlink" href="#coding-style" title="Permalink to this headline"></a></h2>
<p>The SINGA codebase follows the Google Style for both <a class="reference external" href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">CPP</a> and <a class="reference external" href="http://google.github.io/styleguide/pyguide.html">Python</a> code.</p>
<p>A simple way to enforce the Google coding styles is to use the linting and formating tools in the Visual Studio Code editor:</p>
<ul class="simple">
<li><a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools">C/C++ extension</a></li>
<li><a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=ms-python.python">Python extension</a></li>
</ul>
<p>Once the extensions are installed, edit the settings.json file.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;editor.formatOnSave&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
<span class="s2">&quot;python.formatting.provider&quot;</span><span class="p">:</span> <span class="s2">&quot;yapf&quot;</span><span class="p">,</span>
<span class="s2">&quot;python.formatting.yapfArgs&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;--style&quot;</span><span class="p">,</span>
<span class="s2">&quot;{based_on_style: google}&quot;</span>
<span class="p">],</span>
<span class="s2">&quot;python.linting.enabled&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
<span class="s2">&quot;python.linting.lintOnSave&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
<span class="s2">&quot;C_Cpp.clang_format_style&quot;</span><span class="p">:</span> <span class="s2">&quot;Google&quot;</span>
</pre></div>
</div>
<p>You need to fix the format errors before submitting the pull requests.</p>
</div>
<div class="section" id="jira-format">
<h2>JIRA format<a class="headerlink" href="#jira-format" title="Permalink to this headline"></a></h2>
<p>Like other Apache projects, SINGA uses JIRA to track bugs, improvements and
other high-level discussions (e.g., system design and features). Github pull requests are
used for implementation discussions, e.g., code review and code merge.</p>
<ul class="simple">
<li>Provide a descriptive Title.</li>
<li>Write a detailed Description. For bug reports, this should ideally include a
short reproduction of the problem. For new features, it may include a design
document.</li>
<li>Set <a class="reference external" href="https://cwiki.apache.org/confluence/display/SPARK/Contributing+to+Spark#ContributingtoSpark-JIRA">required fields</a></li>
</ul>
</div>
<div class="section" id="git-workflow">
<h2>Git Workflow<a class="headerlink" href="#git-workflow" title="Permalink to this headline"></a></h2>
<ol>
<li><p class="first">Fork the <a class="reference external" href="https://github.com/apache/singa">SINGA Github repository</a> to your own Github account.</p>
</li>
<li><p class="first">Clone the <strong>repo</strong> (short for repository) from your Github</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/&lt;</span><span class="n">Github</span> <span class="n">account</span><span class="o">&gt;/</span><span class="n">singa</span><span class="o">.</span><span class="n">git</span>
<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">apache</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">apache</span><span class="o">/</span><span class="n">singa</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
</li>
<li><p class="first">Create a new branch (e.g., <code class="docutils literal"><span class="pre">feature-foo</span></code> or <code class="docutils literal"><span class="pre">fixbug-foo</span></code>), work on it and commit your code.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">feature</span><span class="o">-</span><span class="n">foo</span>
<span class="c1"># write your code</span>
<span class="n">git</span> <span class="n">add</span> <span class="o">&lt;</span><span class="n">created</span><span class="o">/</span><span class="n">updated</span> <span class="n">files</span><span class="o">&gt;</span>
<span class="n">git</span> <span class="n">commit</span>
</pre></div>
</div>
<p>The commit message should have a <strong>title which consists of the JIRA ticket No (SINGA-xxx) and title</strong>. A brief description of the commit should be added in the commit message.</p>
<p>If your branch has many small commits, you need to clean those commits via</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">rebase</span> <span class="o">-</span><span class="n">i</span> <span class="o">&lt;</span><span class="n">commit</span> <span class="nb">id</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>You can <a class="reference external" href="https://help.github.com/en/articles/about-git-rebase">squash and reword</a> the commits.</p>
</li>
<li><p class="first">When you are working on the code, the <code class="docutils literal"><span class="pre">master</span></code> of SINGA may have been updated by others; In this case, you need to pull the latest master</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">pull</span> <span class="n">apache</span> <span class="n">master</span><span class="p">:</span><span class="n">master</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="n">feature</span><span class="o">-</span><span class="n">foo</span>
</pre></div>
</div>
</li>
<li><p class="first"><a class="reference external" href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">Rebase</a> <code class="docutils literal"><span class="pre">feature-foo</span></code> onto the <code class="docutils literal"><span class="pre">master</span></code> branch and push commits to your own Github account (the new branch).</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">rebase</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">push</span> <span class="n">origin</span> <span class="n">feature</span><span class="o">-</span><span class="n">foo</span><span class="p">:</span><span class="n">feature</span><span class="o">-</span><span class="n">foo</span>
</pre></div>
</div>
</li>
<li><p class="first">Open a pull request (PR) against the master branch of apache/singa on Github website. The PR title should be the JIRA ticket title. If you want to inform other contributors who worked on the same files, you can find the file(s) on Github and click &#8220;Blame&#8220; to see a line-by-line annotation of who changed the code last. Then, you can add &#64;username in the PR description to ping them immediately. Please state that the contribution is your original work and that you license the work to the project under the project&#8216;s open source license. Further commits (e.g., bug fix) to your new branch will be added to this pull request automatically by Github.</p>
</li>
<li><p class="first">Wait for committers to review the PR. If no conflicts and errors, the committers will merge it with the master branch. The merge should <strong>a) not use rebase b) disable fast forward merge c) check the commit message format and test the code/feature</strong>. During this time, the master of SINGA may have been updated by others, and then you need to <a class="reference external" href="https://docs.fast.ai/dev/git.html#how-to-keep-your-feature-branch-up-to-date">merge the latest master</a> to resolve conflicts. Some people <a class="reference external" href="https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request">rebase the PR onto the latest master</a> instead of merging. However, if other developers fetch this PR to add new features and then send PR, the rebase operation would introduce <strong>duplicate commits</strong> (with different hash) in the future PR. See <a class="reference external" href="https://www.atlassian.com/git/tutorials/merging-vs-rebasing">The Golden Rule of Rebasing</a> for the details of when to avoid using rebase. Another simple solution to update the PR (to fix conflicts or commit errors) is to checkout a new branch from the latest master branch of Apache SINGAS repo; copy and paste the updated/added code; commit and send a new PR.</p>
</li>
</ol>
</div>
<div class="section" id="developing-environment">
<h2>Developing Environment<a class="headerlink" href="#developing-environment" title="Permalink to this headline"></a></h2>
<p>Visual Studio Code is recommended as the editor. Extensions like Python, C/C++, Code Spell Checker, autoDocstring, vim, Remote Development could be installed. A reference configuration (i.e., <code class="docutils literal"><span class="pre">settings.json</span></code>) of these extensions is <a class="reference external" href="https://gist.github.com/nudles/3d23cfb6ffb30ca7636c45fe60278c55">here</a>.</p>
<p>If you update the CPP code, you need to recompile SINGA <a class="reference internal" href="build.html"><span class="doc">from source</span></a>. It is recommended to use the native building tools in the <code class="docutils literal"><span class="pre">*-devel</span></code> Docker images or <code class="docutils literal"><span class="pre">conda</span> <span class="pre">build</span></code>.</p>
<p>If you only update the Python code, you can install SINGAS once, and then copy the updated Python files to replace those in the Python installation folder,</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">cp</span> <span class="n">python</span><span class="o">/</span><span class="n">singa</span><span class="o">/</span><span class="n">xx</span><span class="o">.</span><span class="n">py</span> <span class="o">&lt;</span><span class="n">path</span> <span class="n">to</span> <span class="n">conda</span><span class="o">&gt;/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="o">.</span><span class="mi">7</span><span class="o">/</span><span class="n">site</span><span class="o">-</span><span class="n">packages</span><span class="o">/</span><span class="n">singa</span><span class="o">/</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="contribute-docs.html" class="btn btn-neutral float-right" title="How to Contribute to Documentation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="../security.html" class="btn btn-neutral float-left" title="Security" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2019 The Apache Software Foundation. All rights reserved. Apache SINGA, Apache, the Apache feather logo, and the Apache SINGA project logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/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">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> singa </span>
v: latest
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>Languages</dt>
<dd><a href=".././index.html">English</a></dd>
<dd><a href=".././zh/index.html">中文</a></dd>
</dl>
<dl>
<dt>Versions</dt>
<dd><a href="http://singa.apache.org/v0.3.0/">0.3</a></dd>
<dd><a href="http://singa.apache.org/v1.1.0/">1.1</a></dd>
</dl>
</div>
<a href="http://www.apache.org"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Foundation</a>
<a href="http://www.apache.org/events/current-event"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Events</a>
<a href="http://www.apache.org/foundation/thanks.html"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Thanks</a>
<a href="http://www.apache.org/foundation/sponsorship.html"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">Sponsorship</a>
<a href="http://www.apache.org/licenses/"
style="color:lightblue;padding: 5px; font-size: 10px; text-align: center; text-decoration: none; margin: 5px 2px;">License</a>
<br>
<a href="https://github.com/apache/singa" class="fa fa-github"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://aws.amazon.com/marketplace/seller-profile?id=5bcac385-12c4-4802-aec7-351e09b77b4c"
class="fab fa-aws"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://hub.docker.com/r/apache/singa/" class="fab fa-docker"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://www.linkedin.com/groups/13550034" class="fa fa-linkedin"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://twitter.com/ApacheSinga" class="fa fa-twitter"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://www.facebook.com/Apache-SINGA-347284219056544/" class="fa fa-facebook"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
<a href="https://www.researchgate.net/project/Apache-SINGA" class="fab fa-researchgate"
style="padding: 10px; font-size: 20px; width: 30px; text-align: center; text-decoration: none; margin: 5px 2px;"></a>
</div>
<a href="https://github.com/apache/singa">
<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub">
</a>
</body>
</html>