! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide


Introduction:Whatever the original intention, Flink is very welcome to build and improve the community together. Before we start the specific contribution steps, let’s briefly introduce several ways to participate in contribution, as well as some inherent impression of clarify about open source contribution.

Author: Wu Zhen (Yunxie), Apache Flink PMC, Alibaba technical expert
Collated by: Chen Jingmin (Qing Yue)

This article is organized from the Apache Flink PMC Wu Jie (Yunxie) live sharing, aiming to provide some experience and process of participation and contribution for students who have a certain foundation of big data and are interested in the development of Flink community.

Why participate in the open source community

Yunxie, as an Apache Flink PMC member, summarized three main reasons for participating in the development of open source community according to his own experience.

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

1. Open source spirit

“Freedom” can be said to be the core of the open source spirit. Freedom means unrestrained communication, sharing and the collision of ideas in the world. “Take me personally, I happened to experience the stage of Hadoop and spark fire in my college stage. At that time, I especially looked forward to open source, especially worshipped the God who can read the source code well, and especially hoped that I could write a lot of open source code one day, so that the code I wrote could be used by tens of thousands of users. So for me, participating in open source is like a hobby, willing to pay time and effort for it. I was also lucky to be in touch with the open source community after graduation. “

2. Technological growth

Participating in open source is a good way to improve the quality of personal code. The open source community is very demanding on code and design, unlike some internal projects that are relatively casual. For design, the Flink community has a dedicated flip mechanism, and any significant contribution will be discussed openly and carefully. For the code, Flink CTO personally wrote a 26 page code style guide. In addition, after each PR submission, Flink CTO also received review suggestions from the committers. Therefore, continuous contribution of code in the open source community has greatly improved personal system thinking ability and code ability.

3. Career planning

If you are preparing to change jobs or promote within the company, besides the existing title, the experience of participating in the open source community is definitely a bonus item, because the open source products are labeled with Internet Celebrities, and participating in them will help you improve your influence and get to know the big bulls in the same industry. In addition to directly reflecting your code ability, becoming a member of a committee or even a PMC member can prove your passion & perseverance & soft skills in communication and cooperation_ etc_ .)。

How to become a contributor

1. Contribution path

Whatever the original intention, Flink is very welcome to build and improve the community together. Before we start the specific contribution steps, let’s briefly introduce several ways to participate in contribution, as well as some inherent impression of clarify about open source contribution.

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

When it comes to open source contributions, the intuitive response is to contribute code. However, in Flink community, there are many ways to participate in contribution, including documentation, translation, Q & A, testing, and code, and the community puts document contribution first and code contribution last. Because the attitude of the Apache community towards code contribution isCommunity Over CodeAnd Flink CTO personally tweeted the “unimportance” of code contribution.

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

Why? Because the benign development of open-source projects does not simply rely on the crazy code, the source code of open-source projects without communities will always stay in the stage of “narcissism”. “I have an idea, this is my code” may be the worst way to contribute, because in the absence of any documents, the committers have to try to understand the intention of the contributors through the code. This kind of reverse derivation often consumes the extra time and energy of the committers and the contributors themselves, resulting in very high communication costs and longer code consolidation cycle. On the other hand, the lack of strict code review mechanism and standardized pull requst process will lead to a significant decrease in the quality of open source code. This is why a complete set of mechanisms is required for finding typo and simple bugfix, while detailed design documents and voting are required for the refactoring of a module and the addition of features. The proportion of this part of the work is very high, so it’s natural to get to the stage of writing code. And perfect detailed documents, timely and accurate Q & A, all kinds of technology blog can create high-quality community ecology, attract more users to participate in the use, and then feed back the community. Take Konstantin and Seth, who have recently become members of the committee, for example, that their main contribution is documents. This also shows that Flink PMC Committee has recognized and attached great importance to the contribution of documents. In particular, the threshold for contribution of Chinese documents (translation) is relatively low, as long as they have a certain English foundation& The ability of text expression is enough, which is the best choice for beginners to start open source contribution. The Flink community is currently recruiting translators. The specific process of translation will also be described in detail below.

2. Preparation

  • Subscribe to mailing list
    Flink community discussions are mainly done through email, so the first step in contributing is to join the mailing list to get the latest discussion information. The main mailing lists are user mailing lists (_[email protected] & [email protected])And developer mailing lists([email protected])。 For more information about mailing lists, see https://flink.apache.org/community.html#mailing-lists_ 。 Send an email to the corresponding mailing list and reply to the confirmation message to subscribe.

