diff --git a/community/contribution_guide/SP-License.md b/community/contribution_guide/SP-License.md new file mode 100644 index 000000000..c9b4bb39a --- /dev/null +++ b/community/contribution_guide/SP-License.md @@ -0,0 +1,39 @@ +# License Notice + +As we know that StreamPark is an open-source undergoing project at The Apache Software Foundation (ASF), which means that you have to follow the Apache way to become the StreamPark contributor. Furthermore, Apache has extremely strict rules according to the License. This passage will explain the ASF license and how to avoid License risks at the early stage when you participate in StreamPark. + +Note: This article only applies to the Apache projects. + +### Licenses Could be Accepted to the Apache Project + +You have to pay attention to the following open-source software protocols which Apache projects support when you intend to add a new feature to the StreamPark (or other Apache projects), which functions refers to other open-source software references. + +[ASF 3RD PARTY LICENSE POLICY](https://apache.org/legal/resolved.html) + +If the 3rd party software is not present at the above policy, we are sorry that your code can not pass the audit and we suggest searching for other substitute plans. + +Besides, when you demand new dependencies in the project, please email us about the reason and the outcome of the influence to dev@StreamPark.apache.org to discuss. Besides, you need at least 3 positive votes from the PPMC to finish the whole step. + +### How to Legally Use 3rd Party Open-source Software in the StreamPark + +Moreover, when we intend to refer a new software ( not limited to 3rd party jar, text, CSS, js, pics, icons, audios etc and modifications based on 3rd party files) to our project, we need to use them legally in addition to the permission of ASF. Refer to the following article: + +* [COMMUNITY-LED DEVELOPMENT "THE APACHE WAY"](https://apache.org/dev/licensing-howto.html) + +For example, we should contain the NOTICE file (every open-source project has NOTICE file, generally under root directory) of ZooKeeper in our project when we are using ZooKeeper. As the Apache explains, "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work. + +We are not going to dive into every 3rd party open-source license policy, you may look up them if interested. + +### StreamPark-License Check Rules + +In general, we would have our License-check scripts to our project. StreamPark-License is differ a bit from other open-source projects. All in all, we are trying to make sure avoiding the license issues at the first time. + +We need to follow the following steps when we need to add new jars or external resources: + +* Add the name and the version of the jar file in the `tools/dependencies/known-dependencies.txt` + +### References + +* [COMMUNITY-LED DEVELOPMENT "THE APACHE WAY"](https://apache.org/dev/licensing-howto.html) +* [ASF 3RD PARTY LICENSE POLICY](https://apache.org/legal/resolved.html) + diff --git a/community/contribution_guide/SPIP.md b/community/contribution_guide/SPIP.md new file mode 100644 index 000000000..4c2260dd2 --- /dev/null +++ b/community/contribution_guide/SPIP.md @@ -0,0 +1,92 @@ +# SPIP + +StreamPark Improvement Proposal(SPIP) introduce major improvements to the Apache StreamPark codebase. It is +not for small incremental improvements, and the purpose of SPIP is to notice and inform community the finished or coming +big feature for Apache StreamPark. + +## What is considered as SPIP + +- Any major new feature, major improvement, introduce or remove components +- Any major change of public interfaces, such as API endpoints, web ui huge change + +When the change in doubt and any committer thinks it should be SPIP, it does. + +We use GitHub Issue and Apache mail thread to record and hold SPIP, for more detail you could go to section +[current SPIPs](#current-SPIPs) and [past SPIPs](#past-SPIPs). + +As a SPIP, it should: + +- Have a mail thread title started with `[DISCUSS]` in [dev@streampark.apache.org][mail-to-dev] +- Have a GitHub Issue labeled with `SPIP`, and including the mail thread link in the description. + +### Current SPIPs + +Current SPIPs including all SPIP still work-in-progress, you could see in [current SPIPs][current-SPIPs] + +### Past SPIPs + +Past SPIPs including all SPIP already done or retired for some reason, you could see in [past SPIPs][past-SPIPs] + +## SPIP Process + +### Create GitHub Issue + +All SPIP should start with GitHub Issue + +- If you pretty sure your issue is SPIP, you could click and choose "SPIP" in + [GitHub Issue][github-issue-choose] +- If you not sure about your issue is SPIP or not, you could click and choose "Feature request" in + [GitHub Issue][github-issue-choose]. StreamPark maintainer team would add label `SPIP`, mention you in the + issue and lead you to this document when they think it should be SPIP. + +You should add special prefix `[SPIP-XXX]`, `XXX` stand for the id SPIP. It's auto increment, and you could find the next +integer in [All SPIPs][all-SPIPs] issues. + +### Send Discuss Mail + +After issue labeled with "SPIP", you should send an email to [dev@streampark.apache.org][mail-to-dev]. +Describe the purpose, and the draft design about your idea. + +Here is the template for mail + +- Title: `[DISCUSS][SPIP-XXX] `, change `XXX` to special integer you just change in + [GitHub Issue](#create-github-issue), and also change proposal title. +- Content: + + ```text + Hi community, + + + + I already add a GitHub Issue for my proposal, which you could see in . + + Looking forward any feedback for this thread. + ``` + +After community discuss and all of them think it worth as SPIP, you could [work on it](#work-on-it-or-create-subtask-for-it). +But if community think it should not be SPIP or even this change should not be included to StreamPark, maintainers +terminate mail thread and remove label "SPIP" for GitHub Issue, or even close issue if it should not change. + +### Work On It, Or Create Subtask For It + +When your proposal pass in the mail thread, you could make your hand dirty and start the work. You could submit related +pull requests in GitHub if change should in one single commit. What's more, if proposal is too huge in single commit, you +could create subtasks in GitHub Issue like [SPIP-1][SPIP-1], and separate into multiple commit. + +### Close After It Done + +When SPIP is finished and all related PR were merged, you should reply the mail thread you created in +[step two](#send-discuss-mail) to notice community the result of the SPIP. After that, this SPIP GitHub Issue would be +closed and transfer from [current SPIPs][current-SPIPs] to [past SPIPs][past-SPIPs], but you could still find it in [All SPIPs][all-SPIPs] + +## An Example For SPIP + +* [[SPIP-1][Feature][Parent] Suggest add HA for StreamPark][SPIP-1]: Have multiple subtasks and Projects on it. + +[all-SPIPs]: https://github.com/apache/incubator-streampark/issues?q=is%3Aissue+label%3A%22SPIP%22+ +[current-SPIPs]: https://github.com/apache/incubator-streampark/issues?q=is%3Aissue+is%3Aopen+label%3A%22SPIP%22 +[past-SPIPs]: https://github.com/apache/incubator-streampark/issues?q=is%3Aissue+is%3Aclosed+label%3A%22SPIP%22+ +[github-issue-choose]: https://github.com/apache/incubator-streampark/issues/new/choose +[mail-to-dev]: mailto:dev@streampark.apache.org +[SPIP-1]: https://github.com/apache/incubator-streampark/issues/3905 + diff --git a/community/contribution_guide/commit-message.md b/community/contribution_guide/commit-message.md new file mode 100644 index 000000000..952232d8c --- /dev/null +++ b/community/contribution_guide/commit-message.md @@ -0,0 +1,94 @@ +# Commit Message Notice + +### Preface + +A good commit message can help other developers (or future developers) quickly understand the context of related changes, and can also help project managers determine whether the commit is suitable for inclusion in the release. But when we checked the commit logs of many open source projects, we found an interesting problem. Some developers have very good code quality, but the commit message record is rather confusing. When other contributors or learners are viewing the code, it can’t be intuitively understood through commit log. +The purpose of the changes before and after the submission, as Peter Hutterer said：Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it as much as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator. Therefore, StreamPark developed the protocol in conjunction with other communities and official Apache documents. + +### Commit Message RIP + +#### 1：Clearly modify the content + +A commit message should clearly state what issues (bug fixes, function enhancements, etc.) the submission solves, so that other developers can better track the issues and clarify the optimization during the version iteration process. + +#### 2：Associate the corresponding Pull Request or Issue + +When our changes are large, the commit message should best be associated with the relevant Issue or Pull Request on GitHub, so that our developers can quickly understand the context of the code submission through the associated information when reviewing the code. If the current commit is for an issue, then the issue can be closed in the Footer section. + +#### 3：Unified format + +The formatted CommitMessage can help provide more historical information for quick browsing, and it can also generate a Change Log directly from commit. + +Commit message should include three parts: Header, Body and Footer. Among them, Header is required, Body and Footer can be omitted. + +##### Header + +The header part has only one line, including three fields: type (required), scope (optional), and subject (required). + +[SP-ISSUE number][type] subject + +(1) Type is used to indicate the category of commit, and only the following 7 types are allowed. + +- feat：features +- fix：Bug fixes +- docs：Documentation +- style： Format (does not affect changes in code operation) +- refactor：Refactoring (It is not a new feature or a code change to fix a bug) +- test：Add test +- chore：Changes in the build process or auxiliary tools + +If the type is feat and fix, the commit will definitely appear in the change log. Other types (docs, chore, style, refactor, test) are not recommended. + +(2) Scope + +Scope is used to indicate the scope of commit impact, such as server, remote, etc. If there is no suitable scope, you can use \*. + +(3) subject + +Subject is a short description of the purpose of the commit, no more than 50 characters. + +##### Body + +The body part is a detailed description of this commit, which can be divided into multiple lines, and the line break will wrap with 72 characters to avoid automatic line wrapping affecting the appearance. + +Note the following points in the Body section: + +- Use the verb-object structure, note the use of present tense. For example, use change instead of changed or changes + +- Don't capitalize the first letter + +- The end of the sentence does not need a ‘.’ (period) + +##### Footer + +Footer only works in two situations + +(1) Incompatible changes + +If the current code is not compatible with the previous version, the Footer part starts with BREAKING CHANGE, followed by a description of the change, the reason for the change, and the migration method. + +(2) Close Issue + +If the current commit is for a certain issue, you can close the issue in the Footer section, or close multiple issues at once. + +##### For Example + +``` +[Fix-0001][docs-en] add commit message + +- commit message RIP +- build some conventions +- help the commit messages become clean and tidy +- help developers and release managers better track issues + and clarify the optimization in the version iteration + +This closes #0001 +``` + +### Reference documents + +[Commit message format](https://cwiki.apache.org/confluence/display/GEODE/Commit+Message+Format) + +[On commit messages-Peter Hutterer](http://who-t.blogspot.com/2009/12/on-commit-messages.html) + +[RocketMQ Community Operation Conventions](https://mp.weixin.qq.com/s/LKM4IXAY-7dKhTzGu5-oug) diff --git a/community/contribution_guide/contribute.md b/community/contribution_guide/contribute.md new file mode 100644 index 000000000..3c1e2306e --- /dev/null +++ b/community/contribution_guide/contribute.md @@ -0,0 +1,40 @@ +# Participate in Contributing + +First of all, thank you very much for choosing and using StreamPark, and welcome to join the StreamPark family! + +We encourage any form of participation in the community that will eventually become Committer or PPMC Such as: +* Problems will be encountered via github on the [issue](https://github.com/apache/incubator-streampark/issues) form feedback out. +* Answer the issue questions that others are asking. +* Help improve the documentation. +* Help your project add test cases. +* Add comments to the code. +* Submit a PR that fixes the bug or Feature. +* Publish application case practice, scheduling process analysis, or technical articles related to scheduling. +* Help promote StreamPark, participate in technical conferences or meetup, sharing and more. + +Welcome to the contributing team and join open source starting with submitting your first PR. +- For example, add code comments or find `good first issue` tags or some very simple issue (misspellings, etc.) and so on, first familiarize yourself with the submission process through the first simple PR. + +Note: Contributions are not limited to PR Only, but contribute to the development of the project. + +I'm sure you'll benefit from open source by participating in StreamPark! + +### 1. Participate in documentation contributions. + +Refer to the [Submit Guide-Document Notice](./document.md) + +### 2. Participate in code contributions. + +Refer to the [Submit Guide-Pull Request Notice](./pull-request.md), [Submit Guide-Commit Message Notice](./commit-message.md) + +### 3. How to pick up an Issue and submit a Pull Request. + +If you want to implement a Feature or fix a Bug. Please refer to the following: + +* All bugs and the features are recommended and managed using the GitHub issues(https://github.com/apache/incubator-streampark/issues). +* If you want to develop a Feature, first reply to the Issue associated with that feature, indicating that you are currently working on it. And set yourself a "deadline" when to Submit the Feature, and add it in the reply comment. +* It's a good idea to find a mentor (or an instructor) in the core contributors who gives immediate feedback on design and functional implementation. +* You should create a new branch to start your work, to get the name of the branch refer to the [Submit Guide-Pull Request Notice](./pull-request.md). For example, if you want to complete the feature and submit Issue 111, your branch name should be feature-111. The feature name can be determined after discussion with the instructor. +* When you're done, send a Pull Request to StreamPark. + +If you want to submit a Pull Request to complete a Feature or fix a Bug, it is recommended that you start with the `good first issue` issues, complete a small function to submit, do not change too many files at a time, changing too many files will also put a lot of pressure on Reviewers, it is recommended to submit them through multiple Pull Requests, not all at once. diff --git a/community/contribution_guide/document.md b/community/contribution_guide/document.md new file mode 100644 index 000000000..8ed59823a --- /dev/null +++ b/community/contribution_guide/document.md @@ -0,0 +1,15 @@ +# Documentation Notice + +Good documentation is critical for any type of software. Any contribution that can improve the StreamPark documentation is welcome. + +### Get the document project + +Documentation for the StreamPark project is maintained in a separate [git repository](https://github.com/apache/incubator-streampark-website). + +First you need to fork the document project into your own github repository, and then clone the document to your local computer. + +``` +git clone https://github.com//incubator-streampark-website +``` + +For more information on how to develop document locally, please refer to the [documentation contribution guide](https://github.com/apache/incubator-streampark-website/blob/dev/README.md) diff --git a/community/contribution_guide/e2e-guide.md b/community/contribution_guide/e2e-guide.md new file mode 100644 index 000000000..ecb320227 --- /dev/null +++ b/community/contribution_guide/e2e-guide.md @@ -0,0 +1,13 @@ +# E2E Test Contribution Guide + +The main purpose of E2E test is to verify the integration and data integrity of the system, and its components, by simulating real user scenarios. This makes it possible to extend the scope of testing and ensure the health and stability of the system. To a certain extent, the test workload and costs are reduced. In simple terms, E2E testing is about treating a program as a black box and simulating the access behaviour of a real system from the user's point of view to see if the input to the test (user behaviour/simulated data) gives the expected results. Therefore, the community decided to add E2E automated testing to StreamPark. + +The current community E2E test has not yet reached full coverage, so this document has been written with the aim of guiding more partners to get involved. + +### How to find the corresponding ISSUE? + +The E2E test pages are currently divided into four pages: Project Management, Resource Center, DataSource, and Security Center. + +Contributors can find the task by going to GitHub, searching for [apache/incubator-streampark](https://github.com/apache/incubator-streampark), and then searching for `e2e` in the [issue list](https://github.com/apache/incubator-streampark/issues?q=is%3Aissue+is%3Aopen+e2e). As shown below. + +For more information on e2e development, please refer to the [E2E](https://github.com/apache/incubator-streampark/blob/dev/streampark-e2e/README.md). diff --git a/community/contribution_guide/pull-request.md b/community/contribution_guide/pull-request.md new file mode 100644 index 000000000..90bdfde47 --- /dev/null +++ b/community/contribution_guide/pull-request.md @@ -0,0 +1,93 @@ +# Pull Request Notice + +## Preface + +Pull Request is a way of software cooperation, which is a process of bringing code involving different functions into the trunk. During this process, the code can be discussed, reviewed, and modified. + +In Pull Request, we try not to discuss the implementation of the code. The general implementation of the code and its logic should be determined in Issue. In the Pull Request, we only focus on the code format and code specification, so as to avoid wasting time caused by different opinions on implementation. + +## Specification + +### Pull Request Title + +Title Format: [`Pull Request Type`-`Issue No`][`Module Name`] `Pull Request Description` + +The corresponding relationship between `Pull Request Type` and `Issue Type` is as follows: +```javascript + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Issue TypePull Request TypeExample(Suppose Issue No is 3333)
FeatureFeature[Feature-3333][server] Implement xxx
BugFix[Fix-3333][ui] Fix xxx
ImprovementImprovement[Improvement-3333][alert] Improve the performance of xxx
TestTest[Test-3333][api] Add the e2e test of xxx
DocDoc[Doc-3333] Improve xxx
E2EE2E[E2E-3333] Implement xxx
CICI[CI] Improve xxx
ChoreChore[Chore] Improve xxx
+``` + +`Issue No` refers to the Issue number corresponding to the current Pull Request to be resolved, `Module Name` is the same as the `Module Name` of Issue. + +### Pull Request Branch + +Branch name format: `Pull Request type`-`Issue number`. e.g. Feature-3333 + +### Pull Request Content + +Please refer to the commit message section. + +### Pull Request Code Style + +StreamPark uses `Spotless` to automatically fix code style and formatting errors, + +### Question + +- How to deal with one Pull Request to many Issues scenario. + + First of all, there are fewer scenarios for one Pull Request to many Issues. + The root cause is that multiple issues need to do the same thing. + Usually, there are two solutions to this scenario: the first is to merge multiple issues with into the same issue, and then close the other issues; + the second is multiple issues have subtle differences. + In this scenario, the responsibilities of each issue can be clearly divided. The type of each issue is marked as Sub-Task, and then these sub task type issues are associated with one issue. + And each Pull Request is submitted should be associated with only one issue of a sub task.