This is an automated email from the ASF dual-hosted git repository.
benjobs pushed a commit to branch dev
in repository
https://gitbox.apache.org/repos/asf/incubator-streampark-website.git
The following commit(s) were added to refs/heads/dev by this push:
new 03a1bd8 improve contribution guide (#398)
03a1bd8 is described below
commit 03a1bd81e772f02aad47f5b50c958abd3ecbe42c
Author: xiangzihao <[email protected]>
AuthorDate: Thu Jul 25 23:35:58 2024 +0800
improve contribution guide (#398)
Co-authored-by: sbloodys <[email protected]>
---
community/contribution_guide/SP-License.md | 39 +++++++++++
community/contribution_guide/SPIP.md | 92 +++++++++++++++++++++++++
community/contribution_guide/commit-message.md | 94 ++++++++++++++++++++++++++
community/contribution_guide/contribute.md | 40 +++++++++++
community/contribution_guide/document.md | 15 ++++
community/contribution_guide/e2e-guide.md | 13 ++++
community/contribution_guide/pull-request.md | 93 +++++++++++++++++++++++++
7 files changed, 386 insertions(+)
diff --git a/community/contribution_guide/SP-License.md
b/community/contribution_guide/SP-License.md
new file mode 100644
index 0000000..c9b4bb3
--- /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 [email protected]
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 0000000..4c2260d
--- /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
[[email protected]][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
[[email protected]][mail-to-dev].
+Describe the purpose, and the draft design about your idea.
+
+Here is the template for mail
+
+- Title: `[DISCUSS][SPIP-XXX] <CHANGE-TO-YOUR-LOVELY-PROPOSAL-TITLE>`, change
`XXX` to special integer you just change in
+ [GitHub Issue](#create-github-issue), and also change proposal title.
+- Content:
+
+ ```text
+ Hi community,
+
+ <CHANGE-TO-YOUR-PROPOSAL-DETAIL>
+
+ I already add a GitHub Issue for my proposal, which you could see in
<CHANGE-TO-YOUR-GITHUB-ISSUE-LINK>.
+
+ 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:[email protected]
+[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 0000000..952232d
--- /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 [...]
+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 0000000..3c1e230
--- /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 0000000..8ed5982
--- /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/<your-github-user-name>/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 0000000..ecb3202
--- /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 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 0000000..90bdfde
--- /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
+<table>
+ <thead>
+ <tr>
+ <th style="width: 10%; text-align: center;">Issue Type</th>
+ <th style="width: 20%; text-align: center;">Pull Request Type</th>
+ <th style="width: 20%; text-align: center;">Example(Suppose Issue
No is 3333)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td style="text-align: center;">Feature</td>
+ <td style="text-align: center;">Feature</td>
+ <td style="text-align: center;">[Feature-3333][server] Implement
xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">Bug</td>
+ <td style="text-align: center;">Fix</td>
+ <td style="text-align: center;">[Fix-3333][ui] Fix xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">Improvement</td>
+ <td style="text-align: center;">Improvement</td>
+ <td style="text-align: center;">[Improvement-3333][alert] Improve
the performance of xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">Test</td>
+ <td style="text-align: center;">Test</td>
+ <td style="text-align: center;">[Test-3333][api] Add the e2e test
of xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">Doc</td>
+ <td style="text-align: center;">Doc</td>
+ <td style="text-align: center;">[Doc-3333] Improve xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">E2E</td>
+ <td style="text-align: center;">E2E</td>
+ <td style="text-align: center;">[E2E-3333] Implement xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">CI</td>
+ <td style="text-align: center;">CI</td>
+ <td style="text-align: center;">[CI] Improve xxx</td>
+ </tr>
+ <tr>
+ <td style="text-align: center;">Chore</td>
+ <td style="text-align: center;">Chore</td>
+ <td style="text-align: center;">[Chore] Improve xxx</td>
+ </tr>
+ </tbody>
+</table>
+```
+
+`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.