E.g.If you want to subscribe to the developer mailing list, send a content free email to_[email protected]A kind of The community will reply to an email asking if you want to join, and then reply to confirm.

There are a lot of emails in Flink community every day. Effective filing can help you quickly locate relevant topics. Yunxie shared his Gmail receiving rules here_https://gist.github.com/wuchong/ad6a3bd241aca0e04eef93ae71fba73bA kind of For reference.! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

  • Focus on JIRA module
    Flink community manages all issues through JIRA, so we need to have a JIRA account before we start contributing. Although JIRA does not support focusing on a particular module, we can use JIRA filters to track the modules we are interested in.
    The operation steps are as follows
  1. Switch to the JIRA issues page and switch the search box from basic to advanced mode.
  2. Add filters that you are interested in, such as Chinese translation,component = chinese-translationAll translation related issues will be screened out,resolution = Unresolved AND assignee IN (EMPTY)On this basis, the translation tasks that are available and have not been assigned to others will be deleted. Complete filtration conditions:project = FLINK AND component = chinese-translation AND resolution = Unresolved AND assignee IN (EMPTY) ORDER BY updatedDate DESC, and then click save. In addition, you can create multiple filters according to the modules you are interested in to facilitate subsequent use.
  • At present, only the Committee in Flink community has the right to assign issue to itself, so if a contributor wants to solve it, he can leave a message under issue to apply for assignment. In general, if it is a simple typo or bugfix, the committer will assign it directly. However, if more complex changes or new feature implementations are involved, it is necessary to explain the implementation scheme at the code level when applying, and assign only after reaching an agreement with the Committee. In addition, you can click watchers on the issue page to add a follow-up. Any updates to this issue will be sent to the email address used when registering for JIRA.! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide
  • Fork Flink repository & Download Flink source code

First you need to have a GitHub account, and then open Flink’s GitHub home pagehttps://github.com/apache/flinkclickforkButton to create an image in your own private warehouse.

Then, in the local clone Flink warehouse, it is used to synchronize the master code > master codegit clone https://github.com/apache/flink.git ${your-local-dir}

Then add your own fork warehouse to submit the development branch > >git remote add ${your-repo-name} https://github.com/${your-github-id}/flink.git> > E.g.The configuration of Yunxie > Yunxiegit remote add my https://github.com/wuchong/flink.git

Start your first pull request Tour

For starters who participate in the community, translation module is usually the highest choice of “ROI”. Because it’s not only easy to use but also covers the standard contribution process, it takes you minutes to become an Apache Flink contributor. Next, we will show the complete pull request (PR) process through a Chinese translation example. But before we take off, we need to knowTranslation normsThree points are briefly summarized here

  • Translation using plain text tools
  • There should be spaces between Chinese characters and English and numbers
  • Chinese document links need to be in the corresponding English documentbaseUrlAdd afterzhAdaptation

After the completion of the above preparatory work, we will enter the exciting stage of actual combat.

Step1: apply to be an assignee of a JIRA issue. Since this is a demo task, we open the translation task that we prepared in advanceFLINK-17939 Translate “Python Table API Installation” page into ChineseAssign it to yourself (Yunxie).
! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

Step2: start work & review the content to be submitted. Note that all documents are.mdFor suffix, Chinese document name will havezhIdentifier, in the initial state, the contents of Chinese documents are all in English. We switch to the local warehouse, switch to the doc directory, find the document to be translated, and then we can start to work according to the translation specification.

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

After the translation work is completed, it is better to render locally and check the effect before submitting. The method is as follows:

Switch to the docker directory under docs and start the docker environment

cd ${your-local-dir}/flink/docs/docker

After that, it takes 1 to 2 minutes to compile the local document

./build docs.sh -p

Then open itlocalhost:4000After switching to the Chinese version, you can check the rendered document, such as the typesetting format and whether the hyperlinks in the page can be opened normally, etc. after confirmation, the document can be submitted. Note: do Chinese adaptation for hyperlinks to other documents.

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

Step3: preparation for submission phase. The best practice is to create a branch for commit and commit changes to that branch. For example, here we create ainstallation-translateBranch and switch over.

git checkout -b installation-translate

Flink community has certain requirements on the format of commit message, which is generally
[${jira-issue-id}][${affected-component}] ${jira-issue-title}

