This is an automated email from the ASF dual-hosted git repository.
haonan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new 18ce8537b7 Added a new document “How to Contribute Code” with chinese
and english (#6141)
18ce8537b7 is described below
commit 18ce8537b710422ae7732be3e758a1fc91e226e0
Author: chuchaofan <[email protected]>
AuthorDate: Thu Jun 2 10:05:15 2022 +0800
Added a new document “How to Contribute Code” with chinese and english
(#6141)
---
docs/Development/HowtoContributeCode.md | 160 +++++++++++++++++++++++++++++
docs/zh/Development/HowtoContributeCode.md | 154 +++++++++++++++++++++++++++
site/src/main/.vuepress/config.js | 2 +
3 files changed, 316 insertions(+)
diff --git a/docs/Development/HowtoContributeCode.md
b/docs/Development/HowtoContributeCode.md
new file mode 100644
index 0000000000..47b7024874
--- /dev/null
+++ b/docs/Development/HowtoContributeCode.md
@@ -0,0 +1,160 @@
+<!--
+
+ 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.
+
+-->
+
+# How to Contribute Code
+## Process
+Tasks are managed as issues in JIRA.
+The full lifecycle of an Issue: Create an issue -> assign an issue -> submit a
pr(pull request) -> review a pr -> squash merge a pr -> close an issue.
+
+## Contributing Conventions
+
+ ### Creating an Issue
+ There are a few things to keep in mind when creating an issue in [ JIRA
](https://issues.apache.org/JIRA/projects/IOTDB/issues)
+ 1. Naming: Try to make it clear and easy to understand. Examples include
supporting a new aggregate query function (avg) and optimizing the performance
of querying raw data . The name of the issue will later be used as the release
note.
+
+ 2. Description: Issue of new features and improvements should be clear. Bug
reports should cover the environment, load, phenomenon (abnormal log), the
affected version(s) , etc. And it's best to include ways to reproduce the bug.
+
+ ### Assigning an Issue
+ When assigning an issue in JIRA for yourself, it's recommended to add the
comment, "I'm doing this", otherwise there might be duplication of effort.
+Note: If you can't assign an issue, it is because your account doesn't have
the necessary permission.
+To address this, please send an email to the [email protected] mailing
list with the title of [application] apply for permission to assign issues to
XXX (your JIRA username).。
+### Submitting a PR
+#### What you need to submit
+Issue type : New Feature
+
+1.Submit the user manual and the pr for code changes.
+
+A user manual is mainly for helping users understand how the functions work
and how to use them. It is recommended to contain scenario and background,
configuration, interface description and examples. The user manual of the
official website is placed in the docs/UserGuide folder of apache/iotdb
repository. To update the user manual directory, including adding, deleting
documents and renaming documents, you need to make corresponding changes in the
file(path:site/src/main/.vuepress/confi [...]
+
+2.Submit UT (unit test) or IT (integration test).
+
+
+When adding unit tests or integration tests , try to cover as many cases as
possible. xxTest(path:
iotdb/server/src/test/java/org/apache/iotdb/db/query/aggregation/) and
xxIT(path: iotdb/integration/src/test/java/org/apache/iotdb/db/integration/)
can be used as reference.
+
+Issue type : Improvement
+
+1.Submit the code and UT(if importing new scenario)
+2.etter to submit test results, including quantified improvements and possible
negative effects.
+
+Issue type : Bug
+
+Submit UT or IT that can reproduce the bug.
+
+#### Coding Reminders
+Branch management
+
+The IoTDB version naming method is 0.{major version}.{minor version}. For
example, for version 0.12.4, 12 is the major version and 4 is the minor
version.
+
+As the current development branch, the master branch corresponds to the next
major release version. When each major version is released for the first time,
a separate branch will be created for archiving. For example, codes of the
0.12.x versions are placed under the rel/0.12 branch.
+
+If a bug of a released version is found and fixed, the bugfix pr should be
submitted to all branches that are newer than the specific branch. For example,
a pr which is about a version 0.11.x bugfix should be submitted to rel/0.11
branch, rel/0.12 branch and master branch.
+
+Code formatting
+It is required to use "mvn spotless:apply" to format the code before
committing, otherwise, the ci code format check will fail.
+
+Notes
+
+1.The default values need to be consistent between iotdb-engine.properties
file and IoTDBConfig file.
+
+2.To modify the configuration parameters, the following files need to be
modified
+
+a.Configuration file:
server/src/assembly/resources/conf/iotdb-engine.properties
+
+b. Codes: IoTDBDescriptor, IoTDBConfig
+
+c. Documentation: docs/UserGuide/Reference/Config-Manual.md
+
+3.To modify configuration parameters in IT and UT, you need to modify them in
the method annotated by @before and reset them in the method annotated by
@after. In this way, you can avoid impact on other tests. The parameters of the
compaction module are placed in the CompactionConfigRestorer file.
+
+#### PR Naming
+Format: [To branch] [Jira number] PR name
+
+Example: [To rel/0.12] [IoTDB-1907] implement customized sync process: sender
+
+To branch
+
+It is required when submitting pr to a non-master branch (such as rel/0.13, in
which case the pr name should contain [To rel/0.13]) and not required when
submitting to a master branch.
+
+Jira number
+
+The name should start with a JIRA number so that the PR can be automatically
linked to the corresponding issue. Example includes [IOTDB-1907] implement
customized sync process: sender.
+This auto-linking won't happen if the PR is created without any JIRA number or
with one that is improper, in which case you need to correct the PR name and
manually paste the PR link to the issue page by adding a comment or attaching a
link.
+
+#### PR Description
+Usually, the PR name can't reflect all changes, so it is better to add a
description about what has been changed and give explanations for any
difficult-to-understand part.
+
+The description of a bug-fixing pr needs to cover the cause of the bug and how
to fix it, as well as the added UT/IT test cases and associated negative
effects.
+
+#### After Submitting a PR
+
+Send to the [email protected] mailing list an email that describes the PR
in detail, then carefully read and respond to all review comments, and make
changes after reaching a consensus.
+
+### Reviewing a PR
+Checklist
+1. Is the PR named correctly? and whether any new feature and bug fix have an
issue number.
+2. Is PR description sufficiently clear?
+3. Are UT (unit test) or performance test reports submitted?
+4. Is the user manual of the new feature submitted?
+5. It should not contain code modifications for other issues. Irrelevant
modifications should be placed in other PR.
+
+How to review a pr
+
+1. Click Files changed
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto;
margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B1.png?raw=true";>
+
+2. Add review comments. First, move your mouse to the left. And then there
will be a plus sign, click the plus sign. Second, write comments. Third, click
Start a Review. At this step, all review comments will be temporarily saved,
which others can not see.<img style="width:100%; max-width:800px;
max-height:600px; margin-left:auto; margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%A
[...]
+3. Submit review. After all the comments are added, click Review Changes and
select your opinion. Select "Approve" for those that can be combined. Select
"Request Changes" or "Comment" for those that need to be modified. Select
"Comment" for those that are not sure. Finally, submit a review and only the
person submitting the PR can see the review.
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto;
margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B3.png?raw=tru";>
+
+### Merging a PR
+Make sure that all review comments are responded.
+
+Obtain approval from at least 1 committer.
+
+Choose squash merge. You can choose rebase only when the author has only one
commit record with a clear commit log.
+
+Close the corresponding issue in JIRA, and mark the repaired or completed
version. Note that solving or closing an issue requires adding a pr or
description to the issue, so that changes can be tracked via the issue.
+
+## How to Prepare User Manual and Design Document
+User manual and other documentation on the official website are maintained in
the apache/iotdb repository.
+
+The index items of each page of the official website are maintained in the
file "site/src/main/.vuepress/config.js" of the master branch, while the
specific content of the user manual is maintained in the branch of the
corresponding version (for example, user manual for 0.12 is in rel/0.12).
+
+User manual
+
+It is mainly for helping users understand how the functions work and how to
use them.
+It is recommended that the user manual contains scenario and background,
configuration, interface description and examples.。
+
+Design document
+
+It is mainly for helping developers understand how to implement a function,
including the organization of code modules and algorithms.
+It is recommended that the design document contains background, design goals,
idea, main module, interface design.
+
+### Modifying User Manual
+Other than modifying different files, the process is the same as contributing
codes.
+
+The English user manual is placed in the docs/UserGuide folder.
+
+To update the user manual directory, including adding, deleting documents and
renaming documents, you need to make corresponding changes in the
file(path:site/src/main/.vuepress/config.js) in the master branch.
+
+### Modifying the Top Navigation Bar of the Official Website
+
+Search for nav in the file(path:site/src/main/.vuepress/config.js), and make
corresponding modifications by referencing the existing code, then submit a PR
and wait for merging. Documents to be added can be placed in the docs folder.
\ No newline at end of file
diff --git a/docs/zh/Development/HowtoContributeCode.md
b/docs/zh/Development/HowtoContributeCode.md
new file mode 100644
index 0000000000..22494b13d0
--- /dev/null
+++ b/docs/zh/Development/HowtoContributeCode.md
@@ -0,0 +1,154 @@
+<!--
+
+ 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.
+
+-->
+
+# 技术贡献指南
+## 社区贡献流程概览
+Apache IoTDB 社区通过 JIRA 上的 issue 进行任务管理。
+Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审阅 pr -> 合并 pr -> 关闭 issue。
+
+## 技术贡献规范
+
+ ### 创建 issue
+ 在 [ JIRA ](https://issues.apache.org/JIRA/projects/IOTDB/issues)上创建 issue
需要注意几个事项:
+ 1. 命名：争取采用清晰易懂的名字，如支持一种新的聚合查询功能（avg）、优化原始数据查询性能等。Issue 的名字之后会作为发版的 release
note。
+
+ 2. 描述：新功能、优化需要描述具体希望做什么。 Bug 反馈需要描述环境、负载、现象描述（异常日志）、影响版本等，最好有复现方法。
+
+ ### 认领 issue
+ 在 JIRA 上认领 issue：分配给自己。建议添加一句评论：I'm doing this。避免与其他贡献者重复开发。
+ <img style="width:100%; max-width:800px; max-height:600px; margin-left:auto;
margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E8%AE%A4%E9%A2%86issue.png?raw=true";>注：如果发现自己无法认领issue，则是因为自己的账户权限不够。
+遇到此情况，请向 [email protected] 邮件列表发送邮件，标题为： [application] apply for
permission to assign issues to XXX， 其中XXX是自己的JIRA用户名。
+### 提交 PR
+#### 需提交的内容
+Issue 类型：New Feature
+
+1.提交中英文版本的用户手册和代码修改的 pr。
+
+用户手册主要描述功能定义和使用方式，以便用户使用。用户手册建议包括：场景描述，配置方法，接口功能描述，使用示例。官网的用户手册内容放置在
apache/iotdb 仓库根目录下，英文版放在 docs/UserGuide ，中文版放在 docs/zh/UserGuide 。
+如果需要更新用户手册，包括新增或删除文档和修改文档名，需要在 master 分支的site/src/main/.vuepress/config.js
中做相应修改。
+
+2.提交单元测试UT或集成测试IT
+
+需要增加单元测试UT 或集成测试IT，尽量覆盖多的用例。可以参考
xxTest（路径：iotdb/server/src/test/java/org/apache/iotdb/db/query/aggregation/），
xxIT（路径：iotdb/integration/src/test/java/org/apache/iotdb/db/integration/）。
+
+Issue 类型：Improvement
+
+提交代码和 UT，一般不需要修改用户手册。
+最好提交相关实验结果，其中包含量化的改进效果和带来的副作用。
+
+Issue 类型：Bug
+
+需要编写能够复现此 bug 的 单元测试 UT 或集成测试 IT。
+
+#### 代码管理
+分支管理：
+
+IoTDB 版本命名方式为：0.大版本.小版本。例如 0.12.4，12 就是大版本，4 是小版本。
+
+master 分支作为当前主开发分支，对应下一个未发布的大版本，每个大版本发布时会切出一个单独的分支归档，如 0.12.x 系列版本的代码处于
rel/0.12 分支下。
+
+后续如果发现并修复了某发布版本的 bug。对这些 bug 的修复都需要往大于等于该版本对应的归档分支提 pr。如一个关于 0.11.x 版本 bug 修复的
pr 需要同时向 rel/0.11、rel/0.12 和 master 分支提交。
+
+代码格式化:
+提交 PR 前需要使用 mvn spotless:apply 将代码格式化，再 commit，不然会导致 ci 代码格式化检查失败。
+
+注意事项:
+
+iotdb-engine.properties 和 IoTDBConfig 默认值需要保持一致。
+
+如果需要对配置参数进行改动。以下文件需要同时修改：
+ 1. 配置文件：server/src/assembly/resources/conf/iotdb-engine.properties
+ 2. 代码：IoTDBDescriptor、IoTDBConfig
+ 3.
文档：docs/UserGuide/Reference/Config-Manual.md、docs/zh/UserGuide/Reference/Config-Manual.md
+
+如果你想要在 IT 和 UT 文件中对配置参数进行修改，你需要在 @Before 修饰的方法里修改，并且在 @After
修饰的方法里重置，来避免对其他测试的影响。合并模块的参数统一放在CompactionConfigRestorer 文件里。
+
+#### PR 命名
+命名方式：分支标签-Jira 标签-PR 名
+
+示例： [To rel/0.12] [IoTDB-1907] implement customized sync process: sender
+
+分支标签
+
+如果是向非 master 分支提 pr，如 rel/0.13 分支，需要在 pr 名写上 [To
rel/0.13]。如果是指向master分支，则不需要写分支标签。
+
+Jira 标签
+
+以 JIRA 号开头，如：[IOTDB-1907] implement customized sync process: sender。这样创建 PR
后，机器人会将 PR 链接自动链到对应 issue 上。
+
+如果创建 PR 时忘记添加 JIRA 号，或 JIRA 号不规范，则 PR 不会被自动链接到 Jira 上，需要先改正 PR 命名，并手动将 PR 链接贴到
issue 页面（通过留言或链接框）。
+
+#### PR 描述
+通常 PR 名无法涵盖所有改动，需要添加具体描述，改动了哪些内容。对于较难理解的地方给予一定的解释。
+
+修 bug 的 pr 需要描述 bug 出现的原因，以及解决方法，另外还需要描述UT/IT测试用例添加的情况和负面效果的描述。
+
+#### 提交 PR 后
+
+向邮件列表 [email protected] 发送一封邮件，主要介绍 PR 的工作。重视每个审阅者的意见，一一回复，并对达成一致的建议进行修改。
+
+### 审阅PR
+主要关注以下事项：
+1. PR命名是否规范，新功能和bug修复类型的pr是否带了JIRA 号。
+2. PR 描述是否清晰。
+3. 功能测试用例或性能测试报告是否附上。
+4. 新功能是否有用户手册。
+5. 尽量不夹带其他问题的代码修改，将不相关的修改拆分到其他PR。
+
+代码审阅流程：
+
+1. 点击 PR 的 Files changed
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto;
margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B1.png?raw=true";>
+2. 对于有问题的行，移动到左侧，会出现加号，点击加号，然后评论，点击 Start a review，此时，所有的 Review
意见都会暂存起来，别人看不到。<img style="width:100%; max-width:800px; max-height:600px;
margin-left:auto; margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B2.png?raw=true";>
+3. 所有评论加完后，需要点击 Review changes，选择你的意见，已经可以合并的选择 Approve，有 Bug 需要改的选择 Request
changes 或者 Comment，不确定的选择 Comment。最后 Submit review 提交审阅意见，提 PR 的人才能看见此意见。
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto;
margin-right:auto; display:block;"
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B3.png?raw=tru";>
+### 合并PR
+确认所有审阅意见均已回复。
+
+有1个以上 committer 的Approval。
+
+选择 squash merge （当且仅当作者仅有一个提交记录，且记录的commitlog清晰，可选择rebase）。
+
+到 JIRA 上关闭对应的 issue，标记修复或完成的版本【注意，解决或关闭 issue 都需要对 issue 添加 pr 或描述，通过 issue
要能够追踪这个任务的变动】。
+
+## 如何写用户手册和设计文档
+官网的用户手册和其他文档都在 apache/iotdb 仓库中进行维护。
+
+官网各个页面的索引项是在 master 分支的 site/src/main/.vuepress/config.js
文件维护的，用户手册的具体内容是在各个版本的分支维护的，如 0.12 版本的用户手册文档在 rel/0.12 中。
+
+用户手册
+
+主要描述功能定义和使用方式，以便用户使用。
+用户手册建议包括：场景描述，配置参数，接口功能描述，使用示例。用户手册建议包括：场景描述，配置参数，接口功能描述，使用示例。
+
+设计文档
+
+主要描述如何实现某个功能，包括代码模块组织及算法，以便开发者参与。
+设计文档建议包括如下内容：背景描述，设计目标，总体思路，主要模块，接口设计
+
+### 如何修改用户手册
+贡献用户手册和贡献代码的流程是一样的，只是修改的文件不同。
+用户手册的英文版放在 docs/UserGuide , 中文版放在 docs/zh/UserGuide 下。
+如果需要更新 {master} 或 {rel/*} 分支的用户手册目录，包括新增或删除md文档、修改md文档名，需要在 master
分支的site/src/main/.vuepress/config.js 中做相应修改。
+
+### 如何修改官网顶部导航栏
+
+在 site/src/main/.vuepress/config.js 中搜索 nav
（应有中英文两个地方），仿照现有的代码做相应修改。之后提交PR等待合并。需要新增的文档可以放进 docs 和 docs/zh 文件夹下。
\ No newline at end of file
diff --git a/site/src/main/.vuepress/config.js
b/site/src/main/.vuepress/config.js
index 9a9de40a0a..1c35abad01 100644
--- a/site/src/main/.vuepress/config.js
+++ b/site/src/main/.vuepress/config.js
@@ -120,6 +120,7 @@ var config = {
{ text: 'Become a Contributor', link:
'/Development/HowToJoin'},
{ text: 'Become a Committer', link:
'/Development/Committer'},
{ text: 'ContributeGuide', link:
'/Development/ContributeGuide'},
+ { text: 'How to Contribute Code',
link: '/Development/HowtoContributeCode'},
{ text: 'Changelist of TsFile', link:
'/Development/format-changelist'},
{ text: 'Changelist of RPC', link:
'/Development/rpc-changelist'},
]
@@ -1061,6 +1062,7 @@ var config = {
{ text: '成为Contributor', link:
'/zh/Development/HowToJoin'},
{ text: '成为Committer', link:
'/zh/Development/Committer'},
{ text: '项目开发指南', link:
'/zh/Development/ContributeGuide'},
+ { text: '技术贡献指南', link:
'/zh/Development/HowtoContributeCode'},
{ text: 'TsFile的更改列表', link:
'/zh/Development/format-changelist'},
{ text: 'RPC变更清单', link:
'/zh/Development/rpc-changelist'},
]
![https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B1.png?raw=true"](https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B1.png?raw=true"){kind=link}
![https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B3.png?raw=tru"](https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B3.png?raw=tru"){kind=link}
![https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E8%AE%A4%E9%A2%86issue.png?raw=true"](https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E8%AE%A4%E9%A2%86issue.png?raw=true"){kind=link}
![https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B2.png?raw=true"](https://github.com/apache/iotdb-bin-resources/blob/main/docs/zh/development/howtocontributecode/%E4%BB%A3%E7%A0%81%E5%AE%A1%E9%98%85%E6%B5%81%E7%A8%8B2.png?raw=true"){kind=link}