<!--
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。
在 JIRA 上创建 issue 需要注意几个事项:
命名:争取采用清晰易懂的名字,如支持一种新的聚合查询功能(avg)、优化原始数据查询性能等。Issue 的名字之后会作为发版的 release note。
描述:新功能、优化需要描述具体希望做什么。 Bug 反馈需要描述环境、负载、现象描述(异常日志)、影响版本等,最好有复现方法。
在 JIRA 上认领 issue:分配给自己。建议添加一句评论:I'm doing this。避免与其他贡献者重复开发。 注:如果发现自己无法认领issue,则是因为自己的账户权限不够。 遇到此情况,请向 dev@iotdb.apache.org 邮件列表发送邮件,标题为: [application] apply for permission to assign issues to XXX, 其中XXX是自己的JIRA用户名。
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-datanode.properties 和 IoTDBConfig 默认值需要保持一致。
如果需要对配置参数进行改动。以下文件需要同时修改:
如果你想要在 IT 和 UT 文件中对配置参数进行修改,你需要在 @Before 修饰的方法里修改,并且在 @After 修饰的方法里重置,来避免对其他测试的影响。合并模块的参数统一放在CompactionConfigRestorer 文件里。
命名方式:分支标签-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 名无法涵盖所有改动,需要添加具体描述,改动了哪些内容。对于较难理解的地方给予一定的解释。
修 bug 的 pr 需要描述 bug 出现的原因,以及解决方法,另外还需要描述UT/IT测试用例添加的情况和负面效果的描述。
向邮件列表 dev@iotdb.apache.org 发送一封邮件,主要介绍 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 文件夹下。