Take demo as an example[FLINK-17939][docs-zh] Translate "Python Table API Installation" page into Chinese

After the local submission, you can push the changes to the remote private warehouse of your fork by using the following command.

git push my installation-translate

Step4: prepare pr. After pushing the changes to its fork’s remote repository, GitHub automatically creates a new PR and returns a link to the PR page[https://github.com/apache/flink/pull/12343](https://github.com/apache/flink/pull/12343)On this basis, the following information needs to be filled in to facilitate the reviewer to quickly understand the PR to be reviewed and improve the merger efficiency.

  • What is the purpose of the change
  • Generally speaking, it can be described by JIRA issue description
  • Brief change log (what changes have been made to the commits involved in PR)
    Fill in this as needed. For example, you can write translate for translation tasksflink/docs/dve/table/python/installation.zh.md。 If it is a more complex change involving multiple commits, it is better to briefly summarize the contents of each submission according to the order of submission, and attach the commit log link.

The last three are multiple-choice questions, which can be checked as required:

  • Verifying this change
  • Does this pull request potentially affect one of the following parts
  • Documentation (does the change require a new document)

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

Step5: wait for the committee review. When you refresh the JIRA page, you can usually see the PR update on issue links. Generally speaking, the Committee assigned to us by JIRA issue will check whether there is a PR of the module that he is concerned about. Occasionally, when the committee is very busy, you can also @ a certain committee in the PR to help review the submission. Usually, the committer will give some comments, and the committer will reply, and sometimes it may be necessary to make changes & submit again. It should be noted that the Flink community does not recommend using itgit squashMerge and compress multiple commits, because this will lose the history of changes. It is recommended that the modifications be directly appended to the original commits. Sometimes this step can be repeated several times & with multiple committers involved until the committers and the committers agree. For a contributor, the whole PR is finished at this stage. Subsequent committers will merge it into the master branch and close pr.

To summarize briefly, for a contributor, the steps to complete the PR submission are as follows.

Step 1: claim the issue you are interested in on JIRA, and ask the committee to assign it to yourself.
Step 2: complete the issue task and check before submission.
Step 3: fill in the commit information according to the specification and submit it to the remote private warehouse.
Step 4: fill in the PR information according to the specification and wait for the committee review.
Step 5: deal with the comments of the committee, sometimes including modifying the code, and repeat this step until the members agree that the change is OK.

Congratulations on becoming a Flink contributor! Each release announcement of Flink will have a list of contributors to list all contributors. Meanwhile, the GitHub contributor page will list the list of top 100 contributors in history.

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

How to be an excellent contributor

Submitting the first PR is only the first step in the long march. How to be an excellent contributor or even a committer? Here are three tips that might help you.

1. Actively participate in users’ Q & A

! image.png ](/ img / bvchqgd) code! Flink contributor Quick Guide

Flink community encourages more people to participate in the user’s mailing list. Apache financial report in 2019 shows that Flink community ranks first in mailing list activity. Every month, the community counts the contributors who actively answer questions in each mailing list and looks for potential contributors from these active contributors.

2. Code quality wins community trust

For code contributors, the best practice is:

  • followCode style specification, configure in ideacheckstyle.xmlCheck at any time to avoid low-level problems such as nonstandard style in PR.
  • Carefully fill in the PR description template, especially the “brief change log” section, for referencehttps://github.com/apache/flink/pull/7264A kind of andhttps://github.com/apache/flink/pull/10013_
  • Any new features should have test coverage, which tends to be unit testing rather than integration testing.
  • Any new functions should be synchronized to cover documents, and both Chinese and English documents need to be updated or issue created.
  • Pay attention to the test results of azure lab.

3. Have a sense of community

Finally, the title of contributor or committee not only brings us “professional aura”, but also brings a sense of responsibility and helps the community to become better from the bottom of my heart. For example, we can help new people become contributors and review new pr(Review guide)Wait.

Finally, I would like to borrow the classic line “it is the time you wasted on your rose that makes your rose important.”.

Link to original text
This article is the original content of Alibaba cloud and can not be reproduced without permission.

Recommended Today

DK7 switch’s support for string

Before JDK7, switch can only support byte, short, char, int or their corresponding encapsulation classes and enum types. After JDK7, switch supports string type. In the switch statement, the value of the expression cannot be null, otherwise NullPointerException will be thrown at runtime. Null cannot be used in the case clause, otherwise compilation errors will […]