| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <!-- |
| 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 charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <link href="/css/bootstrap.min.css" rel="stylesheet"> |
| <link href="/css/bootstrap-theme.min.css" rel="stylesheet"> |
| <link href="/css/dataTables.bootstrap.css" rel="stylesheet"> |
| <link href="/css/pirk.css" rel="stylesheet" type="text/css"> |
| <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet"> |
| |
| <title>How to Contribute</title> |
| |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script> |
| <script src="/js/bootstrap.min.js"></script> |
| <script src="/js/jquery.dataTables.min.js"></script> |
| <script src="/js/dataTables.bootstrap.js"></script> |
| <script> |
| // show location of canonical site if not currently on the canonical site |
| $(function() { |
| var host = window.location.host; |
| if (typeof host !== 'undefined' && host !== 'pirk.incubator.apache.org') { |
| $('#non-canonical').show(); |
| } |
| }); |
| |
| |
| // decorate menu with currently navigated page |
| $(function() { |
| $("#nav_contribute").addClass("active"); |
| }); |
| |
| |
| $(function() { |
| // decorate section headers with anchors |
| return $("h2, h3, h4, h5, h6").each(function(i, el) { |
| var $el, icon, id; |
| $el = $(el); |
| id = $el.attr('id'); |
| icon = '<i class="fa fa-link"></i>'; |
| if (id) { |
| return $el.append($("<a />").addClass("header-link").attr("href", "#" + id).html(icon)); |
| } |
| }); |
| }); |
| |
| // configure Google Analytics |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-81114308-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| </head> |
| <body style="padding-top: 100px"> |
| |
| <nav class="navbar navbar-default navbar-fixed-top"> |
| <div class="container-fluid"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar-items"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a href="/"><img id="nav-logo" alt="Apache Pirk" class="img-responsive" src="/images/pirkImage.png" width="150"/></a> |
| </div> |
| <div class="collapse navbar-collapse" id="navbar-items"> |
| <ul class="nav navbar-nav"> |
| <li class="nav-link"><a href="/downloads">Download</a></li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li id="nav_users"><a href="/for_users">For Users</a></li> |
| <li id="nav_developers"><a href="/for_developers">For Developers</a></li> |
| <li id="nav_developers"><a href="/cloud_instructions">Cloud instructions</a></li> |
| <li id="nav_papers"><a href="/papers">Papers & Presentations</a></li> |
| <li class="nav_faq"><a href="/faq">FAQ</a></li> |
| <li class="divider"></li> |
| <li><a href="/javadocs">Javadocs</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Community<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li id="nav_getinvolvedpirk"><a href="/get_involved_pirk">Get Involved</a></li> |
| <li id="nav_listspirk"><a href="/mailing_list_pirk">Mailing Lists</a></li> |
| <li id="nav_peoplepirk"><a href="/people_pirk">People</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Development<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li id="nav_releasing"><a href="/how_to_contribute">How to Contribute</a></li> |
| <li id="nav_releasing"><a href="/releasing">Making Releases</a></li> |
| <li id="nav_nav_verify_release"><a href="/verifying_releases">Verifying Releases</a></li> |
| <li id="nav_update_website"><a href="/website_updates">Website Updates</a></li> |
| <hr> |
| <li><a href="https://issues.apache.org/jira/browse/PIRK ">Issue Tracker/JIRA <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://builds.apache.org/job/pirk/">Jenkins Builds <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://travis-ci.org/apache/incubator-pirk">Travis CI Builds <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://github.com/apache/incubator-pirk"> Pirk Github Mirror <i class="fa fa-external-link"></i></a></li> |
| </ul> |
| </li> |
| <li class="nav-link"><a href="/roadmap">Roadmap</a></li> |
| <ul class="nav navbar-nav navbar-right"> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://www.apache.org">Apache Homepage <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0">License <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship">Sponsorship <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://www.apache.org/security">Security <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://www.apache.org/foundation/thanks">Thanks <i class="fa fa-external-link"></i></a></li> |
| <li><a href="https://www.apache.org/foundation/policies/conduct">Code of Conduct <i class="fa fa-external-link"></i></a></li> |
| </ul> |
| </li> |
| </ul> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <div class="container"> |
| <div class="row"> |
| <div class="col-md-12"> |
| <div id="content"> |
| |
| <h1 class="title">How to Contribute</h1> |
| |
| <ol> |
| <li><a href="#contribution-philosophy">Contribution Philosophy</a></li> |
| <li><a href="#general-process">General Process</a></li> |
| <li><a href="#github-pull-requests">GitHub Pull Requests</a> |
| <ul> |
| <li><a href="#git-setup">Git Setup</a></li> |
| <li><a href="#creating-a-pull-request">Creating a Pull Request</a></li> |
| <li><a href="#merging-a-pull-request">Merging a Pull Request</a></li> |
| <li><a href="#closing-a-pull-request-without-committing">Closing a Pull Request Without Committing</a></li> |
| <li><a href="#apache-and-github-integration">Apache and GitHub Integration</a></li> |
| </ul> |
| </li> |
| </ol> |
| |
| <h2 id="contribution-philosophy">Contribution Philosophy</h2> |
| |
| <p>We welcome contributors of all kinds within the Apache Pirk community!</p> |
| |
| <p>A successful project requires many people to play many roles. Some members write code or documentation, while others are valuable as testers, submitting patches and suggestions. We also highly encourage the involvement of algorithmic team members who provide/discuss algorithmic ideas via the <a href="/mailing_list_pirk">dev mailing list</a> and who may or may not participate in their implementation.</p> |
| |
| <p>If you have algorithmic ideas or would like to discuss a potential implementation item, please reach out to the community via <a href="mailto:dev@pirk.incubator.apache.org">dev@pirk.incubator.apache.org</a> - we would love to hear from you!</p> |
| |
| <h2 id="general-process">General Process</h2> |
| |
| <p>The general process for code contribution is as follows:</p> |
| |
| <ol> |
| <li>Create a <a href="https://issues.apache.org/jira/browse/PIRK">Pirk JIRA issue</a></li> |
| <li>Fork the <a href="https://github.com/apache/incubator-pirk">Pirk source code</a> from your personal GitHub repository and clone locally</li> |
| <li>Modify the source code to add your awesome features; you will most likely be modifying the apache/incubator-pirk master branch (unless you are <a href="/website_updates">modifying the Pirk website</a>)</li> |
| <li>Ensure that all unit and functional tests pass</li> |
| <li>Ensure that your code follows the <a href="/for_developers#coding-standards">Pirk code standards</a></li> |
| <li>Ensure that any new third-party dependencies introduced in your code are accounted for in the appropriate license and notice files |
| <ul> |
| <li>Binary license and notice files for Pirk are contained in the <code class="highlighter-rouge">src/main/resources/META-INF/bin-license-notice</code> directory. Please update the <code class="highlighter-rouge">LICENSE-bin</code> and <code class="highlighter-rouge">NOTICE-bin</code> files as well as the <code class="highlighter-rouge">licenses</code> directory with any licenses and notices corresponding to all new third-party dependencies introduced in your code.</li> |
| <li><a href="http://www.apache.org/dev/release.html#distributing-code-under-several-licenses">LICENSE requirements for distribution artifacts with multiple licenses</a></li> |
| <li><a href="http://www.apache.org/dev/release.html#notice-content">NOTICE file requirements</a></li> |
| <li><a href="http://www.apache.org/legal/resolved.html#category-a">Acceptable</a> and <a href="http://www.apache.org/legal/resolved.html#category-x">Unacceptable</a> Dependency Licenses</li> |
| </ul> |
| </li> |
| <li>Commit the changes to your local repository</li> |
| <li>Push the code back up to your GitHub fork of apache/incubator-pirk</li> |
| <li><a href="#github-pull-requests">Create a Pull Request</a> to the to <a href="https://github.com/apache/incubator-pirk">apache/incubator-pirk</a> repository on GitHub. Please include the corresponding JIRA issue number and description in the title of the pull request: PIRK-XXXX: < JIRA-Issue-Description ></li> |
| <li>Members of the Pirk community can then comment on the pull request; be sure to watch for comments, respond, and make any necessary changes.</li> |
| <li>A Pirk committer will merge the pull request</li> |
| </ol> |
| |
| <h2 id="github-pull-requests">GitHub Pull Requests</h2> |
| |
| <p>All changes to the Apache Pirk codebase should go through a <a href="https://help.github.com/articles/using-pull-requests/">GitHub pull request</a>.</p> |
| |
| <p>(Thanks to <a href="http://mahout.apache.org/">Apache Mahout</a> for sharing <a href="http://mahout.apache.org/developers/github.html">their great pull request overview</a> with us!)</p> |
| |
| <h3 id="git-setup">Git Setup</h3> |
| |
| <p>Fork <a href="https://github.com/apache/incubator-pirk">apache/incubator-pirk</a> to your personal GitHub repository. Clone this fork locally to set up “origin” to point to your remote fork on GitHub as the default remote (for the sake of this explanation); if you perform</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git push origin master |
| </code></pre> |
| </div> |
| |
| <p>it will go to your GitHub fork of apache/incubator-pirk. Please make sure that you follow branch naming conventions that will integrate with Apache Pirk JIRA issue numbers. For the issue number XXXX, please name branch containing the corresponding work PIRK-XXXX (all caps):</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git checkout -b PIRK-XXXX |
| #do some work on the branch |
| git commit -a -m "did some work" |
| git push origin PIRK-XXXX #pushing to your fork of apache/incubator-pirk |
| </code></pre> |
| </div> |
| |
| <p>Clone the Apache Pirk git repo via</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git clone -o apache https://git-wip-us.apache.org/repos/asf/incubator-pirk.git |
| </code></pre> |
| </div> |
| |
| <p>or attach via the following:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git remote add apache https://git-wip-us.apache.org/repos/asf/incubator-pirk.git |
| </code></pre> |
| </div> |
| |
| <p>Once you are ready to commit to the apache remote, you can create a pull request.</p> |
| |
| <h3 id="creating-a-pull-request">Creating a Pull Request</h3> |
| |
| <p>Pull requests are made to the <a href="https://github.com/apache/incubator-pirk">apache/incubator-pirk</a> repository on GitHub; please check out GitHub’s info on <a href="https://help.github.com/articles/creating-a-pull-request/">how to create a pull request</a>.</p> |
| |
| <p>First, push your work from your local PIRK-XXXX branch to the remote PIRK-XXXX branch of your apache/incubator-pirk GitHub fork:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git checkout PIRK-XXXX |
| git push origin PIRK-XXXX |
| </code></pre> |
| </div> |
| |
| <p>Go to your PIRK-XXXX branch on GitHub. Since you forked it from GitHub’s <a href="https://github.com/apache/incubator-pirk">apache/incubator-pirk</a>, it will default any pull request to go to the master branch of apache/incubator-pirk.</p> |
| |
| <p>Click the “Compare, review, and create pull request” button.</p> |
| |
| <p>You can edit the “to” and “from” for the pull request if it isn’t correct. The “base fork” should be apache/incubator-pirk. The “base” will be master unless your are <a href="/website_updates">updating the website</a>. The “head fork” will be your forked repo and the “compare” will be your PIRK-XXXX branch.</p> |
| |
| <p>Click the “Create pull request” button and name the request “PIRK-XXXX”, all caps. This will connect the comments of the pull request to the mailing list and JIRA comments.</p> |
| |
| <p>From now on, the pull request lives in GitHub’s <a href="https://github.com/apache/incubator-pirk">apache/incubator-pirk</a>; use the commenting UI there. The pull request is tied to the corresponding branch in your forked repo, so you can respond to comments, make fixes, and commit them from there; they will appear on the pull request page and be mirrored to JIRA and the mailing list.</p> |
| |
| <p>All pull requests to <a href="https://github.com/apache/incubator-pirk">apache/incubator-pirk</a> are built through <a href="https://travis-ci.org/apache/incubator-pirk">Pirk’s Travis CI integration</a>.</p> |
| |
| <h3 id="merging-a-pull-request">Merging a Pull Request</h3> |
| |
| <p>Check out the GitHub info on <a href="https://help.github.com/articles/merging-a-pull-request/#merging-locally">how to merge a pull request</a>.</p> |
| |
| <p>Pull requests are equivalent to a remote GitHub branch with (potentially) a multitude of commits. Please squash the remote commit history to have one commit per issue, rather than merging in all of the contributor’s commits:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git pull --squash <repo> <branch> |
| </code></pre> |
| </div> |
| |
| <p>Merging pull requests are equivalent to a “pull” of a contributor’s branch; to merge the pull request branch PIRK-XXXX:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git checkout master # switch to local master branch |
| git pull apache master # fast-forward to current remote HEAD |
| git pull --squash <contributor's GitHub repo> PIRK-XXXX # merge to master |
| </code></pre> |
| </div> |
| |
| <p>You now can commit the request:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git commit --author "contributor_name <contributor_email>" -a -m "PIRK-XXXX <description> - closes apache/incubator-pirk#ZZ" |
| </code></pre> |
| </div> |
| |
| <p>PIRK-XXXX is in all caps and ZZ is the pull request number on apache/incubator-pirk. Including “closes apache/incubator-pirk#ZZ” will close the <a href="https://help.github.com/articles/closing-issues-via-commit-messages/">pull request automatically</a>.</p> |
| |
| <p>Next, push to the apache master branch:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git push apache master |
| </code></pre> |
| </div> |
| |
| <p>(this will require Apache handle credentials).</p> |
| |
| <p>The pull request, once pushed, will get mirrored to apache/incubator-pirk on GitHub.</p> |
| |
| <h3 id="closing-a-pull-request-without-committing">Closing a Pull Request Without Committing</h3> |
| |
| <p>To reject pull request ZZ (close without committing), issue an empty commit on master’s HEAD without merging the pull request:</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>git commit --allow-empty -m "closes apache/incubator-pirk#ZZ" |
| git push apache master |
| </code></pre> |
| </div> |
| |
| <h3 id="apache-and-github-integration">Apache and GitHub Integration</h3> |
| |
| <p>Check out Apache INFRA’s blog post on <a href="https://blogs.apache.org/infra/entry/improved_integration_between_apache_and">Apache-GitHub integration</a>.</p> |
| |
| <p>Comments and pull requests with Pirk issue handles of the form</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>PIRK-XXXX |
| </code></pre> |
| </div> |
| |
| <p>should post to the mailing lists and JIRA. Please file a JIRA issue first, and then create a pull request with the description</p> |
| |
| <div class="highlighter-rouge"><pre class="highlight"><code>PIRK-XXXX: <jira-issue-description> |
| </code></pre> |
| </div> |
| |
| <p>so that all subsequent comments will be automatically copied to JIRA.</p> |
| |
| </div> |
| |
| |
| <footer> |
| |
| <p><a href="https://www.apache.org"><img src="/images/feather-small.gif" alt="Apache Software Foundation" id="asf-logo" height="100" /></a></p> |
| |
| <p>Copyright © 2016-2016 The Apache Software Foundation. Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> |
| |
| </footer> |
| |
| |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
