| |
| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <title>Contributions</title> |
| <meta name="description" content=""> |
| <meta name="author" content="The Apache Software Foundation"> |
| |
| <!-- Enable responsive viewport --> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" /> |
| |
| <!-- Le HTML5 shim, for IE6-8 support of HTML elements --> |
| <!--[if lt IE 9]> |
| <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script> |
| <![endif]--> |
| |
| <!-- Le styles --> |
| <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"> |
| <link href="https://fonts.googleapis.com/icon?family=Material+Icons"> |
| <link href="/assets/themes/submarine/bootstrap/css/bootstrap.css" rel="stylesheet"> |
| <link href="/assets/themes/submarine/css/style.css?body=1" rel="stylesheet" type="text/css"> |
| <link href="/assets/themes/submarine/css/syntax.css" rel="stylesheet" type="text/css" media="screen" /> |
| <!-- Le fav and touch icons --> |
| <!-- Update these with your own images |
| <link rel="shortcut icon" href="images/favicon.ico"> |
| <link rel="apple-touch-icon" href="images/apple-touch-icon.png"> |
| <link rel="apple-touch-icon" sizes="72x72" href="images/apple-touch-icon-72x72.png"> |
| <link rel="apple-touch-icon" sizes="114x114" href="images/apple-touch-icon-114x114.png"> |
| --> |
| <link rel="apple-touch-icon" sizes="180x180" href="/assets/themes/submarine/img/favicon/apple-touch-icon.png"> |
| <link rel="icon" type="image/png" sizes="32x32" href="/assets/themes/submarine/img/favicon/favicon-32x32.png"> |
| <link rel="icon" type="image/png" sizes="16x16" href="/assets/themes/submarine/img/favicon/favicon-16x16.png"> |
| <link rel="icon" type="image/png" href="/assets/themes/submarine/img/favicon/favicon.ico"> |
| <link rel="manifest" href="/assets/themes/submarine/img/favicon/manifest.json"> |
| <link rel="mask-icon" href="/assets/themes/submarine/img/favicon/safari-pinned-tab.svg" color="#438bc9"> |
| <meta name="theme-color" content="#ffffff"> |
| |
| <!-- Js --> |
| <script src="https://code.jquery.com/jquery-1.10.2.min.js"></script> |
| <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.15/angular.min.js"></script> |
| <script src="https://angular-ui.github.io/bootstrap/ui-bootstrap-tpls-2.5.0.js"></script> |
| <script src="/assets/themes/submarine/bootstrap/js/bootstrap.min.js"></script> |
| <script src="/assets/themes/submarine/js/docs.js"></script> |
| <script src="/assets/themes/submarine/js/anchor.min.js"></script> |
| <script src="/assets/themes/submarine/js/moment.min.js"></script> |
| <script src="/assets/themes/submarine/js/helium.controller.js"></script> |
| <script src="/assets/themes/submarine/js/medium.controller.js"></script> |
| |
| <!-- atom & rss feed --> |
| <link href="/atom.xml" type="application/atom+xml" rel="alternate" title="Sitewide ATOM Feed"> |
| <link href="/rss.xml" type="application/rss+xml" rel="alternate" title="Sitewide RSS Feed"> |
| </head> |
| |
| <body> |
| |
| <div class="navbar navbar-inverse navbar-fixed-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="/"> |
| <img src="/assets/themes/submarine/img/submarine_white_logo.png" style="margin-top: -6px;" width="80" alt="I'm submarine"> |
| <span style="margin-left: 0px;"> Apache Submarine </span> |
| <!-- <span style="margin-left: 4px; font-size: 16px; font-family: Arial;">0.4.0</span> --> |
| </a> |
| </div> |
| |
| <nav class="navbar-collapse collapse" role="navigation"> |
| <ul class="nav navbar-nav navbar-right"> |
| <!-- Quick Start --> |
| <li class="docs"> |
| <a href="#" data-toggle="dropdown" class="dropdown-toggle">Quick Start<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://github.com/apache/submarine/blob/master/docs/userdocs/yarn">Submarine on YARN</a></li> |
| <li><a href="https://github.com/apache/submarine/blob/master/docs/userdocs/k8s">Submarine on K8s</a></li> |
| </ul> |
| </li> |
| |
| <!-- Download --> |
| <li><a href="/download.html">Download</a></li> |
| |
| <!-- Docs --> |
| <li><a href="https://github.com/apache/submarine/tree/master/docs">Docs</a></li> |
| |
| <!-- GitHub --> |
| <li> |
| <a href="https://github.com/apache/submarine">GitHub</a> |
| </li> |
| |
| <!-- Community --> |
| <li class="docs"> |
| <a href="#" data-toggle="dropdown" class="dropdown-toggle">Community<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="/community/contributors.html">Contributors</a></li> |
| <li><a href="/community/member.html">Member</a></li> |
| </ul> |
| </li> |
| |
| <!-- Apache --> |
| <li class="docs"> |
| <a href="#" data-toggle="dropdown" class="dropdown-toggle">Apache<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="http://www.apache.org/foundation/how-it-works.html">Apache Software Foundation</a></li> |
| <li><a href="http://www.apache.org/licenses/">Apache License</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="/assets.html">Assets</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| </div> |
| |
| |
| |
| |
| <div class="content"> |
| |
| |
| <div class="row"> |
| |
| <div class="sideMenu col-sm-3"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="active"><a href="/contribution/contributions.html" class="active">Contributions</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="/contribution/documentation.html">Documentation</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="/contribution/webapplication.html">Web Application</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="col-sm-9"> |
| <!-- |
| Licensed 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. |
| --> |
| |
| <h1>Contribution Guidelines</h1> |
| |
| <p><strong>Apache Submarine</strong> is an <a href="https://github.com/apache/submarine/blob/master/CONTRIBUTING.md">Apache2 License</a> Software.</p> |
| |
| <p>Contributing to Submarine (Source code, Documents, Image, Website) means you agree to the Apache2 License.</p> |
| |
| <ol> |
| <li>Make sure your issue is not already in the <a href="https://issues.apache.org/jira/browse/SUBMARINE">Jira issue tracker</a></li> |
| <li>If not, create a ticket describing the change you're proposing in the <a href="https://issues.apache.org/jira/browse/SUBMARINE">Jira issue tracker</a></li> |
| <li>Setup travis <a href="#continuous-integration">Continuous Integration</a></li> |
| <li>Contribute your patch via Pull Request on our <a href="https://github.com/apache/submarine">Github Mirror</a>.</li> |
| </ol> |
| |
| <p>Before you start, please read the <a href="http://www.apache.org/foundation/policies/conduct.html">Code of Conduct</a> carefully, familiarize yourself with it and refer to it whenever you need it.</p> |
| |
| <p>For those of you who are not familiar with Apache project, understanding <a href="http://www.apache.org/foundation/how-it-works.html">How it works</a> would be quite helpful.</p> |
| |
| <h2>Creating a Pull Request</h2> |
| |
| <p>When creating a Pull Request, you will automatically get the template below.</p> |
| |
| <p>Filling it thoroughly can improve the speed of the review process.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">### What is this PR for? |
| A few sentences describing the overall goals of the pull request's commits. |
| First time? Check out the contribution guidelines - https://submarine.apache.org/contribute.html |
| |
| ### What type of PR is it? |
| [Bug Fix | Improvement | Feature | Documentation | Hot Fix | Refactoring] |
| |
| ### Todos |
| * [ ] - Task |
| |
| ### What is the Jira issue? |
| * Open an issue on Jira https://issues.apache.org/jira/browse/SUBMARINE/ |
| * Put link here, and add [SUBMARINE-*Jira number*] in PR title, eg. [SUBMARINE-533] |
| |
| ### How should this be tested? |
| Outline the steps to test the PR here. |
| |
| ### Screenshots (if appropriate) |
| |
| ### Questions: |
| * Does the licenses files need update? |
| * Is there breaking changes for older versions? |
| * Does this needs documentation? |
| </code></pre></figure> |
| <h2>Testing a Pull Request</h2> |
| |
| <p>You can also test and review a particular Pull Request. Here are two useful ways.</p> |
| |
| <ul> |
| <li><p>Using a utility provided from Submarine.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">dev/test_submarine_pr.py [# of PR] |
| </code></pre></figure> |
| <p>For example, if you want to test <code>#513</code>, then the command will be:</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">dev/test_submarine_pr.py 513 |
| </code></pre></figure></li> |
| <li><p>Another way is using <a href="https://github.com/github/hub">github/hub</a>.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">hub checkout https://github.com/apache/submarine/pull/[# of PR] |
| </code></pre></figure></li> |
| </ul> |
| |
| <p>The above two methods will help you test and review Pull Requests.</p> |
| |
| <h2>Source Control Workflow</h2> |
| |
| <p>Submarine follows <a href="https://github.com/sevntu-checkstyle/sevntu.checkstyle/wiki/Development-workflow-with-Git:-Fork,-Branching,-Commits,-and-Pull-Request">Fork & Pull</a> model.</p> |
| |
| <h2>The Review Process</h2> |
| |
| <p>When a Pull Request is submitted, it is being merged or rejected by the following review process.</p> |
| |
| <ul> |
| <li>Anybody can be a reviewer and may comment on the change or suggest modifications.</li> |
| <li>Reviewer can indicate that a patch looks suitable for merging with a comment such as: "Looks good", "LGTM", "+1".</li> |
| <li>At least one indication of suitability (e.g. "LGTM") from a committer is required to be merged.</li> |
| <li>Pull request is open for 1 or 2 days for potential additional review, unless it's got enough indication of suitability.</li> |
| <li>A committer can then initiate lazy consensus ("Merge if there is no more discussion") after what the code can be merged after a certain time (normally 24 hours) if there is no more reviews.</li> |
| <li>Contributors can ping reviewers (including committers) by commenting 'Ready to review' or suitable indication.</li> |
| </ul> |
| |
| <h2>Becoming a Committer</h2> |
| |
| <p>The PMC adds new committers from the active contributors, based on their contribution to Submarine.</p> |
| |
| <p>The qualifications for new committers include:</p> |
| |
| <ol> |
| <li>Sustained contributions: Committers should have a history of constant contributions to Submarine.</li> |
| <li>Quality of contributions: Committers more than any other community member should submit simple, well-tested, and well-designed patches.</li> |
| <li>Community involvement: Committers should have a constructive and friendly attitude in all community interactions. They should also be active on the dev, user list and reviewing patches. Also help new contributors and users.</li> |
| </ol> |
| |
| <h2>Setting up</h2> |
| |
| <p>Here are some things you will need to build and test Submarine.</p> |
| |
| <h3>Software Configuration Management (SCM)</h3> |
| |
| <p>submarine uses Git for its SCM system. so you'll need git client installed in your development machine.</p> |
| |
| <h3>Integrated Development Environment (IDE)</h3> |
| |
| <p>You are free to use whatever IDE you prefer, or your favorite command line editor.</p> |
| |
| <h3>Code convention</h3> |
| |
| <p>We are following Google Code style:</p> |
| |
| <ul> |
| <li><a href="https://google.github.io/styleguide/javaguide.html">Java style</a></li> |
| <li><a href="https://google.github.io/styleguide/shell.xml">Shell style</a></li> |
| </ul> |
| |
| <p>There are some plugins to format, lint your code in IDE (use <a href="https://github.com/apache/submarine/tree/master/_tools">_tools/checkstyle.xml</a> as rules)</p> |
| |
| <ul> |
| <li><a href="https://plugins.jetbrains.com/plugin/1065">Checkstyle plugin for Intellij</a> (<a href="http://stackoverflow.com/questions/26955766/intellij-idea-checkstyle">Setting Guide</a>)</li> |
| <li><a href="http://eclipse-cs.sourceforge.net/#!/">Checkstyle plugin for Eclipse</a> (<a href="http://eclipse-cs.sourceforge.net/#!/project-setup">Setting Guide</a>)</li> |
| </ul> |
| |
| <p>Checkstyle report location is in <code>${submodule}/target/site/checkstyle.html</code> |
| Test coverage report location is in <code>${submodule}/target/site/cobertura/index.html</code></p> |
| |
| <h2>Getting the source code</h2> |
| |
| <p>First of all, you need the Submarine source code.</p> |
| |
| <p>The official location for Submarine is <a href="http://git.apache.org/submarine.git">http://git.apache.org/submarine.git</a>.</p> |
| |
| <h3>git access</h3> |
| |
| <p>Get the source code on your development machine using git.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">git clone git://git.apache.org/submarine.git submarine |
| </code></pre></figure> |
| <p>You may also want to develop against a specific branch. For example, for branch-0.5.6</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">git clone -b branch-0.5.6 git://git.apache.org/submarine.git submarine |
| </code></pre></figure> |
| <p>or with write access</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">git clone https://git-wip-us.apache.org/repos/asf/submarine.git |
| </code></pre></figure> |
| <h3>Fork repository</h3> |
| |
| <p>If you want not only build Submarine but also make change, then you need fork <a href="https://github.com/apache/submarine">Submarine github mirror repository</a> and make a pull request.</p> |
| |
| <h2>Build</h2> |
| |
| <h3>Build Tools</h3> |
| |
| <p>To build the code, install</p> |
| |
| <ul> |
| <li>Oracle Java 7</li> |
| <li>Apache Maven</li> |
| </ul> |
| |
| <h3>Building the code</h3> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">mvn install |
| </code></pre></figure> |
| <p>To skip test</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">mvn install -DskipTests |
| </code></pre></figure> |
| <p>To build with specific spark / hadoop version</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">mvn install -Phadoop-2.2 -Dhadoop.version=2.2.0 -Pspark-1.3 -Dspark.version=1.3.0 |
| </code></pre></figure> |
| <h2>Tests</h2> |
| |
| <p>Each new File should have its own accompanying unit tests. Each new interpreter should have come with its tests.</p> |
| |
| <p>submarine has 3 types of tests:</p> |
| |
| <ul> |
| <li><strong>Unit Tests:</strong> The unit tests run as part of each package's build. E.g. SparkInterpeter Module's unit test is SparkInterpreterTest</li> |
| <li><strong>Integration Tests:</strong> The integration tests run after all modules are build. The integration tests launch an instance of submarine server. submarineRestApiTest is an example integration test.</li> |
| <li><strong>GUI integration tests:</strong> These tests validate the submarine UI elements. These tests require a running submarine server and launches a web browser to validate Notebook UI elements like Notes and their execution. See submarineIT as an example.</li> |
| </ul> |
| |
| <p>Currently the <strong>GUI integration tests</strong> are not run in the Maven and are only run in the CI environment when the pull request is submitted to github.</p> |
| |
| <p>Make sure to watch the <a href="https://travis-ci.org/apache/submarine/pull_requests">CI results</a> for your pull request.</p> |
| |
| <h4>Running GUI integration tests locally</h4> |
| |
| <h5>All tests, just like the CI:</h5> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">PATH=~/Applications/Firefox.app/Contents/MacOS/:$PATH CI="true" mvn verify -Pspark-1.6 -Phadoop-2.3 -Ppyspark -B -pl "submarine-interpreter,submarine-zengine,submarine-server,submarine-display,spark-dependencies,spark" -Dtest="org.apache.submarine.AbstractFunctionalSuite" -DfailIfNoTests=false |
| </code></pre></figure> |
| <h5>Next to a Running instance of submarine</h5> |
| |
| <p>This allows you to target a specific <strong>GUI integration test</strong>.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">TEST_SELENIUM="true" mvn package -DfailIfNoTests=false -pl 'submarine-interpreter,submarine-zengine,submarine-server' -Dtest=ParagraphActionsIT |
| </code></pre></figure> |
| <h2>Continuous Integration</h2> |
| |
| <p>submarine project's CI system will collect information from pull request author's travis-ci and display status in the pull request.</p> |
| |
| <p>Each individual contributor should setup travis-ci for the fork before making a pullrequest. Go to <a href="https://travis-ci.org/profile">https://travis-ci.org/profile</a> and switch on 'submarine' repository.</p> |
| |
| <h2>Run submarine server in development mode</h2> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">cd submarine-server |
| HADOOP_HOME=YOUR_HADOOP_HOME JAVA_HOME=YOUR_JAVA_HOME mvn exec:java -Dexec.mainClass="org.apache.submarine.server.submarineServer" -Dexec.args="" |
| </code></pre></figure> |
| <p>or use daemon script</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">bin/submarine-daemon start |
| </code></pre></figure> |
| <p>Server will be run on http://localhost:8080</p> |
| |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <footer> |
| <!-- <p>© 2020 The Apache Software Foundation</p>--> |
| </footer> |
| </body> |
| </html> |
| |
