You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by rm...@apache.org on 2019/06/21 14:36:36 UTC
[flink-web] 01/08: [FLINK-12605] Simplify how to contribute page
This is an automated email from the ASF dual-hosted git repository.
rmetzger pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/flink-web.git
commit e81818e69cc0abcf597745c0165420856249d35c
Author: Robert Metzger <rm...@apache.org>
AuthorDate: Tue May 7 12:50:44 2019 +0200
[FLINK-12605] Simplify how to contribute page
---
_layouts/base.html | 2 +-
community.md | 29 ++++---
contribute-code.md | 231 +++++++++++++++++++++++++--------------------------
how-to-contribute.md | 186 +++++++++++++++++++++--------------------
js/codetabs.js | 1 -
reviewing-prs.md | 5 ++
6 files changed, 234 insertions(+), 220 deletions(-)
diff --git a/_layouts/base.html b/_layouts/base.html
index b14e49d..0581c32 100755
--- a/_layouts/base.html
+++ b/_layouts/base.html
@@ -10,7 +10,7 @@
<link rel="icon" href="{{ site.baseurl }}/favicon.ico" type="image/x-icon">
<!-- Bootstrap -->
- <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">
<link rel="stylesheet" href="{{ site.baseurl }}/css/flink.css">
<link rel="stylesheet" href="{{ site.baseurl }}/css/syntax.css">
diff --git a/community.md b/community.md
index 57e2d01..bd9d442 100644
--- a/community.md
+++ b/community.md
@@ -6,16 +6,10 @@ title: "Community & Project Info"
{% toc %}
+## How do I get help from Apache Flink?
There are many ways to get help from the Apache Flink community. The [mailing lists](#mailing-lists) are the primary place where all Flink committers are present. For user support and questions use the *user mailing list*. Some committers are also monitoring [Stack Overflow](http://stackoverflow.com/questions/tagged/apache-flink). Please remember to tag your questions with the *[apache-flink](http://stackoverflow.com/questions/tagged/apache-flink)* tag. Bugs and feature requests can eith [...]
-If you send us an email with a code snippet, make sure that:
-
-1. you do not link to files in external services as such files can change, get deleted or the link might break and thus make an archived email thread useless
-2. you paste text instead of screenshots of text
-3. you keep formatting when pasting code in order to keep the code readable
-4. there are enough import statements to avoid ambiguities
-
## Mailing Lists
@@ -123,6 +117,23 @@ If you send us an email with a code snippet, make sure that:
<b style="color:red">Please make sure you are subscribed to the mailing list you are posting to!</b> If you are not subscribed to the mailing list, your message will either be rejected (dev@ list) or you won't receive the response (user@ list).
+### How to subscribe to a mailing list
+
+Before you can post a message to a mailing list, you need to subscribe to the list first.
+
+1. Send an email without any contents or subject to subscribe-*listname*@flink.apache.org. (replace *listname* with dev, user, user-zh, ..)
+2. Wait till you receive an email with the subject "confirm subscribe to *listname*@flink.apache.org". Reply to that email, without editing the subject or including any contents
+3. Wait till you receive an email with the subject "WELCOME to *listname*@flink.apache.org".
+
+
+If you send us an email with a code snippet, make sure that:
+
+1. you do not link to files in external services as such files can change, get deleted or the link might break and thus make an archived email thread useless
+2. you paste text instead of screenshots of text
+3. you keep formatting when pasting code in order to keep the code readable
+4. there are enough import statements to avoid ambiguities
+
+
## Stack Overflow
Committers are watching [Stack Overflow](http://stackoverflow.com/questions/tagged/apache-flink) for the [apache-flink](http://stackoverflow.com/questions/tagged/apache-flink) tag.
@@ -172,11 +183,9 @@ The Apache Flink <a href="https://cwiki.apache.org/confluence/display/FLINK/Apac
## Flink Forward
-Flink Forward 2015 (October 12-13, 2015) was the first conference to bring together the Apache Flink developer and user community. You can find [slides and videos](http://2015.flink-forward.org/?post_type=session) of all talks on the Flink Forward 2015 page.
+Flink Forward is a conference happening yearly in different locations around the world. Up to date information about the conference is available on <a href="https://www.flink-forward.org/">Flink-Forward.org</a>.
-The second edition of Flink Forward took place on September 12-14, 2016. All [slides and videos](http://2016.flink-forward.org/program/sessions/) are available on the Flink Forward 2016 page.
-In 2017, Flink Forward came to San Francisco to welcome the Apache Flink community to one day of training and one day of conference. Find all videos on our [YouTube Channel](https://www.youtube.com/playlist?list=PLDX4T_cnKjD2UC6wJr_wRbIvtlMtkc-n2) and all slides on [SlideShare](https://www.slideshare.net/FlinkForward).
# People
diff --git a/contribute-code.md b/contribute-code.md
index 35c8c32..feb22cc 100644
--- a/contribute-code.md
+++ b/contribute-code.md
@@ -2,11 +2,11 @@
title: "Contributing Code"
---
-Apache Flink is maintained, improved, and extended by code contributions of volunteers. The Apache Flink community encourages anybody to contribute source code. In order to ensure a pleasant contribution experience for contributors and reviewers and to preserve the high quality of the code base, we follow a contribution process that is explained in this document.
+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.
-This document contains everything you need to know about contributing code to Apache Flink. It describes the process of preparing, testing, and submitting a contribution, explains coding guidelines and code style of Flink's code base, and gives instructions to setup a development environment.
+**Please feel free to ask questions at any time.** Either send a mail to the [dev mailing list]( {{ site.base }}/community.html#mailing-lists ) or comment on the Jira issue you are working on.
-**IMPORTANT**: Please read this document carefully before starting to work on a code contribution. It is important to follow the process and guidelines explained below. Otherwise, your pull request might not be accepted or might require substantial rework. In particular, before opening a pull request that implements a **new feature**, you need to open a Jira ticket and reach consensus with the community on whether this feature is needed.
+**IMPORTANT**: Please read this document carefully before starting to work on a code contribution. Follow the process and guidelines explained below. Otherwise, your pull request might not be accepted or might require substantial rework. In particular, before opening a pull request that implements a **new feature**, you need to open a Jira ticket and reach consensus with the community on whether this feature is needed.
@@ -14,81 +14,129 @@ This document contains everything you need to know about contributing code to Ap
## Code Contribution Process
-### Before you start coding…
-
-…please make sure there is a Jira issue that corresponds to your contribution. This is a *general rule* that the Flink community follows for all code contributions, including bug fixes, improvements, or new features, with an exception for *trivial* hot fixes. If you would like to fix a bug that you found or if you would like to add a new feature or improvement to Flink, please follow the [File a bug report]({{ site.baseurl }}/how-to-contribute.html#file-a-bug-report) or [Propose an impro [...]
-
-If the description of a Jira issue indicates that its resolution will touch sensitive parts of the code base, be sufficiently complex, or add significant amounts of new code, the Flink community might request a design document. (Most contributions should not require a design document.) The purpose of this document is to ensure that the overall approach to address the issue is sensible and agreed upon by the community. Jira issues that require a design document are tagged with the **`requ [...]
-
-- Overview of the general approach.
-- List of API changes (changed interfaces, new and deprecated configuration parameters, changed behavior, …).
-- Main components and classes to be touched.
-- Known limitations of the proposed approach.
-
-A design document can be added by anybody, including the reporter of the issue or the person working on it.
-
-Contributions for Jira issues that require a design document will not be added to Flink's code base before a design document has been accepted by the community with [lazy consensus](http://www.apache.org/foundation/glossary.html#LazyConsensus). Please check if a design document is required before starting to code.
-
-
-### While coding…
-
-…please respect the following rules:
-
-- Take any discussion or requirement that is recorded in the Jira issue into account.
-- Follow the design document (if a design document is required) as close as possible. Please update the design document and seek consensus, if your implementation deviates too much from the solution proposed by the design document. Minor variations are OK but should be pointed out when the contribution is submitted.
-- Closely follow the [coding guidelines]( {{site.base}}/contribute-code.html#coding-guidelines) and the [code style]({{ site.base }}/contribute-code.html#code-style).
+<style>
+.process-box {
+ border: 1px solid #dee2e6!important;
+ border-radius: .5rem!important;
+ margin: 2px;
+ margin-bottom: 5px;
+ padding: 10px;
+ width: 24%;
+ height: 300px;
+}
+</style>
+
+<div class="row">
+ <div class="col-sm-3 process-box">
+ <h2><a href="#consensus">1. JIRA Ticket: Get Consensus</a></h2>
+ Agree on importance, relevance, scope of the ticket, discuss the implementation approach and find a committer willing to review and merge the change.<br>
+ <b>Only committers can assign a Jira ticket</b>.
+ </div>
+ <div class="col-sm-3 process-box">
+ <h2><a href="#implement">2. Implement</a></h2>
+ Implement the change according to the <a href="">Code Style and Quality Guide</a> and the approach agreed upon in the JIRA ticket.
+ </div>
+ <div class="col-sm-3 process-box">
+ <h2><a href="#review">3. Review</a></h2>
+ Open a pull request and work with the reviewer. <br /><br />
+ <b>Pull requests belonging to unassigned Jira tickets will not be reviewed or merged by the community</b>
+ </div>
+ <div class="col-sm-3 process-box">
+ <h2><a href="#merge">4. Merge</a></h2>
+ A committer of Flink checks if the contribution fulfills the requirements and merges the code to the codebase.
+ </div>
+</div>
+<div class="row">
+ <div class="col-sm-12 process-box" style="height:inherit; width:inherit;">
+ 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>
+
+
+<a name="consensus"></a>
+
+### 1. Jira Ticket: Get Consensus
+
+
+The first step for making a contribution to Apache Flink is to reach consensus in [Flink's bug tracker: Jira](https://issues.apache.org/jira/projects/FLINK/summary).
+This means agreeing on the scope and implementation approach of a change.
+
+**Requirements for a Jira ticket to get consensus:**
+
+ - Formal requirements
+ - The *Title* describes the problem concisely.
+ - The *Description* gives all the details needed to understand the problem or feature request.
+ - The *Component* field is set: Many committers and contributors only focus on certain subsystems of Flink. Setting the appropriate component is important for getting their attention.
+ - There is **agreement** that the ticket solves a valid problem, and that it is a **good fit** for Flink.
+ The Flink community considers the following aspects:
+ - 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.
+ - 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?
+ - 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?
+ - 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?
+ - Does this feature align well with Flink's roadmap and currently ongoing efforts?
+ - 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?
+ - Could the contribution live in another repository, e.g., Apache Bahir or another external repository?
+ - 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)
+ - There is **consensus** on how to solve the problem. This includes considerations such as
+ - API and data backwards compatibility and migration strategies
+ - testing strategies
+ - impact on Flink's build time
+ - dependencies and their licenses
+
+Large changes might require a [Flink Improvement Proposal (FLIP)](https://cwiki.apache.org/confluence/display/FLINK/Flink+Improvement+Proposals) or a discussion on the [dev mailing list]( {{ site.base }}/community.html#mailing-lists ) to reach agreement or consensus.
+
+Once all requirements for the ticket are met, a committer will assign somebody to the *`Assignee`* field of the ticket to work on it.
+Only committers have the permission to assign somebody.
+
+**Pull requests belonging to unassigned Jira tickets will not be reviewed or merged by the community**.
+
+
+<a name="implement"></a>
+
+### 2. Implement your change
+
+- Follow the [Code Style and Quality Guide]() of Flink
+- Take any discussions and requirements from the Jira issue or design document into account.
- Do not mix unrelated issues into one contribution.
-**Please feel free to ask questions at any time.** Either send a mail to the [dev mailing list]( {{ site.base }}/community.html#mailing-lists ) or comment on the Jira issue.
-The following instructions will help you to [setup a development environment]( {{ site.base }}/contribute-code.html#setup-a-development-environment).
+<a name="review"></a>
+### 3. Open a Pull Request
+Code changes in Flink are reviewed and accepted through [GitHub pull requests](https://help.github.com/en/articles/creating-a-pull-request).
+There is a separate guide on [how to review a pull request]({{ site.base }}/reviewing-prs.html), including our pull request review process. As a code author, you should prepare your pull request to meet all requirements.
-### Verifying the compliance of your code
+Considerations before opening a pull request:
-It is very important to verify the compliance of changes before submitting your contribution. This includes:
+ - Make sure that **`mvn clean verify`** is passing on your changes to ensure that all checks pass, the code builds and that all tests pass.
+ - Execute the [End to End tests of Flink](https://github.com/apache/flink/tree/master/flink-end-to-end-tests#running-tests).
+ - Make sure no unrelated or unnecessary reformatting changes are included.
+ - Make sure your commit history adheres to the requirements.
+ - Make sure your change has been rebased to the latest commits in your base branch.
-- Making sure the code builds.
-- Verifying that all existing and new tests pass.
-- Checking that the code style is not violated.
-- Making sure no unrelated or unnecessary reformatting changes are included.
-You can build the code, run the tests, and check (parts of) the code style by calling:
+Considerations before or right after opening a pull request:
-```
-mvn clean verify
-```
-
-Please note that some tests in Flink's code base are flaky and can fail by chance. The Flink community is working hard on improving these tests but sometimes this is not possible, e.g., when tests include external dependencies. We maintain all tests that are known to be flaky in Jira and attach the **`test-stability`** label. Please check (and extend) this list of [known flaky tests](https://issues.apache.org/jira/issues/?jql=project%20%3D%20FLINK%20AND%20resolution%20%3D%20Unresolved%20 [...]
-
-Please note that we run additional build profiles for different combinations of Java, Scala, and Hadoop versions to validate your contribution. We encourage every contributor to use a *continuous integration* service that will automatically test the code in your repository whenever you push a change. The [Best practices]( {{site.base}}/contribute-code.html#best-practices ) guide shows how to integrate [Travis](https://travis-ci.org/) with your GitHub repository.
-
-In addition to the automated tests, please check the diff of your changes and remove all unrelated changes such as unnecessary reformatting.
+ - Make sure that the branch is building successfully on [Travis](https://travis-ci.org/).
+<a name="merge"></a>
-### Preparing and submitting your contribution
+### 4. Merge change
-To make the changes easily mergeable, please rebase them to the latest version of the main repository's master branch. Please also respect the [commit message guidelines]( {{ site.base }}/contribute-code.html#coding-guidelines ), clean up your commit history, and squash your commits to an appropriate set. Please verify your contribution one more time after rebasing and commit squashing as described above.
+The code will be merged by a committer of Flink once the review is finished. The Jira ticket will be closed afterwards.
-The Flink project accepts code contributions through the [GitHub Mirror](https://github.com/apache/flink), in the form of [Pull Requests](https://help.github.com/articles/using-pull-requests). Pull requests are a simple way to offer a patch, by providing a pointer to a code branch that contains the change.
-To open a pull request, push your contribution back into your fork of the Flink repository.
-```
-git push origin myBranch
-```
-
-Go to the website of your repository fork (`https://github.com/<your-user-name>/flink`) and use the *"Create Pull Request"* button to start creating a pull request. Make sure that the base fork is `apache/flink master` and the head fork selects the branch with your changes. Give the pull request a meaningful description and send it.
-
-It is also possible to attach a patch to a [Jira]({{site.FLINK_ISSUES_URL}}) issue.
-----
-## Coding guidelines
+## Coding guidelines (OUTDATED)
+
+*Note: These guidelines are outdated and will be updated soon.*
### Pull requests and commit message
{:.no_toc}
@@ -137,77 +185,26 @@ It is also possible to attach a patch to a [Jira]({{site.FLINK_ISSUES_URL}}) iss
## Code style
-### License
-- **Apache license headers.** Make sure you have Apache License headers in your files. The RAT plugin is checking for that when you build the code.
-
-### Imports
-- **Empty line before and after package declaration.**
-- **No unused imports.**
-- **No redundant imports.**
-- **No wildcard imports.** They can cause problems when adding to the code and in some cases even during refactoring.
-- **Import order.** Imports must be ordered alphabetically, grouped into the following blocks, with each block separated by an empty line:
- - <imports from org.apache.flink.*>
- - <imports from org.apache.flink.shaded.*>
- - <imports from other libraries>
- - <imports from javax.*>
- - <imports from java.*>
- - <imports from scala.*>
- - <static imports>
-
-### Naming
-- **Package names must start with a letter, and must not contain upper-case letters or special characters.**
-- **Non-private static final fields must be upper-case, with words being separated by underscores.** (`MY_STATIC_VARIABLE`)
-- **Non-static fields/methods must be in lower camel case.** (`myNonStaticField`)
-
-### Whitespace
-- **Tabs vs. spaces.** We are using tabs for indentation, not spaces. We are not religious there; it just happened to be that we started with tabs, and it is important to not mix them (merge/diff conflicts).
-- **No trailing whitespace.**
-- **Spaces around operators/keywords.** Operators (`+`, `=`, `>`, …) and keywords (`if`, `for`, `catch`, …) must have a space before and after them, provided they are not at the start or end of the line.
-
-### Braces
-- **Left curly braces (`{`) must not be placed on a new line.**
-- **Right curly braces (`}`) must always be placed at the beginning of the line.**
-- **Blocks.** All statements after `if`, `for`, `while`, `do`, … must always be encapsulated in a block with curly braces (even if the block contains one statement).
-
- ```java
-for (…) {
- …
-}
-```
- If you are wondering why, recall the famous [*goto bug*](https://www.imperialviolet.org/2014/02/22/applebug.html) in Apple's SSL library.
+-----
-### Javadocs
-- **All public/protected methods and classes must have a Javadoc.**
-- **The first sentence of the Javadoc must end with a period.**
-- **Paragraphs must be separated with a new line, and started with <p>.**
+## Best practices
-### Modifiers
-- **No redundant modifiers.** For example, public modifiers in interface methods.
-- **Follow JLS3 modifier order.** Modifiers must be ordered in the following order: public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp.
+- Travis: Flink is pre-configured for [Travis CI](http://docs.travis-ci.com/), which can be easily enabled for your personal repository fork (it uses GitHub for authentication, so you do not need an additional account). Simply add the *Travis CI* hook to your repository (*Settings --> Integrations & services --> Add service*) and enable tests for the `flink` repository on [Travis](https://travis-ci.org/profile).
-### Files
-- **All files must end with `\n`.**
-- **File length must not exceed 3000 lines.**
+-----
-### Misc
-- **Arrays must be defined Java-style.** For example, `public String[] array`.
-- **Use Flink Preconditions.** To increase homogeneity, consistently use the `org.apache.flink.Preconditions` methods `checkNotNull` and `checkArgument` rather than Apache Commons Validate or Google Guava.
-- **No raw generic types.** Do not use raw generic types, unless strictly necessary (sometime necessary for signature matches, arrays).
-- **Suppress warnings.** Add annotations to suppress warnings, if they cannot be avoided (such as "unchecked", or "serial").
-- **Comments.** Add comments to your code. What is it doing? Add Javadocs or inherit them by not adding any comments to the methods. Do not automatically generate comments, and avoid unnecessary comments like:
+---
- ```java
-i++; // increment by one
-```
------
-## Best practices
+Please note that some tests in Flink's code base are flaky and can fail by chance. The Flink community is working hard on improving these tests but sometimes this is not possible, e.g., when tests include external dependencies. We maintain all tests that are known to be flaky in Jira and attach the **`test-stability`** label. Please check (and extend) this list of [known flaky tests](https://issues.apache.org/jira/issues/?jql=project%20%3D%20FLINK%20AND%20resolution%20%3D%20Unresolved%20 [...]
+
+Please note that we run additional build profiles for different combinations of Java, Scala, and Hadoop versions to validate your contribution. We encourage every contributor to use a *continuous integration* service that will automatically test the code in your repository whenever you push a change. The [Best practices]( {{site.base}}/contribute-code.html#best-practices ) guide shows how to integrate [Travis](https://travis-ci.org/) with your GitHub repository.
+
+In addition to the automated tests, please check the diff of your changes and remove all unrelated changes such as unnecessary reformatting.
-- Travis: Flink is pre-configured for [Travis CI](http://docs.travis-ci.com/), which can be easily enabled for your personal repository fork (it uses GitHub for authentication, so you do not need an additional account). Simply add the *Travis CI* hook to your repository (*Settings --> Integrations & services --> Add service*) and enable tests for the `flink` repository on [Travis](https://travis-ci.org/profile).
------
## Setup a development environment
diff --git a/how-to-contribute.md b/how-to-contribute.md
index 7c50316..1475de7 100644
--- a/how-to-contribute.md
+++ b/how-to-contribute.md
@@ -6,17 +6,75 @@ title: "How To Contribute"
Apache Flink is developed by an open and friendly community. Everybody is cordially welcome to join the community and contribute to Apache Flink. There are several ways to interact with the community and to contribute to Flink including asking questions, filing bug reports, proposing new features, joining discussions on the mailing lists, contributing code or documentation, improving the website, or testing release candidates.
-{% toc %}
-## Ask questions!
+<h1>What do you want to do?</h1>
+<p>Contributing to Apache Flink goes beyond writing code for the project. Below, we list different opportunities to help the project:</p>
+
+
+<table class="table table-bordered">
+ <thead>
+ <tr>
+ <th>Area</th>
+ <th>Further information</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><span class="glyphicon glyphicon-console" aria-hidden="true"></span> Contribute Code</td>
+ <td>Read the <a href="{{ site.baseurl }}/contribute-code.html">Code Contribution Guide</a></td>
+ </tr>
+ <tr>
+ <td><span class="glyphicon glyphicon-ok" aria-hidden="true"></span> Help With Code Reviews</td>
+ <td>Read the <a href="{{ site.baseurl }}/reviewing-prs.html">Code Review Guide</a></td>
+ </tr>
+ <tr>
+ <td><span class="glyphicon glyphicon-thumbs-up" aria-hidden="true"></span> Review a Release Candidate</td>
+ <td>
+ Releasing a new version consists of the following steps:
+ <ol>
+ <li>Building a new release candidate and starting a vote (usually for 72 hours) on the dev@flink.apache.org list</li>
+ <li>Testing the release candidate and voting (+1 if no issues were found, -1 if the release candidate has issues).</li>
+ <li>Going back to step 1 if the release candidate had issues. Otherwise we publish the release.</li>
+ </ol>
+ Read the <a href="https://cwiki.apache.org/confluence/display/FLINK/Releasing">test procedure for a release</a>.
+ </td>
+ </tr>
+ <tr>
+ <td><span class="glyphicon glyphicon-list-alt" aria-hidden="true"></span> Contribute Documentation</td>
+ <td>Read the <a href="{{ site.baseurl }}/contribute-documentation.html">Documentation Contribution Guide</a></td>
+ </tr>
+ <tr>
+ <td><span class="glyphicon glyphicon-user" aria-hidden="true"></span> Support Flink Users</td>
+ <td>
+ <ul class="contribute-card-list">
+ <li>Reply to questions on the <a href="https://flink.apache.org/community.html#mailing-lists">user mailing list</a></li>
+ <li>Reply to Flink related questions on <a href="https://stackoverflow.com/questions/tagged/apache-flink">Stack Overflow</a> with the <a href="https://stackoverflow.com/questions/tagged/apache-flink"><code style="background-color: #cee0ed; border-color: #cee0ed;">apache-flink</code></a> tag</li>
+ <li>Check the latest issues in <a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20FLINK%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20created%20DESC%2C%20priority%20DESC%2C%20updated%20DESC">Jira</a> for tickets which are actually user questions</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td><span class="glyphicon glyphicon-blackboard" aria-hidden="true"></span> Contribute To The Website</td>
+ <td>Read the <a href="{{ site.baseurl }}/improve-website.html">Website Contribution Guide</a></td>
+ </tr>
+ <tr>
+ <td><span class="glyphicon glyphicon-volume-up" aria-hidden="true"></span> Contribute Evangelism</td>
+ <td>
+ <ul class="contribute-card-list">
+ <li>Organize or attend a <a href="https://www.meetup.com/topics/apache-flink/">Flink Meetup</a></li>
+ <li>Contribute to the <a href="https://flink.apache.org/blog/">Flink blog</a></li>
+ <li>Submit a talk to conference. <a href="https://flink.apache.org/community.html#mailing-lists">Contact the community@flink.apache.org mailing list</a> to learn about relevant conferences near you.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <span class="glyphicon glyphicon-question-sign" aria-hidden="true"></span> Any other question? Reach out to the <a href="https://flink.apache.org/community.html#mailing-lists">community@flink.apache.org mailing list</a> to get help!
+ </td>
+ </tr>
+ </tbody>
+</table>
-The Apache Flink community is eager to help and to answer your questions. We have a [user mailing list]({{ site.baseurl }}/community.html#mailing-lists ) and watch Stack Overflow on the [[apache-flink]](http://stackoverflow.com/questions/tagged/apache-flink) tag.
-
------
-
-## File a bug report
-
-Please let us know if you experienced a problem with Flink and file a bug report. Open [Flink's Jira](http://issues.apache.org/jira/browse/FLINK), log in if necessary, and click on the red **Create** button at the top. Please give detailed information about the problem you encountered and, if possible, add a description that helps to reproduce the problem. Thank you very much.
-----
@@ -37,113 +95,59 @@ For very big features that change Flink in a fundamental way we have another pro
[Flink Improvement Proposals](https://cwiki.apache.org/confluence/display/FLINK/Flink+Improvement+Proposals). If you are interested you can propose a new feature there or follow the
discussions on existing proposals.
------
-
-## Help others and join the discussions
-
-Most communication in the Apache Flink community happens on two mailing lists:
-
-- The user mailing list `user@flink.apache.org` is the place where users of Apache Flink ask questions and seek help or advice. Joining the user list and helping other users is a very good way to contribute to Flink's community. Furthermore, there is the [[apache-flink]](http://stackoverflow.com/questions/tagged/apache-flink) tag on Stack Overflow if you'd like to help Flink users (and harvest some points) there.
-- The development mailing list `dev@flink.apache.org` is the place where Flink developers exchange ideas and discuss new features, upcoming releases, and the development process in general. If you are interested in contributing code to Flink, you should join this mailing list.
-
-You are very welcome to [subscribe to both mailing lists]({{ site.baseurl }}/community.html#mailing-lists).
-
------
-
-## Review a code contribution
-
-The Apache Flink project receives many code contributions as [Github pull requests](https://github.com/apache/flink/pulls). A great way to contribute to the Flink community is to help review pull requests.
-
-**Please read the [Review Guide]({{ site.baseurl }}/reviewing-prs.html) if you want to help review pull requests.**
-
------
-
-## Test a release candidate
-
-Apache Flink is continuously improved by its active community. Every few weeks, we release a new version of Apache Flink with bug fixes, improvements, and new features. The process of releasing a new version consists of the following steps:
-
-1. Building a new release candidate and starting a vote (usually for 72 hours).
-2. Testing the release candidate and voting (`+1` if no issues were found, `-1` if the release candidate has issues).
-3. Going back to step 1 if the release candidate had issues. Otherwise we publish the release.
-
-Our wiki contains a page that summarizes the [test procedure for a release](https://cwiki.apache.org/confluence/display/FLINK/Releasing). Release testing is a big effort if done by a small group of people but can be easily scaled out to more people. The Flink community encourages everybody to participate in the testing of a release candidate. By testing a release candidate, you can ensure that the next Flink release is working properly for your setup and help to improve the quality of releases.
-
------
-
-## Contribute code
-
-Apache Flink is maintained, improved, and extended by code contributions of volunteers. The Apache Flink community encourages anybody to contribute source code. In order to ensure a pleasant contribution experience for contributors and reviewers and to preserve the high quality of the code base, we follow a contribution process that is explained in our [Contribute code]( {{ site.base }}/contribute-code.html) guide. The guide also includes instructions on how to setup a development enviro [...]
-
-**Please read the [Contribute code]( {{ site.base }}/contribute-code.html) guide before you start to work on a code contribution.**
-
-Please do also read the [Submit a Contributor License Agreement]({{ site.baseurl }}/how-to-contribute.html#submit-a-contributor-license-agreement) Section.
-
-### Looking for an issue to work on?
-{:.no_toc}
-
-We maintain a list of all known bugs, proposed improvements, and suggested features in [Flink's Jira](https://issues.apache.org/jira/browse/FLINK/?selectedTab=com.atlassian.jira.jira-projects-plugin:issues-panel). Issues that we believe are good tasks for new contributors are tagged with a special "starter" tag. Those tasks are supposed to be rather easy to solve and will help you to become familiar with the project and the contribution process.
-
-Please have a look at the list of [starter issues](https://issues.apache.org/jira/issues/?jql=project%20%3D%20FLINK%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20starter%20ORDER%20BY%20priority%20DESC), if you are looking for an issue to work on. You can of course also choose [any other issue](https://issues.apache.org/jira/issues/?jql=project%20%3D%20FLINK%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC) to work on. Feel free to ask questions about is [...]
-----
-## Contribute documentation
+## Submit a Contributor License Agreement
-Good documentation is crucial for any kind of software. This is especially true for sophisticated software systems such as distributed data processing engines like Apache Flink. The Apache Flink community aims to provide concise, precise, and complete documentation and welcomes any contribution to improve Apache Flink's documentation.
+Please submit a contributor license agreement to the Apache Software Foundation (ASF) if you are contributing a lot of code to Apache Flink. The following quote from [http://www.apache.org/licenses](http://www.apache.org/licenses/#clas) gives more information about the ICLA and CCLA and why they are necessary.
-- Please report missing, incorrect, or outdated documentation as a [Jira issue](http://issues.apache.org/jira/browse/FLINK).
-- Flink's documentation is written in Markdown and located in the `docs` folder in [Flink's source code repository]({{ site.baseurl }}/community.html#main-source-repositories). See the [Contribute documentation]({{ site.base }}/contribute-documentation.html) guidelines for detailed instructions for how to update and improve the documentation and to contribute your changes.
+> The ASF desires that all contributors of ideas, code, or documentation to the Apache projects complete, sign, and submit (via postal mail, fax or email) an [Individual Contributor License Agreement](http://www.apache.org/licenses/icla.txt) (CLA) [ [PDF form](http://www.apache.org/licenses/icla.pdf) ]. The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to the ASF and thereby allow us to defend the project should there be a [...]
+>
+> For a corporation that has assigned employees to work on an Apache project, a [Corporate CLA](http://www.apache.org/licenses/cla-corporate.txt) (CCLA) is available for contributing intellectual property via the corporation, that may have been assigned as part of an employment agreement. Note that a Corporate CLA does not remove the need for every developer to sign their own CLA as an individual, to cover any of their contributions which are not owned by the corporation signing the CCLA.
+>
+> ...
-----
-## Improve the website
+## Becoming a Flink Committer and PMC member
-The [Apache Flink website](http://flink.apache.org) presents Apache Flink and its community. It serves several purposes including:
+### How to become a committer
-- Informing visitors about Apache Flink and its features.
-- Encouraging visitors to download and use Flink.
-- Encouraging visitors to engage with the community.
+Committers are community members that have write access to the project's repositories, i.e., they can modify the code, documentation, and website by themselves and also accept other contributions.
-We welcome any contribution to improve our website.
+There is no strict protocol for becoming a committer or PMC member. Candidates for new committers are typically people that are active contributors and community members.
-- Please open a [Jira issue](http://issues.apache.org/jira/browse/FLINK) if you think our website could be improved.
-- Please follow the [Improve the website]({{ site.baseurl }}/improve-website.html) guidelines if you would like to update and improve the website.
+Candidates for new committers are suggested by current committers or PMC members, and voted upon by the PMC.
------
+If you would like to become a committer, you should engage with the community and start contributing to Apache Flink in any of the above ways. You might also want to talk to other committers and ask for their advice and guidance.
-## More ways to contribute…
+### What are we looking for in Committers
-There are many more ways to contribute to the Flink community. For example you can:
+Being a committer means being recognized as a significant contributor to the project (community or technology), and having the tools to help with the development. Committer candidates are community members who have made good contributions over an extended period of time and want to continue their contributions.
-- Give a talk about Flink and tell others how you use it.
-- Organize a local Meetup or user group.
-- Talk to people about Flink.
-- …
+Community contributions include helping to answer user questions on the mailing list, verifying release candidates, giving talks, organizing community events, and other forms of evangelism and community building. The "Apache Way" has a strong focus on the project community, and committers can be recognized for outstanding community contributions even without any code contributions.
------
+Code/technology contributions include contributed pull requests (patches), design discussions, reviews, testing, and other help in identifying and fixing bugs. Especially constructive and high quality design discussions, as well as helping other contributors, are strong indicators.
-## Submit a Contributor License Agreement
+While the prior points give ways to identify promising candidates, the following are "must haves" for any committer candidate:
-Please submit a contributor license agreement to the Apache Software Foundation (ASF) if you would like to contribute to Apache Flink. The following quote from [http://www.apache.org/licenses](http://www.apache.org/licenses/#clas) gives more information about the ICLA and CCLA and why they are necessary.
+ - Being community minded: The candidate understands the meritocratic principles of community management. They do not always optimize for as much as possible personal contribution, but will help and empower others where it makes sense.
-> The ASF desires that all contributors of ideas, code, or documentation to the Apache projects complete, sign, and submit (via postal mail, fax or email) an [Individual Contributor License Agreement](http://www.apache.org/licenses/icla.txt) (CLA) [ [PDF form](http://www.apache.org/licenses/icla.pdf) ]. The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to the ASF and thereby allow us to defend the project should there be a [...]
->
-> For a corporation that has assigned employees to work on an Apache project, a [Corporate CLA](http://www.apache.org/licenses/cla-corporate.txt) (CCLA) is available for contributing intellectual property via the corporation, that may have been assigned as part of an employment agreement. Note that a Corporate CLA does not remove the need for every developer to sign their own CLA as an individual, to cover any of their contributions which are not owned by the corporation signing the CCLA.
->
-> ...
+ - We trust that a committer candidate will use their write access to the repositories responsibly, an if in doubt, conservatively. Flink is a big system, and it is important that committers are aware of what they know and what they don't know. In doubt, committers should ask for a second pair of eyes rather than commit to parts that they are not well familiar with. (Even the most seasoned committers follow this practice.)
+
+ - They have shown to be respectful towards other community members and constructive in discussions.
------
-## How to become a committer
+### What are we looking for in PMC members
-Committers are community members that have write access to the project's repositories, i.e., they can modify the code, documentation, and website by themselves and also accept other contributions.
+The PMC is the official controlling body of the project. PMC members "must" be able to perform the official responsibilities of the PMC (verify releases and growth of committers/PMC). We "want" them to be people that have a vision for Flink, technology and community wise.
-There is no strict protocol for becoming a committer. Candidates for new committers are typically people that are active contributors and community members.
+For the avoidance of doubt, not every PMC member needs to know all details of how exactly Flink's release process works (it is okay to understand the gist and how to find the details). Likewise, not every PMC member needs to be a visionary. We strive to build a PMC that covers all parts well, understanding that each member brings different strengths.
-Being an active community member means participating on mailing list discussions, helping to answer questions, verifying release candidates, being respectful towards others, and following the meritocratic principles of community management. Since the "Apache Way" has a strong focus on the project community, this part is *very* important.
+Ideally, we find candidates among active community members that have shown initiative to shape the direction of Flink (technology and community) and have shown willingness to learn the official processes, such as how to create or verify for releases.
-Of course, contributing code and documentation to the project is important as well. A good way to start is contributing improvements, new features, or bug fixes. You need to show that you take responsibility for the code that you contribute, add tests and documentation, and help maintaining it.
+A PMC member is also a committer. Candidates are already committers or will automatically become also a committer when joining the PMC. Hence, the "What are we looking for in committers?" also applies to PMC candidates.
-Candidates for new committers are suggested by current committers or PMC members, and voted upon by the PMC.
+A PMC member has a lot of power in a project. A single PMC member can block many decisions and generally stall and harm the project in many ways. We hence must trust the PMC candidates to be level-headed, constructive, supportive, and willing to "disagree and commit" at times.
-If you would like to become a committer, you should engage with the community and start contributing to Apache Flink in any of the above ways. You might also want to talk to other committers and ask for their advice and guidance.
diff --git a/js/codetabs.js b/js/codetabs.js
index 878aa32..7f5f648 100755
--- a/js/codetabs.js
+++ b/js/codetabs.js
@@ -99,7 +99,6 @@ function viewSolution() {
// A script to fix internal hash links because we have an overlapping top bar.
// Based on https://github.com/twitter/bootstrap/issues/193#issuecomment-2281510
function maybeScrollToHash() {
- console.log("HERE");
if (window.location.hash && $(window.location.hash).length) {
console.log("HERE2", $(window.location.hash), $(window.location.hash).offset().top);
var newTop = $(window.location.hash).offset().top - 57;
diff --git a/reviewing-prs.md b/reviewing-prs.md
index a67e4f0..b988095 100644
--- a/reviewing-prs.md
+++ b/reviewing-prs.md
@@ -4,6 +4,11 @@ title: "How to Review a Pull Request"
<hr />
+TODO:
+- LICENSE files
+- documentation
+-
+
This guide is for all committers and contributors that want to help with reviewing code contributions. Thank you for your effort - good reviews are one the most important and crucial parts of an open source project. This guide should help the community to make reviews such that:
* Contributors have a good contribution experience.