Skip to content

Commit

Permalink
docs: standardize development docs (#480)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Mister-Hope
Mister-Hope authored Dec 17, 2024
1 parent 0ca9445 commit bf430f5
Show file tree
Hide file tree
Showing 8 changed files with 448 additions and 479 deletions.
36 changes: 16 additions & 20 deletions src/Development/stage/Committer.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,19 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
-->

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


The code of conduct is derived from [Apache Beam](https://beam.apache.org/contribute/become-a-committer/).
The code of conduct is derived from [Apache Beam](https://beam.apache.org/contribute/become-a-committer/).
188 changes: 91 additions & 97 deletions src/Development/stage/ContributeGuide.md
View file

Large diffs are not rendered by default.

115 changes: 56 additions & 59 deletions src/Development/stage/HowToCommit.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,22 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
-->

# Howto Submit Code
# How to Submit Code

## Contribution

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

- Clone the source code to local machine:

```
```bash
git clone https://github.com/<your_github_name>/iotdb.git
```

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

- add apache/iotdb as upstream remote:

```
```bash
cd iotdb
git remote add upstream https://github.com/apache/iotdb.git
```

- Check the local repository’s remotes

```
```bash
git remote -v
origin https://github.com/<your_github_name>/iotdb.git (fetch)
origin https://github.com/<your_github_name>/iotdb.git(push)
upstream https://github.com/apache/iotdb.git (fetch)
upstream https://github.com/apache/iotdb.git (push)
```

- Create a new branch to start working：(e.g. fix)
- Create a new branch to start working. (e.g. fix)

```
```bash
git checkout -b fix
```

You can make code changes after creation.

- Push the changes to a remote repository：(e.g. fix)
- Push the changes to a remote repository. (e.g. fix)

```
```bash
git commit -a -m "<you_commit_message>"
git push origin fix
```
Expand All @@ -91,67 +88,67 @@ When submitting code on git, you should pay attention to:

- Keep the repository clean:

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

- Do not submit generated code.
- Do not submit generated code.

- The log should have meaning:

- Title is jira numbered: [IOTDB-jira number]
- Title is jira numbered: `[IOTDB-jira number]`

- Title is the issue number of GitHub: [ISSUE-issue number]
- Title is the issue number of GitHub: `[ISSUE-issue number]`

- Write #XXXX in the content for association.
- Write #XXXX in the content for association.

### Create PR

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:
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:

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

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/)
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/)

### Resolve conflicts

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

1：Switch to the master branch
1. Switch to the master branch

```
git checkout master
```
```bash
git checkout master
```

2：Pull the upstream’s master branch
2. Pull the upstream’s master branch

```
git pull upstream master
```
```bash
git pull upstream master
```

3：Switch back to the branch we are working on(e.g. fix)
3. Switch back to the branch we are working on(e.g. fix)

```
git checkout fix
```
```bash
git checkout fix
```

4：Rebase the working branch onto the master branch
4. Rebase the working branch onto the master branch

```
git rebase -i master
```
```bash
git rebase -i master
```

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
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

```
git add .
git rebase --continue
```
```bash
git add .
git rebase --continue
```

Repeat this process until all commits are successfully applied. And finally run
Repeat this process until all commits are successfully applied. And finally run

5：to push the resolved branch to remote origin
5. to push the resolved branch to remote origin

```
git push -f origin fix
```
```bash
git push -f origin fix
```

The code of conduct is derived from[Apache ServiceComb](http://servicecomb.apache.org/developers/submit-codes/)
66 changes: 33 additions & 33 deletions src/Development/stage/HowToJoin.md
View file
Original file line number Diff line number Diff line change
@@ -1,65 +1,65 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
-->

# IoTDB Contributor Beginning

## Subscribe to the mailing list ([email protected])

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:

1. Sending subscription email: Send an email to [[email protected]]([email protected]) with any subject you want.
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.
1. Sending subscription email: Send an email to [[email protected]]([email protected]) with any subject you want.
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.

## Create a development platform account

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.
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.
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.
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.

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.

## Enter user/development chat group

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

## Subscribe WeChat public account

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

## Long term considerations

### Learn the basic use of IoTDB

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

### Learn to debug IoTDB

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

### Understand the internal design of IoTDB

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

### Find to-do tasks

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

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

0 comments on commit bf430f5

Please sign in to comment.