Skip to content

Commit f86cd75

Browse files
caozhen1937caozhen1937
committed
[docs] Fill out Contribute Code doc
1 parent 8b10719 commit f86cd75

File tree

1 file changed

+198
-1
lines changed

1 file changed

+198
-1
lines changed

‎website/community/how-to-contribute/contribute-code.md‎

Lines changed: 198 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,204 @@ sidebar_position: 1
55

66
# Contribute Code
77

8-
TODO
8+
Fluss is maintained, improved, and extended by code contributions of volunteers. We welcome contributions to Fluss, but due to preserve the high quality of the code base, we follow a contribution process that is explained in this document.
99

10+
IMPORTANT: Please read this document carefully before starting to work on a code contribution. Follow the process and guidelines explained below. Contributing to Fluss does not start with opening a pull request. We expect contributors to reach out to us first to discuss the overall approach together. Without consensus with the Fluss committers, contributions might require substantial rework or will not be reviewed.
11+
12+
## Looking for what to contribute
13+
14+
- If you have a good idea for the contribution, you can proceed to [the code contribution process](#code-contribution-process).
15+
- If you are looking for what you could contribute, you can browse [open issues](https://github.com/alibaba/fluss/issues), which are not assigned, and then follow [the code contribution process](#code-contribution-process).
16+
- If you are very new to the Fluss project and ready to tackle some open issues, we've collected some [good first issues](https://github.com/alibaba/fluss/contribute) for you.
17+
18+
19+
## Code Contribution Process
20+
21+
22+
<style>
23+
.contribute-grid {
24+
margin-bottom: 10px;
25+
display: flex;
26+
flex-direction: column;
27+
margin-left: -2px;
28+
margin-right: -2px;
29+
}
30+
31+
.contribute-grid .column {
32+
margin-top: 4px;
33+
padding: 0 2px;
34+
}
35+
36+
@media only screen and (min-width: 480px) {
37+
.contribute-grid {
38+
flex-direction: row;
39+
flex-wrap: wrap;
40+
}
41+
42+
.contribute-grid .column {
43+
flex: 0 0 50%;
44+
}
45+
46+
.contribute-grid .column {
47+
margin-top: 4px;
48+
}
49+
}
50+
51+
@media only screen and (min-width: 960px) {
52+
.contribute-grid {
53+
flex-wrap: nowrap;
54+
}
55+
56+
.contribute-grid .column {
57+
flex: 0 0 25%;
58+
}
59+
}
60+
61+
.contribute-grid .panel {
62+
height: 100%;
63+
margin: 0;
64+
}
65+
66+
.contribute-grid .panel-body {
67+
padding: 10px;
68+
}
69+
70+
.contribute-grid h2 {
71+
margin: 0 0 10px 0;
72+
padding: 0;
73+
display: flex;
74+
align-items: flex-start;
75+
}
76+
77+
.contribute-grid .number {
78+
margin-right: 0.25em;
79+
font-size: 1.5em;
80+
line-height: 0.9;
81+
}
82+
</style>
83+
84+
<div class="contribute-grid">
85+
<div class="column">
86+
<div class="panel panel-default">
87+
<div class="panel-body">
88+
<h2><span class="number">1</span><a href="#consensus">Discuss</a></h2>
89+
<p>Create an issue and reach consensus</p>
90+
<p><b>To request an issue, please note that it is not just a "please assign it to me", you need to explain your understanding of the issue, and your design, and if possible, you need to provide your POC code.</b></p>
91+
</div>
92+
</div>
93+
</div>
94+
<div class="column">
95+
<div class="panel panel-default">
96+
<div class="panel-body">
97+
<h2><span class="number">2</span><a href="#implement">Implement</a></h2>
98+
<p>Implement the change according to the Code Style and Quality(refer to the <a href="https://flink.apache.org/how-to-contribute/code-style-and-quality-preamble/">Flink doc</a>) Guide and the approach agreed upon in the issue.</p>
99+
<p><b>Only start working on the implementation if there is consensus on the approach (e.g. you are assigned to the ticket)</b></p>
100+
</div>
101+
</div>
102+
</div>
103+
<div class="column">
104+
<div class="panel panel-default">
105+
<div class="panel-body">
106+
<h2><span class="number">3</span><a href="#review">Review</a></h2>
107+
<p>Create the pull request and work with the reviewer.</p><br />
108+
<p><b>1.Make sure no unrelated or unnecessary reformatting changes are included. 2.Please ensure that the test passing. 3.Please don't resolve conversation.</b></p>
109+
</div>
110+
</div>
111+
</div>
112+
<div class="column">
113+
<div class="panel panel-default">
114+
<div class="panel-body">
115+
<h2><span class="number">4</span><a href="#merge">Merge</a></h2>
116+
<p>A committer of Fluss checks if the contribution fulfills the requirements and merges the code to the codebase.</p>
117+
</div>
118+
</div>
119+
</div>
120+
</div>
121+
122+
123+
### Pull Request Guide
124+
125+
#### Before PR Checklist
126+
127+
- Make sure that the pull request corresponds to a [GitHub issue](https://github.com/alibaba/fluss/issues). Exceptions are made for typos in JavaDoc or documentation files, which need no issue.
128+
129+
- Name the pull request in the format "[component] Title of the pull request", where *[component]* should be replaced by the name of the component being changed. Typically, this corresponds to the component label assigned to the issue (e.g., [kv], [log], [client], [flink]). Skip *[component]* if you are unsure about which is the best component. **Hotfixes** should be named for example `[hotfix][docs] Expand JavaDoc for PuncuatedWatermarkGenerator`.
130+
131+
- Fill out the PR template to describe the changes contributed by the pull request. Please describe it such that the reviewer understands the problem and solution from the description, not only from the code. That will give reviewers the context they need to do the review.
132+
133+
- Make sure that the change passes the automated tests, i.e., `mvn clean verify` passes.
134+
135+
- Each pull request should address only one issue, not mix up code from multiple issues.
136+
137+
#### How to debug failed cases?
138+
139+
140+
141+
### Code Review Guide
142+
143+
Every review needs to check the following six aspects. **We encourage to check these aspects in order, to avoid
144+
spending time on detailed code quality reviews when formal requirements are not met or there is no consensus in
145+
the community to accept the change.**
146+
147+
### 1. Is the Contribution Well-Described?
148+
149+
Check whether the contribution is sufficiently well-described to support a good review. Trivial changes and fixes
150+
do not need a long description. If the implementation is exactly according to a prior discussion on issue or the
151+
development mailing list, only a short reference to that discussion is needed.
152+
153+
If the implementation is different from the agreed approach in the consensus discussion, a detailed description of
154+
the implementation is required for any further review of the contribution.
155+
156+
### 2. Does the Contribution Need Attention from some Specific Committers?
157+
158+
Some changes require attention and approval from specific committers.
159+
160+
If the pull request needs specific attention, one of the tagged committers/contributors should give the final approval.
161+
162+
### 3. Is the Overall Code Quality Good, Meeting Standard we Want to Maintain in Fluss?
163+
164+
- Does the code follow the right software engineering practices? Is the code correct, robust, maintainable, testable?
165+
- Are the changes performance aware, when changing a performance sensitive part?
166+
- Are the changes sufficiently covered by tests? Are the tests executing fast?
167+
- If dependencies have been changed, were the NOTICE files updated?
168+
169+
Code guidelines can be found in the [Flink Java Code Style and Quality Guide](https://flink.apache.org/how-to-contribute/code-style-and-quality-java/).
170+
171+
### 4. Are the documentation updated?
172+
173+
If the pull request introduces a new feature, the feature should be documented.
174+
175+
## Become a Committer
176+
177+
### How to become a committer
178+
179+
There is no strict protocol for becoming a committer. Candidates for new committers are typically people that are
180+
active contributors and community members. Candidates are suggested by current committers or PPMC members, and
181+
voted upon by the PPMC.
182+
183+
If you would like to become a committer, you should engage with the community and start contributing to Fluss in
184+
any of the above ways. You might also want to talk to other committers and ask for their advice and guidance.
185+
186+
- Community contributions include helping to answer user questions on the mailing list, verifying release candidates,
187+
giving talks, organizing community events, and other forms of evangelism and community building. The "Apache Way" has
188+
a strong focus on the project community, and committers can be recognized for outstanding community contributions even
189+
without any code contributions.
190+
191+
- Code/technology contributions include contributed pull requests (patches), design discussions, reviews, testing,
192+
and other help in identifying and fixing bugs. Especially constructive and high quality design discussions, as well
193+
as helping other contributors, are strong indicators.
194+
195+
#### Identify promising candidates
196+
197+
While the prior points give ways to identify promising candidates, the following are "must haves" for any committer candidate:
198+
199+
- Being community minded: The candidate understands the meritocratic principles of community management. They do not
200+
always optimize for as much as possible personal contribution, but will help and empower others where it makes sense.
201+
202+
- We trust that a committer candidate will use their write access to the repositories responsibly, and if in doubt,
203+
conservatively. It is important that committers are aware of what they know and what they don't know. In doubt,
204+
committers should ask for a second pair of eyes rather than commit to parts that they are not well familiar with.
205+
206+
- They have shown to be respectful towards other community members and constructive in discussions.
10207

11208

0 commit comments

Comments
 (0)