Skip to content

Commit bf430f5

Browse files
authored
docs: standardize development docs (#480)
1 parent 0ca9445 commit bf430f5

File tree

8 files changed

+448
-479
lines changed

8 files changed

+448
-479
lines changed

src/Development/stage/Committer.md

Lines changed: 16 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,19 @@
11
<!--
2-
3-
Licensed to the Apache Software Foundation (ASF) under one
4-
or more contributor license agreements. See the NOTICE file
5-
distributed with this work for additional information
6-
regarding copyright ownership. The ASF licenses this file
7-
to you under the Apache License, Version 2.0 (the
8-
"License"); you may not use this file except in compliance
9-
with the License. You may obtain a copy of the License at
10-
11-
http://www.apache.org/licenses/LICENSE-2.0
12-
13-
Unless required by applicable law or agreed to in writing,
14-
software distributed under the License is distributed on an
15-
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16-
KIND, either express or implied. See the License for the
17-
specific language governing permissions and limitations
18-
under the License.
19-
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
2017
-->
2118

2219
# Become a Committer
@@ -73,5 +70,4 @@ See the [ASF documentation](https://www.apache.org/dev/committers.html#committer
7370
- They accept and integrate feedback on their code
7471
- They know, follow, and enforce IoTDB's practices while reviewing/merging code - style, documentation, testing, backward compatibility, etc.
7572

76-
77-
The code of conduct is derived from [Apache Beam](https://beam.apache.org/contribute/become-a-committer/).
73+
The code of conduct is derived from [Apache Beam](https://beam.apache.org/contribute/become-a-committer/).

src/Development/stage/ContributeGuide.md

Lines changed: 91 additions & 97 deletions
Large diffs are not rendered by default.
Lines changed: 56 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,22 @@
11
<!--
2-
3-
Licensed to the Apache Software Foundation (ASF) under one
4-
or more contributor license agreements. See the NOTICE file
5-
distributed with this work for additional information
6-
regarding copyright ownership. The ASF licenses this file
7-
to you under the Apache License, Version 2.0 (the
8-
"License"); you may not use this file except in compliance
9-
with the License. You may obtain a copy of the License at
10-
11-
http://www.apache.org/licenses/LICENSE-2.0
12-
13-
Unless required by applicable law or agreed to in writing,
14-
software distributed under the License is distributed on an
15-
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16-
KIND, either express or implied. See the License for the
17-
specific language governing permissions and limitations
18-
under the License.
19-
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
2017
-->
2118

22-
# Howto Submit Code
19+
# How to Submit Code
2320

2421
## Contribution
2522

@@ -43,7 +40,7 @@ Visit the apache/iotdb project’s [github page](https://github.com/apache/iotdb
4340

4441
- Clone the source code to local machine:
4542

46-
```
43+
```bash
4744
git clone https://github.com/<your_github_name>/iotdb.git
4845
```
4946

@@ -53,32 +50,32 @@ After the clone is done, the origin remote will point to the default branch of t
5350

5451
- add apache/iotdb as upstream remote:
5552

56-
```
53+
```bash
5754
cd iotdb
5855
git remote add upstream https://github.com/apache/iotdb.git
5956
```
6057

6158
- Check the local repository’s remotes
6259

63-
```
60+
```bash
6461
git remote -v
6562
origin https://github.com/<your_github_name>/iotdb.git (fetch)
6663
origin https://github.com/<your_github_name>/iotdb.git(push)
6764
upstream https://github.com/apache/iotdb.git (fetch)
6865
upstream https://github.com/apache/iotdb.git (push)
6966
```
7067

71-
- Create a new branch to start working(e.g. fix)
68+
- Create a new branch to start working. (e.g. fix)
7269

73-
```
70+
```bash
7471
git checkout -b fix
7572
```
7673

7774
You can make code changes after creation.
7875

79-
- Push the changes to a remote repository(e.g. fix)
76+
- Push the changes to a remote repository. (e.g. fix)
8077

81-
```
78+
```bash
8279
git commit -a -m "<you_commit_message>"
8380
git push origin fix
8481
```
@@ -91,67 +88,67 @@ When submitting code on git, you should pay attention to:
9188

9289
- Keep the repository clean:
9390

94-
- Do not submit binary files, so that the size of the repository only increases due to changes in the code.
91+
- Do not submit binary files, so that the size of the repository only increases due to changes in the code.
9592

96-
- Do not submit generated code.
93+
- Do not submit generated code.
9794

9895
- The log should have meaning:
9996

100-
- Title is jira numbered: [IOTDB-jira number]
97+
- Title is jira numbered: `[IOTDB-jira number]`
10198

102-
- Title is the issue number of GitHub: [ISSUE-issue number]
99+
- Title is the issue number of GitHub: `[ISSUE-issue number]`
103100

104-
- Write #XXXX in the content for association.
101+
- Write #XXXX in the content for association.
105102

106103
### Create PR
107104

108-
Goto your github page, find the apache/servicecomb-website project, swich to the branch you just pushed, click on `New pull request` and then `Create pull request`, see the image below:If you solve the [issues](https://issues.apache.org/jira/projects/IOTDB/issues), you need to add [IOTDB-xxx] at the beginning,see the image below:
105+
Goto your github page, find the apache/servicecomb-website project, switch to the branch you just pushed, click on `New pull request` and then `Create pull request`, see the image below:If you solve the [issues](https://issues.apache.org/jira/projects/IOTDB/issues), you need to add `[IOTDB-xxx]` at the beginning,see the image below:
109106

110107
![](https://user-images.githubusercontent.com/37333508/79414865-5f815480-7fde-11ea-800c-47c7dbad7648.png)
111108

112-
Congrautulations, now you have succesfully submitted a PR. For more on PR, please read [collaborating-with-issues-and-pull-requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/)
109+
Congratulations, now you have successfully submitted a PR. For more on PR, please read [collaborating-with-issues-and-pull-requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/)
113110

114111
### Resolve conflicts
115112

116113
When a same piece of file is edited by multiple person simultaneously, conflicts can occur. It can be resolved as follow:
117114

118-
1Switch to the master branch
115+
1. Switch to the master branch
119116

120-
```
121-
git checkout master
122-
```
117+
```bash
118+
git checkout master
119+
```
123120

124-
2Pull the upstream’s master branch
121+
2. Pull the upstream’s master branch
125122

126-
```
127-
git pull upstream master
128-
```
123+
```bash
124+
git pull upstream master
125+
```
129126

130-
3Switch back to the branch we are working on(e.g. fix)
127+
3. Switch back to the branch we are working on(e.g. fix)
131128

132-
```
133-
git checkout fix
134-
```
129+
```bash
130+
git checkout fix
131+
```
135132

136-
4Rebase the working branch onto the master branch
133+
4. Rebase the working branch onto the master branch
137134

138-
```
139-
git rebase -i master
140-
```
135+
```bash
136+
git rebase -i master
137+
```
141138

142-
A list of commits will be listed on your text editor. Normally we can just save and exit. Git will now apply the commits one by one onto the master branch until it encounters a conflict. When this happens, the rebase process is paused. We need to resolve the conflicts, then execute
139+
A list of commits will be listed on your text editor. Normally we can just save and exit. Git will now apply the commits one by one onto the master branch until it encounters a conflict. When this happens, the rebase process is paused. We need to resolve the conflicts, then execute
143140

144-
```
145-
git add .
146-
git rebase --continue
147-
```
141+
```bash
142+
git add .
143+
git rebase --continue
144+
```
148145

149-
Repeat this process until all commits are successfully applied. And finally run
146+
Repeat this process until all commits are successfully applied. And finally run
150147

151-
5to push the resolved branch to remote origin
148+
5. to push the resolved branch to remote origin
152149

153-
```
154-
git push -f origin fix
155-
```
150+
```bash
151+
git push -f origin fix
152+
```
156153

157154
The code of conduct is derived from[Apache ServiceComb](http://servicecomb.apache.org/developers/submit-codes/)

src/Development/stage/HowToJoin.md

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,65 @@
11
<!--
2-
3-
Licensed to the Apache Software Foundation (ASF) under one
4-
or more contributor license agreements. See the NOTICE file
5-
distributed with this work for additional information
6-
regarding copyright ownership. The ASF licenses this file
7-
to you under the Apache License, Version 2.0 (the
8-
"License"); you may not use this file except in compliance
9-
with the License. You may obtain a copy of the License at
10-
11-
http://www.apache.org/licenses/LICENSE-2.0
12-
13-
Unless required by applicable law or agreed to in writing,
14-
software distributed under the License is distributed on an
15-
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16-
KIND, either express or implied. See the License for the
17-
specific language governing permissions and limitations
18-
under the License.
19-
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
2017
-->
2118

2219
# IoTDB Contributor Beginning
20+
2321
## Subscribe to the mailing list ([email protected])
22+
2423
The mailing list is the only communication channel that Apache designates for open source contributors. So try to make discussions on the mailing list as much as possible. The mailing list is essentially a mailbox. After subscription, all emails sent to this mailbox will be forwarded to the subscribed mailbox. The subscription method is as follows:
2524

26-
1. Sending subscription email: Send an email to [[email protected]]([email protected]) with any subject you want.
27-
2. Confirming subscription: You will receive a subscription confirmation email from iotdb.apache.org after completing the previous step. Confirm your subscription by sending another email to this email with any subject matter.
25+
1. Sending subscription email: Send an email to [[email protected]]([email protected]) with any subject you want.
26+
2. Confirming subscription: You will receive a subscription confirmation email from iotdb.apache.org after completing the previous step. Confirm your subscription by sending another email to this email with any subject matter.
2827

2928
## Create a development platform account
3029

31-
1. Creating Jira account: [https://issues.apache.org/jira/projects/IOTDB/issues](https://issues.apache.org/jira/projects/IOTDB/issues) in order to claim issues.
32-
2. Creating Confluence account: [https://cwiki.apache.org/confluence/display/IOTDB/Home](https://cwiki.apache.org/confluence/display/IOTDB/Home) . It is then used to write design documents.
30+
1. Creating Jira account: [https://issues.apache.org/jira/projects/IOTDB/issues](https://issues.apache.org/jira/projects/IOTDB/issues) in order to claim issues.
31+
2. Creating Confluence account: [https://cwiki.apache.org/confluence/display/IOTDB/Home](https://cwiki.apache.org/confluence/display/IOTDB/Home) . It is then used to write design documents.
3332

3433
After creation, please send an email to the mailing list including **self introduction**, **Jira ID** and **Confluence ID**. The community PMC will add permissions to the account.
3534

3635
## Enter user/development chat group
3736

38-
- QQ user group: 659990460
39-
- WeChat user group: IoTDB 数据库交流x群
40-
- Slack: [Apache IoTDB Community](https://join.slack.com/t/apacheiotdb/shared_invite/zt-qvso1nj8-7715TpySZtZqmyG5qXQwpg)
37+
- QQ user group: 659990460
38+
- WeChat user group: IoTDB 数据库交流 x 群
39+
- Slack: [Apache IoTDB Community](https://join.slack.com/t/apacheiotdb/shared_invite/zt-qvso1nj8-7715TpySZtZqmyG5qXQwpg)
4140

4241
## Subscribe WeChat public account
42+
4343
Scan the QR code to subscribe official public account: Apache IoTDB
4444
![IoTDB WeChat public account QR](https://user-images.githubusercontent.com/7240743/98633970-73671c00-235d-11eb-9913-f38e570fcfc8.png)
4545

4646
## Long term considerations
47+
4748
### Learn the basic use of IoTDB
4849

49-
- [Download and Setup](https://iotdb.apache.org/UserGuide/Master/QuickStart/WayToGetIoTDB.html)
50-
- [IoTDB Quick Start](https://iotdb.apache.org/UserGuide/Master/QuickStart/QuickStart_apache.html)
51-
- [Data Concept](https://iotdb.apache.org/UserGuide/Master/Data-Concept/Data-Model-and-Terminology.html)
52-
- [API](https://iotdb.apache.org/UserGuide/Master/API/Programming-Java-Native-API.html)
50+
- [Download and Setup](https://iotdb.apache.org/UserGuide/Master/QuickStart/WayToGetIoTDB.html)
51+
- [IoTDB Quick Start](https://iotdb.apache.org/UserGuide/Master/QuickStart/QuickStart_apache.html)
52+
- [Data Concept](https://iotdb.apache.org/UserGuide/Master/Data-Concept/Data-Model-and-Terminology.html)
53+
- [API](https://iotdb.apache.org/UserGuide/Master/API/Programming-Java-Native-API.html)
5354

5455
### Learn to debug IoTDB
5556

56-
- [How to debug IoTDB server](https://my.oschina.net/u/3664598/blog/4500279)
57+
- [How to debug IoTDB server](https://my.oschina.net/u/3664598/blog/4500279)
5758

5859
### Understand the internal design of IoTDB
5960

60-
- [IoTDB design documentation](https://cwiki.apache.org/confluence/display/IOTDB/Home)
61+
- [IoTDB design documentation](https://cwiki.apache.org/confluence/display/IOTDB/Home)
6162

6263
### Find to-do tasks
6364

64-
- [Resolve issues on Jira](https://issues.apache.org/jira/projects/IOTDB/issues)
65-
65+
- [Resolve issues on Jira](https://issues.apache.org/jira/projects/IOTDB/issues)

0 commit comments

Comments
 (0)