content/contributing.html - apex-site - Git at Google

 <html lang="en"><head>

     <meta charset="utf-8">
     <meta http-equiv="X-UA-Compatible" content="IE=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
     <meta name="description" content="Apex is an enterprise grade native YARN big data-in-motion platform that unifies stream processing as well as batch processing.">
     <meta name="author" content="Apache Software Foundation">
     <link rel="icon" href="favicon.ico">

     <title>Apache Apex</title>

     <!-- Main Stylesheet -->
     <link href="css/main.css" rel="stylesheet">

     <script>
       (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-85540278-1', 'auto');
       ga('send', 'pageview');
     </script>

   </head>

   <body>
     <nav class="navbar navbar-default navbar-static-top" id="main-nav">
       <div class="container">

       <div class="navbar-header">
         <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false">
           <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="images/apex-logo.svg" class="logo" alt="Apache Apex Logo">
           Apache Apex<span class="trademark">&trade;</span>
         </a>
       </div>

       <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
         <ul class="nav navbar-right navbar-nav">
           <li class="nav-item">
             <a class="nav-link " href="/">Home</a>
           </li>
           <li class="nav-item">
             <a class="nav-link " href="/docs.html">Documentation</a>
           </li>
           <li class="nav-item">
             <a class="nav-link " href="/powered-by-apex.html">Powered By Apex</a>
           </li>
           <li class="nav-item">
             <a class="nav-link " href="/roadmap.html">Roadmap</a>
           </li>

             <li class="nav-item nav-mouseover">
               <ul class="dropdown-menu">
                 <li class=""><a href="/community.html#mailing-lists">Mailing Lists</a></li>
                 <li class=""><a href="/community.html#issue-tracking">Issue Tracking</a></li>
                 <li class=""><a href="http://stackoverflow.com/questions/tagged/apache-apex">Stack Overflow</a></li>
                 <li class=""><a href="/community.html#events">Events</a></li>
                 <li class=""><a href="/community.html#contributing">Contributing</a></li>
                 <li class=""><a href="http://www.apache.org/foundation/how-it-works.html">Apache Foundation</a></li>
               </ul>
               <a href="/community.html" class="nav-link">Community</a>
             </li>


             <li class="nav-item nav-mouseover">
               <ul class="dropdown-menu">
                 <li class=""><a href="https://github.com/apache/apex-core">Apex Core</a></li>
                 <li class=""><a href="https://github.com/apache/apex-malhar">Apex Malhar</a></li>
                 <li class=""><a href="https://github.com/apache/apex-site">Apex Site</a></li>
               </ul>
               <a href="https://github.com/apache/apex-core" class="nav-link">Github</a>
             </li>

           <li class="nav-item">
             <a class="nav-link btn btn-success btn-download" href="/downloads.html">Download</a>
           </li>
         </ul>

       </div>
     </nav>

 <div class="container">

   <h1 id="contributing-guidelines">Contributing Guidelines</h1>
 <p>This project welcomes new contributors and invites everyone to participate. Our aim is to build an open community. There are many different ways to get involved:</p>
 <ul>
 <li>Adding new features, enhancements, tests or fixing bugs</li>
 <li>Pull request reviews</li>
 <li>Release management and verification</li>
 <li>Participation on email list</li>
 <li>Web site improvements</li>
 <li>Documentation</li>
 <li>Organize meetups and other events</li>
 <li>Publishing papers and blogs</li>
 <li>Present at conferences or spread the word in other ways</li>
 </ul>
 <p>People that help with the project in any of the above categories or other ways are contributors. See the <a href="http://www.apache.org/foundation/how-it-works.html#roles">roles</a> as defined by the ASF. Community members that make sustained, welcome contributions to the project may be invited to become a <a href="/people.html">committer</a>. </p>
 <h2 id="one-time-setup">One-time Setup</h2>
 <h3 id="jira">JIRA</h3>
 <p>Apache JIRA is used for issue tracking. If you do not already have an Apache JIRA account, sign up <a href="https://issues.apache.org/jira/">here</a>. Note that the user name should have no white spaces or other special characters that complicate auto-completion within JIRA comments etc. </p>
 <p>Please use a single JIRA account only (don&#39;t create multiple with different email addresses) to retain the issue history. Please use a permanent email address, for an existing account it can be changed in the profile. If you absolutely have to change your user name, contact INFRA.</p>
 <p>Apex has 2 JIRA projects:</p>
 <ol>
 <li><a href="https://issues.apache.org/jira/browse/APEXCORE/">APEXCORE</a> for <a href="https://github.com/apache/apex-core">apex-core</a> and <a href="https://github.com/apache/apex-site">apex-site</a></li>
 <li><a href="https://issues.apache.org/jira/browse/APEXMALHAR/">APEXMALHAR</a> for <a href="https://github.com/apache/apex-malhar">apex-malhar</a></li>
 </ol>
 <p>Before working on changes for any of the repositories, please locate an existing JIRA ticket or submit a new one.
 Before a ticket can be assigned, you need to be listed as contributor in the JIRA project. PMC members have access to add new contributors, please request to be added through a comment on your candidate ticket or send us an email on the dev@ mailing list.</p>
 <h3 id="github-and-git">Github and git</h3>
 <p>We use GitHub’s pull request functionality to review proposed code changes. If you do not already have a personal GitHub account, sign up <a href="https://github.com/join">here</a>. We recommend that you use the same email address and first/lastname for emails, git and JIRA so that contributions can be better tracked and notifications correlated. It is also recommended that you use an email address that is valid permanently (for example your @gmail.com or @apache.org address). Please also see:</p>
 <ul>
 <li><a href="https://help.github.com/articles/setting-your-email-in-git/">https://help.github.com/articles/setting-your-email-in-git/</a></li>
 <li><a href="https://help.github.com/articles/adding-an-email-address-to-your-github-account/">https://help.github.com/articles/adding-an-email-address-to-your-github-account/</a></li>
 <li><a href="https://help.github.com/articles/keeping-your-email-address-private/">https://help.github.com/articles/keeping-your-email-address-private/</a></li>
 </ul>
 <p>If you are new to git, this <a href="https://try.github.io/">tutorial</a> may be helpful.</p>
 <ol>
 <li>Fork the ASF repository: <a href="https://github.com/apache/apex-core">Apex Core</a> or <a href="https://github.com/apache/apex-malhar">Apex Malhar</a> or <a href="https://github.com/apache/apex-site">Apex Site</a> into your github account. </li>
 <li>Clone the <strong>fork</strong> on your local workspace:<br/>
 <code>git clone https://github.com/{github_username}/apex-core.git</code></li>
 </ol>
 <h3 id="java-development-environment">Java Development Environment</h3>
 <p>For prerequisites and setup instructions see: <a href="http://apex.apache.org/docs/apex/apex_development_setup/">http://apex.apache.org/docs/apex/apex_development_setup/</a></p>
 <p>Apache Apex follows coding style that is closest to K &amp; R style and uses <a href="http://checkstyle.sourceforge.net/">Checkstyle</a> tool to enforce these standards. Apex checkstyle enforces no trailing whitespace. Travis CI will fail for any pull request that introduces any style violations. The checkstyle configuration is <a href="https://github.com/apache/apex-core/blob/master/codestyle-config/src/main/resources/apex_checks.xml">here</a>.</p>
 <p>To make it easier for the users to set up their development environment, settings for the following common IDEs are provided in the Apache Apex Core repository with instructions.</p>
 <ul>
 <li><a href="https://github.com/apache/apex-core/tree/master/misc/ide-templates/intellij">IntelliJ</a></li>
 <li><a href="https://github.com/apache/apex-core/tree/master/misc/ide-templates/eclipse">Eclipse</a></li>
 <li><a href="https://github.com/apache/apex-core/tree/master/misc/ide-templates/netbeans">NetBeans</a></li>
 </ul>
 <h2 id="before-coding">Before Coding</h2>
 <p>Before starting work, have a JIRA assigned to yourself. If you want to work on a ticket that is assigned to someone else,
 send a courtesy e-mail to the assignee to check if you can take it over.
 Confirm type, priority and other JIRA fields (often default values are not the best fit).</p>
 <p>Before implementing non-trivial changes that result in potentially large code modifications:</p>
 <ul>
 <li>Engage on the mailing list to ensure your time will be well spent, the proposal is welcome by the community
 and does not overlap or conflict with other initiatives.</li>
 <li>Discuss the design aspects, the larger picture. This may involve discussion, questions,
 suggestions, consensus building towards agreed approach. Or possibly some prototyping. </li>
 <li>Capture the outcome or final approach on your JIRA ticket, this will help others to see important
 information without getting into details (including users that may lookup a JIRA from release notes).</li>
 <li>Certain licenses cannot be used in ASF projects. Ensure contributions don&#39;t introduce such dependencies. See</li>
 <li><a href="https://www.apache.org/legal/resolved.html#category-x">https://www.apache.org/legal/resolved.html#category-x</a></li>
 <li><a href="https://www.apache.org/legal/">https://www.apache.org/legal/</a></li>
 <li><a href="https://www.apache.org/legal/resolved.html">https://www.apache.org/legal/resolved.html</a></li>
 <li><a href="https://issues.apache.org/jira/browse/LEGAL">https://issues.apache.org/jira/browse/LEGAL</a></li>
 </ul>
 <h2 id="opening-pull-requests">Opening Pull Requests</h2>
 <ol>
 <li>Create a new branch from the <code>master</code> branch, <strong>name it with the JIRA number, e.g. <code>APEXCORE-123.my-feature</code></strong>:<br/>
 <code>git checkout -b APEXCORE-123.my-feature -t upstream/master</code><br/>
 Creating a local branch that tracks a remote makes pull easier (no need to specify the remote branch while pulling). A branch can be made to track a remote branch anytime, not necessarily at its creation by:<br/>
 <code>git branch -u upstream/master</code></li>
 <li>When adding new files, please include the Apache v2.0 license header.<ul>
 <li>From the top level directory, run <code>mvn license:check -Dlicense.skip=false</code> to check correct header formatting.</li>
 <li>Run <code>mvn license:format -Dlicense.skip=false</code> to automatically add the header when missing.</li>
 </ul>
 </li>
 <li>Once your feature is complete, submit the pull request on github against <code>master</code>. <strong>Use the JIRA number (e.g. APEXCORE-123) as prefix in the pull request title</strong>. This will ensure the information is attached to the JIRA ticket automatically. If commits result from running scripts, file formatting or similar, use following attribution:<br/>
 <code>git commit --amend --author &quot;Apex Dev &lt;dev@apex.apache.org&gt;&quot;</code></li>
 <li>If you want specific people to review the work, request reviewers or assignees on the pull request (Github will make suggestions). You can also use the <code>@</code> notation in Github comments to mention that user, and request that he/she reviews your changes.</li>
 <li>Check the status of the pull request and ensure the Travis CI and Jenkins builds are successful. If not, inspect the linked build log for details.<ul>
 <li>If build fails due to license headers, follow instructions above.</li>
 <li>If build fails due to code style violations, run <code>mvn checkstyle:check -Dcheckstyle.console=true</code> and correct those issues that were introduced with your changes. </li>
 </ul>
 </li>
 <li>Add changes after the PR was opened to the same branch, Travis CI will detect changes and build automatically. To force the CI run, close and re-open the PR.</li>
 <li><p>After all review is complete, combine all new commits into one squashed commit except when there are multiple contributors, and include the Jira number in the commit message. There are several ways to squash commits, but <a href="https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits">here is one explanation from git-scm.com</a> and a simple example is illustrated below:</p>
 <p>If tracking upstream/master then run <code>git rebase -i</code>. Else run <code>git rebase -i upstream/master</code>.
 This command opens the text editor which lists the multiple commits:</p>
 <pre><code>pick 67cd79b change1
 pick 6f98905 change2

 # Rebase e13748b..3463fbf onto e13748b (2 command(s))
 #
 # Commands:
 # p, pick = use commit
 # r, reword = use commit, but edit the commit message
 # e, edit = use commit, but stop for amending
 # s, squash = use commit, but meld into previous commit
 # f, fixup = like &quot;squash&quot;, but discard this commit&#39;s log message
 # x, exec = run command (the rest of the line) using shell
 #
 # These lines can be re-ordered; they are executed from top to bottom.
 </code></pre><p>Squash &#39;change2&#39; to &#39;change1&#39; and save.</p>
 <pre><code>pick 67cd79b change1
 squash 6f98905 change2
 </code></pre></li>
 <li>If there are multiple contributors in a pull request preserve individual attributions. Try to squash the commits to the minimum number of commits required to preserve attribution and the contribution to still be functionally correct.</li>
 <li>Till the review is complete it may happen that working feature branch may diverge from <code>master</code> substantially. Therefore, it is recommended to frequently merge <code>master</code> to the branch being worked on by:<ul>
 <li>when the branch tracks upstream/master<br><code>git pull</code></li>
 <li>when the branch doesn&#39;t track upstream<br><code>git pull upstream master</code></li>
 </ul>
 </li>
 <li>If a pull from <code>master</code> results in a conflict then resolve it and commit the merge. This results in additional merge commits in the pull request. Following steps help to ensure that the final pull request contains just one commit:<ul>
 <li>Rename the original branch:<br><code>git branch -m APEXCORE-123.my-feature.squash</code></li>
 <li>Create a new branch (with the original name) from upstream/master that has latest changes:<br><code>git checkout -b APEXCORE-123.my-feature -t upstream/master</code></li>
 <li>Squash merge the old branch which was renamed. When the new branch has the latest changes then this squash will result only in the changes that were made for the feature:<br><code>git merge --squash APEXCORE-123.my-feature.squash</code></li>
 <li>Commit the squash and force push it to the old feature remote branch so that the pull request is automatically updated:<br><code>git commit -m &quot;APEXCORE-123 #comment added my-feature&quot;</code><br><code>git push origin +APEXCORE-123.my-feature</code></li>
 <li>Delete the extra squash branch:<br><code>git branch -D APEXCORE-123.my-feature.squash</code></li>
 </ul>
 </li>
 <li>In case you need more time to work on the PR after receiving review feedback and anticipate some period of inactivity, please close the PR and let the reviewers know if you plan to work on the PR later. Once you have time to resume
 work on the issue, please re-open existing PR prior to updating your remote branch. When a PR is inactive longer than 2 months, it may be closed by a committer.  </li>
 </ol>
 <p>Thanks for contributing!</p>
 <h2 id="merging-a-pull-request-committers-">Merging a Pull Request (committers)</h2>
 <ol>
 <li>Ensure that basic requirements for a pull request are met. This includes:<ul>
 <li>Sufficient time has passed for others to review </li>
 <li>PR was suffiently reviewed and comments were addressed. See <a href="https://www.apache.org/foundation/voting.html">voting policy</a>. </li>
 <li>When there are multiple reviewers, wait till other reviewers approve, with timeout of 48 hours before merging</li>
 <li>If the PR was open for a long time, email dev@ declaring intent to merge</li>
 <li>Commit messages and PR title need to reference JIRA (pull requests will be linked to ticket)</li>
 <li>Travis CI and Jenkins pull request build needs to pass</li>
 <li>Ensure tests are added/modified for new features or fixes</li>
 <li>Ensure appropriate JavaDoc comments have been added</li>
 <li>Verify contributions don&#39;t depend on incompatible licences (see <a href="https://www.apache.org/legal/resolved.html#category-x">https://www.apache.org/legal/resolved.html#category-x</a>)</li>
 </ul>
 </li>
 <li>If the CI build fails because of the presence of a CVE vulnerability, further analysis needs to be performed<ul>
 <li>If the CVE is unrelated to the changes in the PR i.e., the changes in the PR are not the cause then it can be merged</li>
 <li>If the vulnerability is in a dependency added by the PR then the committer should ask the contributor to address it. If there are no good alternatives, then a discussion should happen in the security list whether to allow the PR, before it can be merged</li>
 <li>If it is determined that a vulnerability is not applicable to the project for a reason such as the code paths corresponding to it are not exercised by the software or for any other reason, the vulnerability can be added to the whitelist file <code>dependency-check-whitelist.xml</code> to ignore it for future builds </li>
 <li>In any case, if the vulnerability affects the software, a JIRA should to be created to address the vulnerability in an appropriate way</li>
 </ul>
 </li>
 <li>Use the github <em>rebase and merge</em> option or the git command line to merge the pull request (see link <code>view command line options</code> on the PR).</li>
 <li>Update JIRA after pushing the changes. Set the <code>Fix version</code> field and resolve the JIRA with proper resolution. Also verify that other fields (type, priority, assignee) are correct.</li>
 </ol>

 </div>

   <hr>
   <div class="container">
     <footer id="main-footer">
       <p>
         Copyright &copy; <span id="copyright-year">2015</span> <a href="http://apache.org">The Apache Software Foundation</a>,
         Licensed under the Apache License, Version 2.0<br>
         Apache and the Apache feather logo are trademarks of The Apache Software Foundation. | <a href="/privacy.html">Privacy Policy</a><br>
         <a class="footer-link-img" href="http://apache.org"><img src="/images/asf_logo.svg" alt="The Apache Software Foundation"></a>
       </p>
     </footer>
   </div> <!-- /container -->

   <!-- Placed at the end of the document so the pages load faster -->
   <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
   <script src="/js/bootstrap.min.js"></script>
   <script src="js/docs.js"></script>

   <script>
     $('#copyright-year').text((new Date()).getFullYear());

     $('.btn-download').click(function(e){
       ga('send', {
         hitType: 'event',
         eventCategory: 'Download Button',
         eventAction: 'Button Click',
         eventLabel: 'Page Header'
       });
     });

   </script>

 </body>
 </html>
	<html lang="en"><head>

	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<!-- The above 3 meta tags must come first in the head; any other head content must come after these tags -->
	<meta name="description" content="Apex is an enterprise grade native YARN big data-in-motion platform that unifies stream processing as well as batch processing.">
	<meta name="author" content="Apache Software Foundation">
	<link rel="icon" href="favicon.ico">

	<title>Apache Apex</title>

	<!-- Main Stylesheet -->
	<link href="css/main.css" rel="stylesheet">

	<script>
	(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-85540278-1', 'auto');
	ga('send', 'pageview');
	</script>

	</head>

	<body>
	<nav class="navbar navbar-default navbar-static-top" id="main-nav">
	<div class="container">

	<div class="navbar-header">
	<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false">
	<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="images/apex-logo.svg" class="logo" alt="Apache Apex Logo">
	Apache Apex<span class="trademark">™</span>
	</a>
	</div>

	<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
	<ul class="nav navbar-right navbar-nav">
	<li class="nav-item">
	<a class="nav-link " href="/">Home</a>
	</li>
	<li class="nav-item">
	<a class="nav-link " href="/docs.html">Documentation</a>
	</li>
	<li class="nav-item">
	<a class="nav-link " href="/powered-by-apex.html">Powered By Apex</a>
	</li>
	<li class="nav-item">
	<a class="nav-link " href="/roadmap.html">Roadmap</a>
	</li>

	<li class="nav-item nav-mouseover">
	<ul class="dropdown-menu">
	<li class=""><a href="/community.html#mailing-lists">Mailing Lists</a></li>
	<li class=""><a href="/community.html#issue-tracking">Issue Tracking</a></li>
	<li class=""><a href="http://stackoverflow.com/questions/tagged/apache-apex">Stack Overflow</a></li>
	<li class=""><a href="/community.html#events">Events</a></li>
	<li class=""><a href="/community.html#contributing">Contributing</a></li>
	<li class=""><a href="http://www.apache.org/foundation/how-it-works.html">Apache Foundation</a></li>
	</ul>
	<a href="/community.html" class="nav-link">Community</a>
	</li>


	<li class="nav-item nav-mouseover">
	<ul class="dropdown-menu">
	<li class=""><a href="https://github.com/apache/apex-core">Apex Core</a></li>
	<li class=""><a href="https://github.com/apache/apex-malhar">Apex Malhar</a></li>
	<li class=""><a href="https://github.com/apache/apex-site">Apex Site</a></li>
	</ul>
	<a href="https://github.com/apache/apex-core" class="nav-link">Github</a>
	</li>

	<li class="nav-item">
	<a class="nav-link btn btn-success btn-download" href="/downloads.html">Download</a>
	</li>
	</ul>

	</div>
	</nav>

	<div class="container">

	<h1 id="contributing-guidelines">Contributing Guidelines</h1>
	<p>This project welcomes new contributors and invites everyone to participate. Our aim is to build an open community. There are many different ways to get involved:</p>
	<ul>
	<li>Adding new features, enhancements, tests or fixing bugs</li>
	<li>Pull request reviews</li>
	<li>Release management and verification</li>
	<li>Participation on email list</li>
	<li>Web site improvements</li>
	<li>Documentation</li>
	<li>Organize meetups and other events</li>
	<li>Publishing papers and blogs</li>
	<li>Present at conferences or spread the word in other ways</li>
	</ul>
	<p>People that help with the project in any of the above categories or other ways are contributors. See the <a href="http://www.apache.org/foundation/how-it-works.html#roles">roles</a> as defined by the ASF. Community members that make sustained, welcome contributions to the project may be invited to become a <a href="/people.html">committer</a>. </p>
	<h2 id="one-time-setup">One-time Setup</h2>
	<h3 id="jira">JIRA</h3>
	<p>Apache JIRA is used for issue tracking. If you do not already have an Apache JIRA account, sign up <a href="https://issues.apache.org/jira/">here</a>. Note that the user name should have no white spaces or other special characters that complicate auto-completion within JIRA comments etc. </p>
	<p>Please use a single JIRA account only (don't create multiple with different email addresses) to retain the issue history. Please use a permanent email address, for an existing account it can be changed in the profile. If you absolutely have to change your user name, contact INFRA.</p>
	<p>Apex has 2 JIRA projects:</p>
	<ol>
	<li><a href="https://issues.apache.org/jira/browse/APEXCORE/">APEXCORE</a> for <a href="https://github.com/apache/apex-core">apex-core</a> and <a href="https://github.com/apache/apex-site">apex-site</a></li>
	<li><a href="https://issues.apache.org/jira/browse/APEXMALHAR/">APEXMALHAR</a> for <a href="https://github.com/apache/apex-malhar">apex-malhar</a></li>
	</ol>
	<p>Before working on changes for any of the repositories, please locate an existing JIRA ticket or submit a new one.
	Before a ticket can be assigned, you need to be listed as contributor in the JIRA project. PMC members have access to add new contributors, please request to be added through a comment on your candidate ticket or send us an email on the dev@ mailing list.</p>
	<h3 id="github-and-git">Github and git</h3>
	<p>We use GitHub’s pull request functionality to review proposed code changes. If you do not already have a personal GitHub account, sign up <a href="https://github.com/join">here</a>. We recommend that you use the same email address and first/lastname for emails, git and JIRA so that contributions can be better tracked and notifications correlated. It is also recommended that you use an email address that is valid permanently (for example your @gmail.com or @apache.org address). Please also see:</p>
	<ul>
	<li><a href="https://help.github.com/articles/setting-your-email-in-git/">https://help.github.com/articles/setting-your-email-in-git/</a></li>
	<li><a href="https://help.github.com/articles/adding-an-email-address-to-your-github-account/">https://help.github.com/articles/adding-an-email-address-to-your-github-account/</a></li>
	<li><a href="https://help.github.com/articles/keeping-your-email-address-private/">https://help.github.com/articles/keeping-your-email-address-private/</a></li>
	</ul>
	<p>If you are new to git, this <a href="https://try.github.io/">tutorial</a> may be helpful.</p>
	<ol>
	<li>Fork the ASF repository: <a href="https://github.com/apache/apex-core">Apex Core</a> or <a href="https://github.com/apache/apex-malhar">Apex Malhar</a> or <a href="https://github.com/apache/apex-site">Apex Site</a> into your github account. </li>
	<li>Clone the <strong>fork</strong> on your local workspace:<br/>
	<code>git clone https://github.com/{github_username}/apex-core.git</code></li>
	</ol>
	<h3 id="java-development-environment">Java Development Environment</h3>
	<p>For prerequisites and setup instructions see: <a href="http://apex.apache.org/docs/apex/apex_development_setup/">http://apex.apache.org/docs/apex/apex_development_setup/</a></p>
	<p>Apache Apex follows coding style that is closest to K & R style and uses <a href="http://checkstyle.sourceforge.net/">Checkstyle</a> tool to enforce these standards. Apex checkstyle enforces no trailing whitespace. Travis CI will fail for any pull request that introduces any style violations. The checkstyle configuration is <a href="https://github.com/apache/apex-core/blob/master/codestyle-config/src/main/resources/apex_checks.xml">here</a>.</p>
	<p>To make it easier for the users to set up their development environment, settings for the following common IDEs are provided in the Apache Apex Core repository with instructions.</p>
	<ul>
	<li><a href="https://github.com/apache/apex-core/tree/master/misc/ide-templates/intellij">IntelliJ</a></li>
	<li><a href="https://github.com/apache/apex-core/tree/master/misc/ide-templates/eclipse">Eclipse</a></li>
	<li><a href="https://github.com/apache/apex-core/tree/master/misc/ide-templates/netbeans">NetBeans</a></li>
	</ul>
	<h2 id="before-coding">Before Coding</h2>
	<p>Before starting work, have a JIRA assigned to yourself. If you want to work on a ticket that is assigned to someone else,
	send a courtesy e-mail to the assignee to check if you can take it over.
	Confirm type, priority and other JIRA fields (often default values are not the best fit).</p>
	<p>Before implementing non-trivial changes that result in potentially large code modifications:</p>
	<ul>
	<li>Engage on the mailing list to ensure your time will be well spent, the proposal is welcome by the community
	and does not overlap or conflict with other initiatives.</li>
	<li>Discuss the design aspects, the larger picture. This may involve discussion, questions,
	suggestions, consensus building towards agreed approach. Or possibly some prototyping. </li>
	<li>Capture the outcome or final approach on your JIRA ticket, this will help others to see important
	information without getting into details (including users that may lookup a JIRA from release notes).</li>
	<li>Certain licenses cannot be used in ASF projects. Ensure contributions don't introduce such dependencies. See</li>
	<li><a href="https://www.apache.org/legal/resolved.html#category-x">https://www.apache.org/legal/resolved.html#category-x</a></li>
	<li><a href="https://www.apache.org/legal/">https://www.apache.org/legal/</a></li>
	<li><a href="https://www.apache.org/legal/resolved.html">https://www.apache.org/legal/resolved.html</a></li>
	<li><a href="https://issues.apache.org/jira/browse/LEGAL">https://issues.apache.org/jira/browse/LEGAL</a></li>
	</ul>
	<h2 id="opening-pull-requests">Opening Pull Requests</h2>
	<ol>
	<li>Create a new branch from the <code>master</code> branch, <strong>name it with the JIRA number, e.g. <code>APEXCORE-123.my-feature</code></strong>:<br/>
	<code>git checkout -b APEXCORE-123.my-feature -t upstream/master</code><br/>
	Creating a local branch that tracks a remote makes pull easier (no need to specify the remote branch while pulling). A branch can be made to track a remote branch anytime, not necessarily at its creation by:<br/>
	<code>git branch -u upstream/master</code></li>
	<li>When adding new files, please include the Apache v2.0 license header.<ul>
	<li>From the top level directory, run <code>mvn license:check -Dlicense.skip=false</code> to check correct header formatting.</li>
	<li>Run <code>mvn license:format -Dlicense.skip=false</code> to automatically add the header when missing.</li>
	</ul>
	</li>
	<li>Once your feature is complete, submit the pull request on github against <code>master</code>. <strong>Use the JIRA number (e.g. APEXCORE-123) as prefix in the pull request title</strong>. This will ensure the information is attached to the JIRA ticket automatically. If commits result from running scripts, file formatting or similar, use following attribution:<br/>
	<code>git commit --amend --author "Apex Dev <dev@apex.apache.org>"</code></li>
	<li>If you want specific people to review the work, request reviewers or assignees on the pull request (Github will make suggestions). You can also use the <code>@</code> notation in Github comments to mention that user, and request that he/she reviews your changes.</li>
	<li>Check the status of the pull request and ensure the Travis CI and Jenkins builds are successful. If not, inspect the linked build log for details.<ul>
	<li>If build fails due to license headers, follow instructions above.</li>
	<li>If build fails due to code style violations, run <code>mvn checkstyle:check -Dcheckstyle.console=true</code> and correct those issues that were introduced with your changes. </li>
	</ul>
	</li>
	<li>Add changes after the PR was opened to the same branch, Travis CI will detect changes and build automatically. To force the CI run, close and re-open the PR.</li>
	<li><p>After all review is complete, combine all new commits into one squashed commit except when there are multiple contributors, and include the Jira number in the commit message. There are several ways to squash commits, but <a href="https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits">here is one explanation from git-scm.com</a> and a simple example is illustrated below:</p>
	<p>If tracking upstream/master then run <code>git rebase -i</code>. Else run <code>git rebase -i upstream/master</code>.
	This command opens the text editor which lists the multiple commits:</p>
	<pre><code>pick 67cd79b change1
	pick 6f98905 change2

	# Rebase e13748b..3463fbf onto e13748b (2 command(s))
	#
	# Commands:
	# p, pick = use commit
	# r, reword = use commit, but edit the commit message
	# e, edit = use commit, but stop for amending
	# s, squash = use commit, but meld into previous commit
	# f, fixup = like "squash", but discard this commit's log message
	# x, exec = run command (the rest of the line) using shell
	#
	# These lines can be re-ordered; they are executed from top to bottom.
	</code></pre><p>Squash 'change2' to 'change1' and save.</p>
	<pre><code>pick 67cd79b change1
	squash 6f98905 change2
	</code></pre></li>
	<li>If there are multiple contributors in a pull request preserve individual attributions. Try to squash the commits to the minimum number of commits required to preserve attribution and the contribution to still be functionally correct.</li>
	<li>Till the review is complete it may happen that working feature branch may diverge from <code>master</code> substantially. Therefore, it is recommended to frequently merge <code>master</code> to the branch being worked on by:<ul>
	<li>when the branch tracks upstream/master<br><code>git pull</code></li>
	<li>when the branch doesn't track upstream<br><code>git pull upstream master</code></li>
	</ul>
	</li>
	<li>If a pull from <code>master</code> results in a conflict then resolve it and commit the merge. This results in additional merge commits in the pull request. Following steps help to ensure that the final pull request contains just one commit:<ul>
	<li>Rename the original branch:<br><code>git branch -m APEXCORE-123.my-feature.squash</code></li>
	<li>Create a new branch (with the original name) from upstream/master that has latest changes:<br><code>git checkout -b APEXCORE-123.my-feature -t upstream/master</code></li>
	<li>Squash merge the old branch which was renamed. When the new branch has the latest changes then this squash will result only in the changes that were made for the feature:<br><code>git merge --squash APEXCORE-123.my-feature.squash</code></li>
	<li>Commit the squash and force push it to the old feature remote branch so that the pull request is automatically updated:<br><code>git commit -m "APEXCORE-123 #comment added my-feature"</code><br><code>git push origin +APEXCORE-123.my-feature</code></li>
	<li>Delete the extra squash branch:<br><code>git branch -D APEXCORE-123.my-feature.squash</code></li>
	</ul>
	</li>
	<li>In case you need more time to work on the PR after receiving review feedback and anticipate some period of inactivity, please close the PR and let the reviewers know if you plan to work on the PR later. Once you have time to resume
	work on the issue, please re-open existing PR prior to updating your remote branch. When a PR is inactive longer than 2 months, it may be closed by a committer. </li>
	</ol>
	<p>Thanks for contributing!</p>
	<h2 id="merging-a-pull-request-committers-">Merging a Pull Request (committers)</h2>
	<ol>
	<li>Ensure that basic requirements for a pull request are met. This includes:<ul>
	<li>Sufficient time has passed for others to review </li>
	<li>PR was suffiently reviewed and comments were addressed. See <a href="https://www.apache.org/foundation/voting.html">voting policy</a>. </li>
	<li>When there are multiple reviewers, wait till other reviewers approve, with timeout of 48 hours before merging</li>
	<li>If the PR was open for a long time, email dev@ declaring intent to merge</li>
	<li>Commit messages and PR title need to reference JIRA (pull requests will be linked to ticket)</li>
	<li>Travis CI and Jenkins pull request build needs to pass</li>
	<li>Ensure tests are added/modified for new features or fixes</li>
	<li>Ensure appropriate JavaDoc comments have been added</li>
	<li>Verify contributions don't depend on incompatible licences (see <a href="https://www.apache.org/legal/resolved.html#category-x">https://www.apache.org/legal/resolved.html#category-x</a>)</li>
	</ul>
	</li>
	<li>If the CI build fails because of the presence of a CVE vulnerability, further analysis needs to be performed<ul>
	<li>If the CVE is unrelated to the changes in the PR i.e., the changes in the PR are not the cause then it can be merged</li>
	<li>If the vulnerability is in a dependency added by the PR then the committer should ask the contributor to address it. If there are no good alternatives, then a discussion should happen in the security list whether to allow the PR, before it can be merged</li>
	<li>If it is determined that a vulnerability is not applicable to the project for a reason such as the code paths corresponding to it are not exercised by the software or for any other reason, the vulnerability can be added to the whitelist file <code>dependency-check-whitelist.xml</code> to ignore it for future builds </li>
	<li>In any case, if the vulnerability affects the software, a JIRA should to be created to address the vulnerability in an appropriate way</li>
	</ul>
	</li>
	<li>Use the github <em>rebase and merge</em> option or the git command line to merge the pull request (see link <code>view command line options</code> on the PR).</li>
	<li>Update JIRA after pushing the changes. Set the <code>Fix version</code> field and resolve the JIRA with proper resolution. Also verify that other fields (type, priority, assignee) are correct.</li>
	</ol>

	</div>

	<hr>
	<div class="container">
	<footer id="main-footer">
	<p>
	Copyright © <span id="copyright-year">2015</span> <a href="http://apache.org">The Apache Software Foundation</a>,
	Licensed under the Apache License, Version 2.0<br>
	Apache and the Apache feather logo are trademarks of The Apache Software Foundation. \| <a href="/privacy.html">Privacy Policy</a><br>
	<a class="footer-link-img" href="http://apache.org"><img src="/images/asf_logo.svg" alt="The Apache Software Foundation"></a>
	</p>
	</footer>
	</div> <!-- /container -->

	<!-- Placed at the end of the document so the pages load faster -->
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
	<script src="/js/bootstrap.min.js"></script>
	<script src="js/docs.js"></script>

	<script>
	$('#copyright-year').text((new Date()).getFullYear());

	$('.btn-download').click(function(e){
	ga('send', {
	hitType: 'event',
	eventCategory: 'Download Button',
	eventAction: 'Button Click',
	eventLabel: 'Page Header'
	});
	});

	</script>

	</body>
	</html>