| <!DOCTYPE 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 --> |
| <title>Apache Flink: Contributing Code</title> |
| <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"> |
| <link rel="icon" href="/favicon.ico" type="image/x-icon"> |
| |
| <!-- Bootstrap --> |
| <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css"> |
| <link rel="stylesheet" href="/css/flink.css"> |
| <link rel="stylesheet" href="/css/syntax.css"> |
| |
| <!-- Blog RSS feed --> |
| <link href="/blog/feed.xml" rel="alternate" type="application/rss+xml" title="Apache Flink Blog: RSS feed" /> |
| |
| <!-- jQuery (necessary for Bootstrap's JavaScript plugins) --> |
| <!-- We need to load Jquery in the header for custom google analytics event tracking--> |
| <script src="/js/jquery.min.js"></script> |
| |
| <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> |
| <!-- WARNING: Respond.js doesn't work if you view the page via file:// --> |
| <!--[if lt IE 9]> |
| <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> |
| <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> |
| <![endif]--> |
| </head> |
| <body> |
| |
| |
| <!-- Main content. --> |
| <div class="container"> |
| <div class="row"> |
| |
| |
| <div id="sidebar" class="col-sm-3"> |
| |
| |
| <!-- Top navbar. --> |
| <nav class="navbar navbar-default"> |
| <!-- The logo. --> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <div class="navbar-logo"> |
| <a href="/"> |
| <img alt="Apache Flink" src="/img/flink-header-logo.svg" width="147px" height="73px"> |
| </a> |
| </div> |
| </div><!-- /.navbar-header --> |
| |
| <!-- The navigation links. --> |
| <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> |
| <ul class="nav navbar-nav navbar-main"> |
| |
| <!-- First menu section explains visitors what Flink is --> |
| |
| <!-- What is Stream Processing? --> |
| <!-- |
| <li><a href="/streamprocessing1.html">What is Stream Processing?</a></li> |
| --> |
| |
| <!-- What is Flink? --> |
| <li><a href="/flink-architecture.html">What is Apache Flink?</a></li> |
| |
| |
| |
| <!-- What is Stateful Functions? --> |
| |
| <li><a href="/stateful-functions.html">What is Stateful Functions?</a></li> |
| |
| <!-- Use cases --> |
| <li><a href="/usecases.html">Use Cases</a></li> |
| |
| <!-- Powered by --> |
| <li><a href="/poweredby.html">Powered By</a></li> |
| |
| |
| |
| <!-- Second menu section aims to support Flink users --> |
| |
| <!-- Downloads --> |
| <li><a href="/downloads.html">Downloads</a></li> |
| |
| <!-- Getting Started --> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Getting Started<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://ci.apache.org/projects/flink/flink-docs-release-1.11/getting-started/index.html" target="_blank">With Flink <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-release-2.1/getting-started/project-setup.html" target="_blank">With Flink Stateful Functions <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="/training.html">Training Course</a></li> |
| </ul> |
| </li> |
| |
| <!-- Documentation --> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://ci.apache.org/projects/flink/flink-docs-release-1.11" target="_blank">Flink 1.11 (Latest stable release) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-docs-master" target="_blank">Flink Master (Latest Snapshot) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-release-2.1" target="_blank">Flink Stateful Functions 2.1 (Latest stable release) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-master" target="_blank">Flink Stateful Functions Master (Latest Snapshot) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| </ul> |
| </li> |
| |
| <!-- getting help --> |
| <li><a href="/gettinghelp.html">Getting Help</a></li> |
| |
| <!-- Blog --> |
| <li><a href="/blog/"><b>Flink Blog</b></a></li> |
| |
| |
| <!-- Flink-packages --> |
| <li> |
| <a href="https://flink-packages.org" target="_blank">flink-packages.org <small><span class="glyphicon glyphicon-new-window"></span></small></a> |
| </li> |
| |
| |
| <!-- Third menu section aim to support community and contributors --> |
| |
| <!-- Community --> |
| <li><a href="/community.html">Community & Project Info</a></li> |
| |
| <!-- Roadmap --> |
| <li><a href="/roadmap.html">Roadmap</a></li> |
| |
| <!-- Contribute --> |
| <li><a href="/contributing/how-to-contribute.html">How to Contribute</a></li> |
| |
| <ul class="nav navbar-nav navbar-subnav"> |
| <li class="active"> |
| <a href="/contributing/contribute-code.html">Contribute Code</a> |
| </li> |
| <li > |
| <a href="/contributing/reviewing-prs.html">Review Pull Requests</a> |
| </li> |
| <li > |
| <a href="/contributing/code-style-and-quality-preamble.html">Code Style and Quality Guide</a> |
| </li> |
| <li > |
| <a href="/contributing/contribute-documentation.html">Contribute Documentation</a> |
| </li> |
| <li > |
| <a href="/contributing/docs-style.html">Documentation Style Guide</a> |
| </li> |
| <li > |
| <a href="/contributing/improve-website.html">Contribute to the Website</a> |
| </li> |
| </ul> |
| |
| |
| <!-- GitHub --> |
| <li> |
| <a href="https://github.com/apache/flink" target="_blank">Flink on GitHub <small><span class="glyphicon glyphicon-new-window"></span></small></a> |
| </li> |
| |
| |
| |
| <!-- Language Switcher --> |
| <li> |
| |
| |
| <a href="/zh/contributing/contribute-code.html">中文版</a> |
| |
| |
| </li> |
| |
| </ul> |
| |
| <ul class="nav navbar-nav navbar-bottom"> |
| <hr /> |
| |
| <!-- Twitter --> |
| <li><a href="https://twitter.com/apacheflink" target="_blank">@ApacheFlink <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| |
| <!-- Visualizer --> |
| <li class=" hidden-md hidden-sm"><a href="/visualizer/" target="_blank">Plan Visualizer <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| |
| <hr /> |
| |
| <li><a href="https://apache.org" target="_blank">Apache Software Foundation <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| |
| <li> |
| <style> |
| .smalllinks:link { |
| display: inline-block !important; background: none; padding-top: 0px; padding-bottom: 0px; padding-right: 0px; min-width: 75px; |
| } |
| </style> |
| |
| <a class="smalllinks" href="https://www.apache.org/licenses/" target="_blank">License</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| |
| <a class="smalllinks" href="https://www.apache.org/security/" target="_blank">Security</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| |
| <a class="smalllinks" href="https://www.apache.org/foundation/sponsorship.html" target="_blank">Donate</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| |
| <a class="smalllinks" href="https://www.apache.org/foundation/thanks.html" target="_blank">Thanks</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| </li> |
| |
| </ul> |
| </div><!-- /.navbar-collapse --> |
| </nav> |
| |
| </div> |
| <div class="col-sm-9"> |
| <div class="row-fluid"> |
| <div class="col-sm-12"> |
| <h1>Contributing Code</h1> |
| |
| <p>Apache Flink is maintained, improved, and extended by code contributions of volunteers. We welcome contributions to Flink, but due to the size of the project and to preserve the high quality of the code base, we follow a contribution process that is explained in this document.</p> |
| |
| <p><strong>Please feel free to ask questions at any time.</strong> Either send a mail to the <a href="/community.html#mailing-lists">dev mailing list</a> or comment on the Jira issue you are working on.</p> |
| |
| <p><strong>IMPORTANT</strong>: Please read this document carefully before starting to work on a code contribution. Follow the process and guidelines explained below. Contributing to Apache Flink does not start with opening a pull request. We expect contributors to reach out to us first to discuss the overall approach together. Without consensus with the Flink committers, contributions might require substantial rework or will not be reviewed.</p> |
| |
| <div class="page-toc"> |
| <ul id="markdown-toc"> |
| <li><a href="#looking-for-what-to-contribute" id="markdown-toc-looking-for-what-to-contribute">Looking for what to contribute</a></li> |
| <li><a href="#code-contribution-process" id="markdown-toc-code-contribution-process">Code Contribution Process</a> <ul> |
| <li><a href="#create-jira-ticket-and-reach-consensus" id="markdown-toc-create-jira-ticket-and-reach-consensus">1. Create Jira Ticket and Reach Consensus</a></li> |
| <li><a href="#implement-your-change" id="markdown-toc-implement-your-change">2. Implement your change</a></li> |
| <li><a href="#open-a-pull-request" id="markdown-toc-open-a-pull-request">3. Open a Pull Request</a></li> |
| <li><a href="#merge-change" id="markdown-toc-merge-change">4. Merge change</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| </div> |
| |
| <h2 id="looking-for-what-to-contribute">Looking for what to contribute</h2> |
| |
| <p>If you have a good idea for the contribution, you can proceed to <a href="#code-contribution-process">the code contribution process</a>. |
| If you are looking for what you could contribute, you can browse open Jira issues in <a href="https://issues.apache.org/jira/projects/FLINK/issues">Flink’s bug tracker</a>, |
| which are not assigned, and then follow <a href="#code-contribution-process">the code contribution process</a>. If you are very new |
| to the Flink project and want to learn about it and its contribution process, you can check |
| <a href="https://issues.apache.org/jira/issues/?filter=12349196">the starter issues</a>, which are annotated with a <em>starter</em> label.</p> |
| |
| <h2 id="code-contribution-process">Code Contribution Process</h2> |
| |
| <style> |
| .contribute-grid { |
| margin-bottom: 10px; |
| display: flex; |
| flex-direction: column; |
| margin-left: -2px; |
| margin-right: -2px; |
| } |
| |
| .contribute-grid .column { |
| margin-top: 4px; |
| padding: 0 2px; |
| } |
| |
| @media only screen and (min-width: 480px) { |
| .contribute-grid { |
| flex-direction: row; |
| flex-wrap: wrap; |
| } |
| |
| .contribute-grid .column { |
| flex: 0 0 50%; |
| } |
| |
| .contribute-grid .column { |
| margin-top: 4px; |
| } |
| } |
| |
| @media only screen and (min-width: 960px) { |
| .contribute-grid { |
| flex-wrap: nowrap; |
| } |
| |
| .contribute-grid .column { |
| flex: 0 0 25%; |
| } |
| |
| } |
| |
| .contribute-grid .panel { |
| height: 100%; |
| margin: 0; |
| } |
| |
| .contribute-grid .panel-body { |
| padding: 10px; |
| } |
| |
| .contribute-grid h2 { |
| margin: 0 0 10px 0; |
| padding: 0; |
| display: flex; |
| align-items: flex-start; |
| } |
| |
| .contribute-grid .number { |
| margin-right: 0.25em; |
| font-size: 1.5em; |
| line-height: 0.9; |
| } |
| </style> |
| |
| <div class="alert alert-warning" role="alert"> |
| <b>Note:</b> The code contribution process has changed recently (June 2019). The community <a href="https://lists.apache.org/thread.html/1e2b85d0095331606ad0411ca028f061382af08138776146589914f8@%3Cdev.flink.apache.org%3E">decided</a> to shift the "backpressure" from pull requests to Jira, by requiring contributors to get consensus (indicated by being assigned to the ticket) before opening a pull request. |
| </div> |
| |
| <div class="contribute-grid"> |
| <div class="column"> |
| <div class="panel panel-default"> |
| <div class="panel-body"> |
| <h2><span class="number">1</span><a href="#consensus">Discuss</a></h2> |
| <p>Create a Jira ticket or mailing list discussion and reach consensus</p> |
| <p>Agree on importance, relevance, scope of the ticket, discuss the implementation approach and find a committer willing to review and merge the change.</p> |
| <p><b>Only committers can assign a Jira ticket.</b></p> |
| </div> |
| </div> |
| </div> |
| <div class="column"> |
| <div class="panel panel-default"> |
| <div class="panel-body"> |
| <h2><span class="number">2</span><a href="#implement">Implement</a></h2> |
| <p>Implement the change according to the <a href="/contributing/code-style-and-quality-preamble.html">Code Style and Quality Guide</a> and the approach agreed upon in the Jira ticket.</p> <br /> |
| <p><b>Only start working on the implementation if there is consensus on the approach (e.g. you are assigned to the ticket)</b></p> |
| </div> |
| </div> |
| </div> |
| <div class="column"> |
| <div class="panel panel-default"> |
| <div class="panel-body"> |
| <h2><span class="number">3</span><a href="#review">Review</a></h2> |
| <p>Open a pull request and work with the reviewer.</p> |
| <p><b>Pull requests belonging to unassigned Jira tickets or not authored by assignee will not be reviewed or merged by the community.</b></p> |
| </div> |
| </div> |
| </div> |
| <div class="column"> |
| <div class="panel panel-default"> |
| <div class="panel-body"> |
| <h2><span class="number">4</span><a href="#merge">Merge</a></h2> |
| <p>A committer of Flink checks if the contribution fulfills the requirements and merges the code to the codebase.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="row"> |
| <div class="col-sm-12"> |
| <div class="panel panel-default"> |
| <div class="panel-body"> |
| Note: <i>trivial</i> hot fixes such as typos or syntax errors can be opened as a <code>[hotfix]</code> pull request, without a Jira ticket. |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <p><a name="consensus"></a></p> |
| |
| <h3 id="create-jira-ticket-and-reach-consensus">1. Create Jira Ticket and Reach Consensus</h3> |
| |
| <p>The first step for making a contribution to Apache Flink is to reach consensus with the Flink community. This means agreeing on the scope and implementation approach of a change.</p> |
| |
| <p>In most cases, the discussion should happen in <a href="https://issues.apache.org/jira/projects/FLINK/summary">Flink’s bug tracker: Jira</a>.</p> |
| |
| <p>The following types of changes require a <code>[DISCUSS]</code> thread on the dev@flink.a.o Flink mailing list:</p> |
| |
| <ul> |
| <li>big changes (major new feature; big refactorings, involving multiple components)</li> |
| <li>potentially controversial changes or issues</li> |
| <li>changes with very unclear approaches or multiple equal approaches</li> |
| </ul> |
| |
| <p>Do not open a Jira ticket for these types of changes before the discussion has come to a conclusion. |
| Jira tickets based on a dev@ discussion need to link to that discussion and should summarize the outcome.</p> |
| |
| <p><strong>Requirements for a Jira ticket to get consensus:</strong></p> |
| |
| <ul> |
| <li>Formal requirements |
| <ul> |
| <li>The <em>Title</em> describes the problem concisely.</li> |
| <li>The <em>Description</em> gives all the details needed to understand the problem or feature request.</li> |
| <li>The <em>Component</em> field is set: Many committers and contributors only focus on certain subsystems of Flink. Setting the appropriate component is important for getting their attention.</li> |
| </ul> |
| </li> |
| <li>There is <strong>agreement</strong> that the ticket solves a valid problem, and that it is a <strong>good fit</strong> for Flink. |
| The Flink community considers the following aspects: |
| <ul> |
| <li>Does the contribution alter the behavior of features or components in a way that it may break previous users’ programs and setups? If yes, there needs to be a discussion and agreement that this change is desirable.</li> |
| <li>Does the contribution conceptually fit well into Flink? Is it too much of a special case such that it makes things more complicated for the common case, or bloats the abstractions / APIs?</li> |
| <li>Does the feature fit well into Flink’s architecture? Will it scale and keep Flink flexible for the future, or will the feature restrict Flink in the future?</li> |
| <li>Is the feature a significant new addition (rather than an improvement to an existing part)? If yes, will the Flink community commit to maintaining this feature?</li> |
| <li>Does this feature align well with Flink’s roadmap and currently ongoing efforts?</li> |
| <li>Does the feature produce added value for Flink users or developers? Or does it introduce the risk of regression without adding relevant user or developer benefit?</li> |
| <li>Could the contribution live in another repository, e.g., Apache Bahir or another external repository?</li> |
| <li>Is this a contribution just for the sake of getting a commit in an open source project (fixing typos, style changes merely for taste reasons)</li> |
| </ul> |
| </li> |
| <li>There is <strong>consensus</strong> on how to solve the problem. This includes considerations such as |
| <ul> |
| <li>API and data backwards compatibility and migration strategies</li> |
| <li>Testing strategies</li> |
| <li>Impact on Flink’s build time</li> |
| <li>Dependencies and their licenses</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>If a change is identified as a large or controversial change in the discussion on Jira, it might require a <a href="https://cwiki.apache.org/confluence/display/FLINK/Flink+Improvement+Proposals">Flink Improvement Proposal (FLIP)</a> or a discussion on the <a href="/community.html#mailing-lists">dev mailing list</a> to reach agreement and consensus.</p> |
| |
| <p>Contributors can expect to get a first reaction from a committer within a few days after opening the ticket. If a ticket doesn’t get any attention, we recommend reaching out to the <a href="/community.html#mailing-lists">developer mailing list</a>. Note that the Flink community sometimes does not have the capacity to accept all incoming contributions.</p> |
| |
| <p>Once all requirements for the ticket are met, a committer will assign somebody to the <em><code>Assignee</code></em> field of the ticket to work on it. |
| Only committers have the permission to assign somebody.</p> |
| |
| <p><strong>Pull requests belonging to unassigned Jira tickets will not be reviewed or merged by the community</strong>.</p> |
| |
| <p><a name="implement"></a></p> |
| |
| <h3 id="implement-your-change">2. Implement your change</h3> |
| |
| <p>Once you’ve been assigned to a Jira issue, you may start to implement the required changes.</p> |
| |
| <p>Here are some further points to keep in mind while implementing:</p> |
| |
| <ul> |
| <li><a href="https://cwiki.apache.org/confluence/display/FLINK/Setting+up+a+Flink+development+environment">Set up a Flink development environment</a></li> |
| <li>Follow the <a href="/contributing/code-style-and-quality-preamble.html">Code Style and Quality Guide</a> of Flink</li> |
| <li>Take any discussions and requirements from the Jira issue or design document into account.</li> |
| <li>Do not mix unrelated issues into one contribution.</li> |
| </ul> |
| |
| <p><a name="review"></a></p> |
| |
| <h3 id="open-a-pull-request">3. Open a Pull Request</h3> |
| |
| <p>Considerations before opening a pull request:</p> |
| |
| <ul> |
| <li>Make sure that <strong><code>mvn clean verify</code></strong> is passing on your changes to ensure that all checks pass, the code builds and that all tests pass.</li> |
| <li>Execute the <a href="https://github.com/apache/flink/tree/master/flink-end-to-end-tests#running-tests">End to End tests of Flink</a>.</li> |
| <li>Make sure no unrelated or unnecessary reformatting changes are included.</li> |
| <li>Make sure your commit history adheres to the requirements.</li> |
| <li>Make sure your change has been rebased to the latest commits in your base branch.</li> |
| <li>Make sure the pull request refers to the respective Jira, and that each Jira issue is assigned to exactly one pull request (in case of multiple pull requests for one Jira; resolve that situation first)</li> |
| </ul> |
| |
| <p>Considerations before or right after opening a pull request:</p> |
| |
| <ul> |
| <li>Make sure that the branch is building successfully on <a href="https://travis-ci.org/">Travis</a>.</li> |
| </ul> |
| |
| <p>Code changes in Flink are reviewed and accepted through <a href="https://help.github.com/en/articles/creating-a-pull-request">GitHub pull requests</a>.</p> |
| |
| <p>There is a separate guide on <a href="/contributing/reviewing-prs.html">how to review a pull request</a>, including our pull request review process. As a code author, you should prepare your pull request to meet all requirements.</p> |
| |
| <p><a name="merge"></a></p> |
| |
| <h3 id="merge-change">4. Merge change</h3> |
| |
| <p>The code will be merged by a committer of Flink once the review is finished. The Jira ticket will be closed afterwards.</p> |
| |
| |
| |
| </div> |
| </div> |
| |
| </div> |
| </div> |
| |
| <hr /> |
| |
| <div class="row"> |
| <div class="footer text-center col-sm-12"> |
| <p>Copyright © 2014-2019 <a href="http://apache.org">The Apache Software Foundation</a>. All Rights Reserved.</p> |
| <p>Apache Flink, Flink®, Apache®, the squirrel logo, and the Apache feather logo are either registered trademarks or trademarks of The Apache Software Foundation.</p> |
| <p><a href="/privacy-policy.html">Privacy Policy</a> · <a href="/blog/feed.xml">RSS feed</a></p> |
| </div> |
| </div> |
| </div><!-- /.container --> |
| |
| <!-- Include all compiled plugins (below), or include individual files as needed --> |
| <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.matchHeight/0.7.0/jquery.matchHeight-min.js"></script> |
| <script src="/js/codetabs.js"></script> |
| <script src="/js/stickysidebar.js"></script> |
| |
| <!-- Google Analytics --> |
| <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','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-52545728-1', 'auto'); |
| ga('send', 'pageview'); |
| </script> |
| </body> |
| </html> |
