| <!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>How to Contribute Code · Apache SINGA</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="<!--- 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. -->"/><meta name="docsearch:version" content="2.0.0"/><meta name="docsearch:language" content="en"/><meta property="og:title" content="How to Contribute Code · Apache SINGA"/><meta property="og:type" content="website"/><meta property="og:url" content="https://feynmandna.github.io/"/><meta property="og:description" content="<!--- 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. -->"/><meta property="og:image" content="https://feynmandna.github.io/img/singa_twitter_banner.jpeg"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://feynmandna.github.io/img/singa_twitter_banner.jpeg"/><link rel="shortcut icon" href="/img/favicon.ico"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://feynmandna.github.io/blog/atom.xml" title="Apache SINGA Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://feynmandna.github.io/blog/feed.xml" title="Apache SINGA Blog RSS Feed"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><script src="https://unpkg.com/vanilla-back-to-top@7.1.14/dist/vanilla-back-to-top.min.js"></script><script> |
| document.addEventListener('DOMContentLoaded', function() { |
| addBackToTop( |
| {"zIndex":100} |
| ) |
| }); |
| </script><script src="/js/scrollSpy.js"></script><link rel="stylesheet" href="/css/main.css"/><script src="/js/codetabs.js"></script></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/"><img class="logo" src="/img/singa.png" alt="Apache SINGA"/></a><a href="/versions"><h3>2.0.0</h3></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class="siteNavGroupActive"><a href="/docs/2.0.0/installation" target="_self">Docs</a></li><li class=""><a href="/docs/2.0.0/source-repository" target="_self">Community</a></li><li class=""><a href="/blog/" target="_self">News</a></li><li class=""><a href="https://apache-singa.readthedocs.io/en/latest/" target="_self">API</a></li><li class=""><a target="_self"></a></li><li class=""><a href="https://github.com/apache/singa-doc" target="_self">GitHub</a></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><div class="hamburger-menu"><div class="line1"></div><div class="line2"></div><div class="line3"></div></div></div><h2><i>›</i><span>Development</span></h2><div class="tocToggler" id="tocToggler"><i class="icon-toc"></i></div></div><div class="navGroups"><div class="navGroup"><h3 class="navGroupCategoryTitle">Getting Started</h3><ul class=""><li class="navListItem"><a class="navItem" href="/docs/2.0.0/installation">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/software-stack">Software Stack</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/benchmark-train">Benchmark for Distributed Training</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Guides</h3><ul class=""><li class="navListItem"><a class="navItem" href="/docs/2.0.0/device">Device</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/tensor">Tensor</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/autograd">Autograd in SINGA</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Model Zoo</h3><ul class=""><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-cnn-cifar10">Train CNN over Cifar-10</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-char-rnn">Train Char-RNN over plain text</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-rbm-mnist">Train a RBM model against MNIST dataset</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-imagenet-alexnet">Train AlexNet over ImageNet</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-imagenet-densenet">Image Classification using DenseNet</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-imagenet-googlenet">Image Classification using GoogleNet</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-imagenet-inception">Image Classification using Inception V4</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-imagenet-resnet">Image Classification using Residual Networks</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/model-zoo-imagenet-vgg">Image Classification using VGG</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Development</h3><ul class=""><li class="navListItem"><a class="navItem" href="/docs/2.0.0/download-singa">Download SINGA</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/build">Build SINGA from Source</a></li><li class="navListItem navListItemActive"><a class="navItem" href="/docs/2.0.0/contribute-code">How to Contribute Code</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/contribute-docs">How to Contribute to Documentation</a></li><li class="navListItem"><a class="navItem" href="/docs/2.0.0/how-to-release">How to Prepare a Release</a></li></ul></div></div></section></div><script> |
| var coll = document.getElementsByClassName('collapsible'); |
| var checkActiveCategory = true; |
| for (var i = 0; i < coll.length; i++) { |
| var links = coll[i].nextElementSibling.getElementsByTagName('*'); |
| if (checkActiveCategory){ |
| for (var j = 0; j < links.length; j++) { |
| if (links[j].classList.contains('navListItemActive')){ |
| coll[i].nextElementSibling.classList.toggle('hide'); |
| coll[i].childNodes[1].classList.toggle('rotate'); |
| checkActiveCategory = false; |
| break; |
| } |
| } |
| } |
| |
| coll[i].addEventListener('click', function() { |
| var arrow = this.childNodes[1]; |
| arrow.classList.toggle('rotate'); |
| var content = this.nextElementSibling; |
| content.classList.toggle('hide'); |
| }); |
| } |
| |
| document.addEventListener('DOMContentLoaded', function() { |
| createToggler('#navToggler', '#docsNav', 'docsSliderActive'); |
| createToggler('#tocToggler', 'body', 'tocActive'); |
| |
| var headings = document.querySelector('.toc-headings'); |
| headings && headings.addEventListener('click', function(event) { |
| var el = event.target; |
| while(el !== headings){ |
| if (el.tagName === 'A') { |
| document.body.classList.remove('tocActive'); |
| break; |
| } else{ |
| el = el.parentNode; |
| } |
| } |
| }, false); |
| |
| function createToggler(togglerSelector, targetSelector, className) { |
| var toggler = document.querySelector(togglerSelector); |
| var target = document.querySelector(targetSelector); |
| |
| if (!toggler) { |
| return; |
| } |
| |
| toggler.onclick = function(event) { |
| event.preventDefault(); |
| |
| target.classList.toggle(className); |
| }; |
| } |
| }); |
| </script></nav></div><div class="container mainContainer docsContainer"><div class="wrapper"><div class="post"><header class="postHeader"><a class="edit-page-link button" href="https://github.com/apache/singa-doc/blob/master/docs/contribute-code.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 id="__docusaurus" class="postHeaderTitle">How to Contribute Code</h1></header><article><div><span><!--- 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. --> |
| <h2><a class="anchor" aria-hidden="true" id="coding-style"></a><a href="#coding-style" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Coding Style</h2> |
| <p>The SINGA codebase follows the Google Style for both <a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">CPP</a> and <a 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> |
| <li><a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools">C/C++ extension</a></li> |
| <li><a href="https://marketplace.visualstudio.com/items?itemName=ms-python.python">Python extension</a></li> |
| </ul> |
| <p>Once the extensions are installed, edit the <code>settings.json</code> file.</p> |
| <pre><code class="hljs css language-json">"editor.formatOnSave": true, |
| "python.formatting.provider": "yapf", |
| "python.formatting.yapfArgs": [ |
| "--style", |
| "{based_on_style: google}" |
| ], |
| "python.linting.enabled": true, |
| "python.linting.lintOnSave": true, |
| "C_Cpp.clang_format_style": "Google" |
| </code></pre> |
| <p>You need to fix the format errors before submitting the pull requests.</p> |
| <h2><a class="anchor" aria-hidden="true" id="jira-format"></a><a href="#jira-format" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>JIRA format</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> |
| <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 href="https://cwiki.apache.org/confluence/display/SPARK/Contributing+to+Spark#ContributingtoSpark-JIRA">required fields</a></li> |
| </ul> |
| <h2><a class="anchor" aria-hidden="true" id="git-workflow"></a><a href="#git-workflow" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Git Workflow</h2> |
| <ol> |
| <li><p>Fork the <a href="https://github.com/apache/singa">SINGA Github repository</a> to your own Github account.</p></li> |
| <li><p>Clone the <strong>repo</strong> (short for repository) from your Github</p> |
| <pre><code class="hljs css language-shell">git clone https://github.com/<Github account>/singa.git |
| git remote add apache https://github.com/apache/singa.git |
| </code></pre></li> |
| <li><p>Create a new branch (e.g., <code>feature-foo</code> or <code>fixbug-foo</code>), work on it and commit your code.</p> |
| <pre><code class="hljs css language-shell">git checkout -b feature-foo |
| <span class="hljs-meta">#</span><span class="bash"> write your code</span> |
| git add <created/updated files> |
| git commit |
| </code></pre> |
| <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> |
| <pre><code class="hljs css language-shell">git rebase -i <commit id> |
| </code></pre> |
| <p>You can <a href="https://help.github.com/en/articles/about-git-rebase">squash and reword</a> the commits.</p></li> |
| <li><p>When you are working on the code, the <code>master</code> of SINGA may have been updated by others; In this case, you need to pull the latest master</p> |
| <pre><code class="hljs css language-shell">git checkout master |
| git pull apache master:master |
| git checkout feature-foo |
| </code></pre></li> |
| <li><p><a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">Rebase</a> <code>feature-foo</code> onto the <code>master</code> branch and push commits to your own Github account (the new branch).</p> |
| <pre><code class="hljs css language-shell">git rebase master |
| git push origin feature-foo:feature-foo |
| </code></pre></li> |
| <li><p>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 "Blame" to see a line-by-line annotation of who changed the code last. Then, you can add @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'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>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 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 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 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> |
| <h2><a class="anchor" aria-hidden="true" id="developing-environment"></a><a href="#developing-environment" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Developing Environment</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>settings.json</code>) of these extensions is <a href="https://gist.github.com/nudles/3d23cfb6ffb30ca7636c45fe60278c55">here</a>.</p> |
| <p>If you update the CPP code, you need to recompile SINGA <a href="/docs/2.0.0/build">from source</a>. It is recommended to use the native building tools in the <code>*-devel</code> Docker images or <code>conda build</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> |
| <pre><code class="hljs css language-shell">cp python/singa/xx.py <path to conda>/lib/python3.7/site-packages/singa/ |
| </code></pre> |
| </span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="/docs/2.0.0/build"><span class="arrow-prev">← </span><span>Build SINGA from Source</span></a><a class="docs-next button" href="/docs/2.0.0/contribute-docs"><span>How to Contribute to Documentation</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#coding-style">Coding Style</a></li><li><a href="#jira-format">JIRA format</a></li><li><a href="#git-workflow">Git Workflow</a></li><li><a href="#developing-environment">Developing Environment</a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="sitemap"><a href="/" class="nav-home"><img src="/img/singa-logo-square.png" alt="Apache SINGA" width="66" height="58"/></a><div><h5>Docs</h5><a href="/docs/installation">Getting Started</a><a href="/docs/device">Guides</a><a href="/en/#">API Reference (coming soon)</a><a href="/docs/model-zoo-cnn-cifar10">Model Zoo</a><a href="/docs/download-singa">Development</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a><a href="/docs/history-singa">SINGA History</a><a href="/docs/team-list">SINGA Team</a><a href="/news">SINGA News</a><a href="https://github.com/apache/singa-doc">GitHub</a><div class="social"><a class="github-button" href="https://github.com/apache/singa-doc" data-count-href="/apache/singa/stargazers" data-show-count="true" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">apache/singa-doc</a></div><div class="social"><a href="https://twitter.com/ApacheSINGA" class="twitter-follow-button">Follow @ApacheSINGA</a></div></div><div><h5>Apache Software Foundation</h5><a href="https://apache.org/" target="_blank" rel="noreferrer noopener">Foundation</a><a href="http://www.apache.org/licenses/" target="_blank" rel="noreferrer noopener">License</a><a href="http://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noreferrer noopener">Sponsorship</a><a href="http://www.apache.org/foundation/thanks.html" target="_blank" rel="noreferrer noopener">Thanks</a><a href="http://www.apache.org/events/current-event" target="_blank" rel="noreferrer noopener">Events</a><a href="http://www.apache.org/security/" target="_blank" rel="noreferrer noopener">Security</a></div></section><div style="width:100%;text-align:center"><a href="https://apache.org/" target="_blank" rel="noreferrer noopener" class="ApacheOpenSource"><img src="/img/asf_logo_wide.svg" alt="Apache Open Source"/></a><section class="copyright" style="max-width:60%;margin:0 auto">Copyright © 2020 |
| 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.</section></div></footer></div><script>window.twttr=(function(d,s, id){var js,fjs=d.getElementsByTagName(s)[0],t=window.twttr||{};if(d.getElementById(id))return t;js=d.createElement(s);js.id=id;js.src='https://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js, fjs);t._e = [];t.ready = function(f) {t._e.push(f);};return t;}(document, 'script', 'twitter-wjs'));</script></body></html> |
