From 8e558b63a3b1039b16096c595794c4627a4a3ce4 Mon Sep 17 00:00:00 2001 From: majialin117 <107627937+mal117@users.noreply.github.com> Date: Fri, 8 Mar 2024 10:21:59 +0000 Subject: [PATCH 1/3] add Development-Guide --- docs/src/.vuepress/navbar/zh.ts | 1 + docs/src/zh/Development/Development-Guide.md | 452 +++++++++++++++++++ 2 files changed, 453 insertions(+) create mode 100644 docs/src/zh/Development/Development-Guide.md diff --git a/docs/src/.vuepress/navbar/zh.ts b/docs/src/.vuepress/navbar/zh.ts index c434303c2..3b8463bf8 100644 --- a/docs/src/.vuepress/navbar/zh.ts +++ b/docs/src/.vuepress/navbar/zh.ts @@ -41,6 +41,7 @@ export const zhNavbar = navbar([ text: '开发', children: [ { text: '成为开发者', link: '/zh/Development/Community-Project-Committers' }, + { text: '开发指南', link: '/zh/Development/Development-Guide' }, { text: 'Power by', link: '/zh/Development/Powered-By' }, ], }, diff --git a/docs/src/zh/Development/Development-Guide.md b/docs/src/zh/Development/Development-Guide.md new file mode 100644 index 000000000..4a3e3606b --- /dev/null +++ b/docs/src/zh/Development/Development-Guide.md @@ -0,0 +1,452 @@ + +# 开发指南 +## 开发约定 +### 代码格式化 (应该没有变化，昊男确认) +我们使用 [Spotless plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven) 和 [google-java-format](https://github.com/google/google-java-format) 格式化 Java 代码。你可以通过以下步骤将 IDE 配置为在保存时自动应用格式以 IDEA 为例）： +1.下载 [google-java-format-plugin v1.7.0.5](https://plugins.jetbrains.com/plugin/8527-google-java-format/versions/stable/83169), 安装到 IDEA(Preferences -> plugins -> search google-java-format),更详细的内容请查看[操作手册](https://github.com/google/google-java-format#intellij-android-studio-and-other-jetbrains-ides) +2.从磁盘安装 (Plugins -> little gear icon -> "Install plugin from disk" -> Navigate to downloaded zip file) +3.开启插件，并保持默认的 GOOGLE 格式 (2-space indents) +4.在 Spotless 没有升级到 18+之前，不要升级 google-java-format 插件 +5.安装 [Save Actions](https://plugins.jetbrains.com/plugin/7642-save-actions) 插件 , 并开启插件，打开 "Optimize imports" and "Reformat file" 选项。 +6.在“Save Actions”设置页面中，将 "File Path Inclusion" 设置为 .*.java”, 避免在编辑的其他文件时候发生意外的重新格式化 + +### 编码风格 (应该没有变化，昊男确认) +我们使用 [maven-checkstyle-plugin](https://checkstyle.sourceforge.io/config_filefilters.html)来保证所有的 Java 代码风格都遵循在项目根目录下的 [checkstyle.xml](https://github.com/apache/iotdb/blob/master/checkstyle.xml) 文件中定义的规则集. + +您可以从该文件中查阅到所有的代码风格要求。当开发完成后，您可以使用 `mvn validate` 命令来检查您的代码是否符合代码风格的要求。 + +另外, 当您在集成开发环境开发时，可能会因为环境的默认代码风格配置导致和本项目的风格规则冲突。 + +在 IDEA 中，您可以通过如下步骤解决风格规则不一致的问题。 +- 禁用通配符引用 + - 跳转至 Java 代码风格配置页面 (Preferences... -> 编辑器 -> 代码风格 -> Java)。 + - 切换到“导入”标签。 + - 在“常规”部分，启用“使用单个类导入”选项。 + - 将“将 import 与‘*’搭配使用的类计数”改成 999 或者一个比较大的值。 + - 将“将静态 import 与‘*’搭配使用的名称计数”改成 999 或者一个比较大的值。 + +## 贡献方式 +### 参与投票 （问昊男投票方式） +- 1.给发布版本投票 + * 非中文用户，请阅读 https://cwiki.apache.org/confluence/display/IOTDB/Validating+a+staged+Release +- 2.下载投票的版本/rc下所有内容 + * https://dist.apache.org/repos/dist/dev/iotdb/ + +- 3.导入发布经理的公钥 + + * https://dist.apache.org/repos/dist/dev/iotdb/KEYS + + * 最下边有 Release Manager (RM) 的公钥 + + * 安装 gpg2 + + - 第一种方法 + + * 公钥的开头如下 + ``` + pub rsa4096 2019-10-15 [SC] + 10F3B3F8A1201B79AA43F2E00FC7F131CAA00430 + ``` + + 或是 + + ``` + pub rsa4096/28662AC6 2019-12-23 [SC] + ``` + + * 下载公钥 + + ``` + gpg2 --receive-keys 10F3B3F8A1201B79AA43F2E00FC7F131CAA00430 （或 28662AC6) + + 或 （指定 keyserver) + gpg2 --keyserver p80.pool.sks-keyservers.net --recv-keys 10F3B3F8A1201B79AA43F2E00FC7F131CAA00430 （或 28662AC6) + ``` + + - 第二种方法 + * 把下方内容复制到一个文本文件中，文本名为 ```key.asc``` + + * 内容如下： + ``` + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v2 + ... + -----END PGP PUBLIC KEY BLOCK----- + ``` + + 导入 RM 的公钥到自己电脑 + + ``` + gpg2 --import key.asc + + ``` + +- 4.验证源码发布版 + + * 验证是否有 NOTICE、LICENSE，以及内容是否正确。 + + * 验证 README、RELEASE_NOTES + + * 验证 header + + ``` + mvn -B apache-rat:check + ``` + + * 验证签名和哈希值 + + ``` + gpg2 --verify apache-iotdb-0.12.0-source-release.zip.asc apache-iotdb-0.12.0-source-release.zip + + 出现 Good Singnature + + shasum -a512 apache-iotdb-0.12.0-source-release.zip + + 和对应的 .sha512 对比，一样就可以。 + ``` + + * 验证编译 + + ``` + mvnw install + + 应该最后全 SUCCESS + ``` +- 5.验证二进制发布版 + + * 验证是否有 NOTICE、LICENSE，以及内容是否正确。 + + * 验证 README、RELEASE_NOTES + + * 验证签名和哈希值 + + ``` + gpg2 --verify apache-iotdb-0.12.0-bin.zip.asc apache-iotdb-0.12.0-bin.zip + + 出现 Good Singnature + + shasum -a512 apache-iotdb-0.12.0-bin.zip + + 和对应的 .sha512 对比，一样就可以。 + ``` + + * 验证是否能启动以及示例语句是否正确执行 + + ``` + nohup ./sbin/start-server.sh >/dev/null 2>&1 & + + ./sbin/start-cli.sh + + CREATE DATABASE root.turbine; + CREATE TIMESERIES root.turbine.d1.s0 WITH DATATYPE=DOUBLE, ENCODING=GORILLA; + insert into root.turbine.d1(timestamp,s0) values(1,1); + insert into root.turbine.d1(timestamp,s0) values(2,2); + insert into root.turbine.d1(timestamp,s0) values(3,3); + select * from root.**; + + 打印如下内容： + +-----------------------------------+------------------+ + | Time|root.turbine.d1.s0| + +-----------------------------------+------------------+ + | 1970-01-01T08:00:00.001+08:00| 1.0| + | 1970-01-01T08:00:00.002+08:00| 2.0| + | 1970-01-01T08:00:00.003+08:00| 3.0| + +-----------------------------------+------------------+ + + ``` +- 6.回复邮件 + + 验证通过之后可以发邮件了 + + ``` + Hi, + + +1 (PMC could binding) + + The source release: + LICENSE and NOTICE [ok] + signatures and hashes [ok] + All files have ASF header [ok] + could compile from source: ./mvnw clean install [ok] + + The binary distribution: + LICENSE and NOTICE [ok] + signatures and hashes [ok] + Could run with the following statements [ok] + + CREATE DATABASE root.turbine; + CREATE TIMESERIES root.turbine.d1.s0 WITH DATATYPE=DOUBLE, ENCODING=GORILLA; + insert into root.turbine.d1(timestamp,s0) values(1,1); + insert into root.turbine.d1(timestamp,s0) values(2,2); + insert into root.turbine.d1(timestamp,s0) values(3,3); + select * from root.**; + + Thanks, + xxx + ``` +### 贡献代码 +#### 贡献流程： + - Apache IoTDB 社区通过 JIRA 上的 issue 进行任务管理。 +Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审阅 pr -> 合并 pr -> 关闭 issue。 + +#### 创建 issue ：（xy确认方式） + - 在 JIRA 上创建 issue 需要注意几个事项: + * 1.命名：争取采用清晰易懂的名字，如支持一种新的聚合查询功能（avg）、优化原始数据查询性能等。Issue 的名字之后会作为发版的 release note。 + * 2.描述：新功能、优化需要描述具体希望做什么。 Bug 反馈需要描述环境、负载、现象描述（异常日志）、影响版本等，最好有复现方法。 +#### 认领 issue ：（xy确认方式） + - 在 JIRA 上认领 issue：分配给自己。建议添加一句评论：I'm doing this。避免与其他贡献者重复开发。 + + 注：如果发现自己无法认领issue，则是因为自己的账户权限不够。遇到此情况，请向 dev@iotdb.apache.org 邮件列表发送邮件，标题为： [application] apply for permission to assign issues to XXX， 其中XXX是自己的JIRA用户名。 +#### 提交PR (昊男确认流程) + - 1.如何提交代码 + - 贡献途径： + - IoTDB 诚邀广大开发者参与开源项目构建，您可以查看 [issues](https://issues.apache.org/jira/projects/IOTDB/issues) 并参与解决，或者做其他改善。 + - 提交 pr，通过 Travis-CI 测试和 Sonar 代码质量检测后，至少有一位以上 Committer 同意且代码无冲突，就可以合并了 + - PR指南： + - 在 Github 上面可以很方便地提交 [Pull Request (PR)](https://help.github.com/articles/about-pull-requests/)，下面将以本网站项目 [apache/iotdb](https://github.com/apache/iotdb) 为例（如果是其他项目，请替换项目名 iotdb） + * 1.Fork仓库： + - 进入 apache/iotdb 的 [github 页面](https://github.com/apache/iotdb) ，点击右上角按钮 `Fork` 进行 Fork + * 2.配置 git 和提交修改 + + - 第一步：将代码克隆到本地： + + ``` + git clone https://github.com//iotdb.git + ``` + + **注意:请将 替换为您的 github 名字** + + clone 完成后，origin 会默认指向 github 上的远程 fork 地址。 + + - 第二步：将 apache/iotdb 添加为本地仓库的远程分支 upstream： + + ``` + cd iotdb + git remote add upstream https://github.com/apache/iotdb.git + ``` + + - 第三步：检查远程仓库设置： + + ``` + git remote -v + origin https://github.com//iotdb.git (fetch) + origin https://github.com//iotdb.git(push) + upstream https://github.com/apache/iotdb.git (fetch) + upstream https://github.com/apache/iotdb.git (push) + ``` + + - 第四步：新建分支以便在分支上做修改：（假设新建的分支名为 fix） + + ``` + git checkout -b fix + ``` + + 创建完成后可进行代码更改。 + + - 第五提交代码到远程分支：（此处以 fix 分支为例） + + ``` + git commit -a -m "" + git push origin fix + ``` + + 更多 git 使用方法请访问：[git 使用](https://www.atlassian.com/git/tutorials/setting-up-a-repository) + * 3.Git 提交注意事项 + - 在 Git 上提交代码时需要注意： + + - 1.保持仓库的整洁： + + - 不要上传二进制文件，保证仓库的大小只因为代码字符串的改动而增大。 + + - 不要上传生成的代码。 + + - 2.日志要有含义： + + - 题目用jira编号：[IOTDB-jira号] + + - 题目用github的ISSUE编号：[ISSUE-issue号] + + - 内容里要写#XXXX用于关联 + * 4.创建 PR + + 在浏览器切换到自己的 github 仓库页面，切换分支到提交的分支 ，依次点击 `New pull request` 和 `Create pull request` 按钮进行创建，如果您解决的是 [issues](https://issues.apache.org/jira/projects/IOTDB/issues)，需要在开头加上 [IOTDB-xxx]。 + 至此，您的 PR 创建完成，更多关于 PR 请阅读 [collaborating-with-issues-and-pull-requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) + * 5. 冲突解决 + + 提交 PR 时的代码冲突一般是由于多人编辑同一个文件引起的，解决冲突主要通过以下步骤即可： + + 步骤一：切换至主分支 + + ``` + git checkout master + ``` + + 步骤二：同步远端主分支至本地 + + ``` + git pull upstream master + ``` + + 步骤三：切换回刚才的分支（假设分支名为 fix） + + ``` + git checkout fix + ``` + + 步骤四：进行 rebase + + ``` + git rebase -i master + ``` + + 此时会弹出修改记录的文件，一般直接保存即可。然后会提示哪些文件出现了冲突，此时可打开冲突文件对冲突部分进行修改，将提示的所有冲突文件的冲突都解决后，执行 + + ``` + git add . + git rebase --continue + ``` + + 依此往复，直至屏幕出现类似 *rebase successful* 字样即可，此时您可以进行往提交 PR 的分支进行更新： + + ``` + git push -f origin fix + ``` + - 2.需提交的内容：（昊男确认） + - Issue 类型：New Feature + + - 1.提交中英文版本的用户手册和代码修改的 pr。 + + 用户手册主要描述功能定义和使用方式，以便用户使用。用户手册建议包括：场景描述，配置方法，接口功能描述，使用示例。官网的用户手册内容放置在 apache/iotdb-docs 仓库 src 目录下，英文版放在 src/UserGuide ，中文版放在 src/zh/UserGuide 。 + 如果需要更新用户手册，包括新增或删除文档和修改文档名，需要在 main 分支的 src/.vuepress/sidebar 中做相应修改。 + + - 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。 + * 3.代码管理 （昊男确认） + * a.分支管理： + + * 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 分支提交。 + + * b.代码格式化: + * 提交 PR 前需要使用 mvn spotless:apply 将代码格式化，再 commit，不然会导致 ci 代码格式化检查失败。 + + * c.注意事项: + * iotdb-datanode.properties 和 IoTDBConfig 默认值需要保持一致。 + * 如果需要对配置参数进行改动。以下文件需要同时修改： + 1. 配置文件：iotdb-core/datanode/src/assembly/resources/conf/iotdb-datanode.properties + 2. 代码：IoTDBDescriptor、IoTDBConfig + 3. 文档：apache/iotdb-docs/src/UserGuide/{version}/Reference/DataNode-Config-Manual.md、apache/iotdb-docs/src/zh/UserGuide/{version}/Reference/DataNode-Config-Manual.md + 如果你想要在 IT 和 UT 文件中对配置参数进行修改，你需要在 @Before 修饰的方法里修改，并且在 @After 修饰的方法里重置，来避免对其他测试的影响。合并模块的参数统一放在CompactionConfigRestorer 文件里。 + * 4. PR 命名 + * 命名方式：分支标签-Jira 标签-PR 名 + + 示例： [To rel/0.12] [TsFile-1907] implement customized sync process: sender + + * 分支标签 + + 如果是向非 master 分支提 pr，如 rel/0.13 分支，需要在 pr 名写上 [To rel/0.13]。如果是指向master分支，则不需要写分支标签。 + + * Jira 标签 + + 以 JIRA 号开头，如：[TsFile-1907] implement customized sync process: sender。这样创建 PR 后，机器人会将 PR 链接自动链到对应 issue 上。 + + 注：如果创建 PR 时忘记添加 JIRA 号，或 JIRA 号不规范，则 PR 不会被自动链接到 Jira 上，需要先改正 PR 命名，并手动将 PR 链接贴到 issue 页面（通过留言或链接框）。 + * 5. PR 描述 + 通常 PR 名无法涵盖所有改动，需要添加具体描述，改动了哪些内容。对于较难理解的地方给予一定的解释。 + + 修改 bug 的 pr 需要描述 bug 出现的原因，以及解决方法，另外还需要描述UT/IT测试用例添加的情况和负面效果的描述。 + * 6.提交 PR 后 + + 向邮件列表 dev@tsfile.apache.org 发送一封邮件，主要介绍 PR 的工作。重视每个审阅者的意见，一一回复，并对达成一致的建议进行修改。 + +#### 审阅PR +- 注意事项： + - 1. PR命名是否规范，新功能和bug修复类型的pr是否带了JIRA 号。 + - 2. PR 描述是否清晰。 + - 3. 功能测试用例或性能测试报告是否附上。 + - 4. 新功能是否有用户手册。 + - 5. 尽量不夹带其他问题的代码修改，将不相关的修改拆分到其他PR。 +- 审阅流程：(更换截图) + - 第一步： 点击 PR 的 Files changed + + - 第二步：对于有问题的行，移动到左侧，会出现加号，点击加号，然后评论，点击 Start a review，此时，所有的 Review 意见都会暂存起来，别人看不到。 + + - 第三步： 所有评论加完后，需要点击 Review changes，选择你的意见，已经可以合并的选择 Approve，有 Bug 需要改的选择 Request changes 或者 Comment，不确定的选择 Comment。最后 Submit review 提交审阅意见，提 PR 的人才能看见此意见。 + +#### 合并PR +- 确认所有审阅意见均已回复且有1个以上 committer 的Approval。 + +- 选择 squash merge （当且仅当作者仅有一个提交记录，且记录的commitlog清晰，可选择rebase）。 + +- 到 JIRA 上关闭对应的 issue，标记修复或完成的版本【注意，解决或关闭 issue 都需要对 issue 添加 pr 或描述，通过 issue 要能够追踪这个任务的变动】。 + +### 贡献文档 + +贡献用户手册和贡献代码的流程是一样的，只是修改的文件不同。 +用户手册的英文版放在 tsfile/docs/src/UserGuide , 中文版放在 src/UserGuide/zh 下。 +如果需要更新用户手册目录，包括新增或删除md文档、修改md文档名，需要在 main 分支的 src/.vuepress/sidebar 中做相应修改。 + + +### 新功能、Bug 反馈、改进等 +所有希望 TsFile 做的功能或修的 bug，都可以在 Jira 上提 issue + +可以选择 issue 类型：bug、improvement、new feature 等。新建的 issue 会自动向邮件列表中同步邮件，之后的讨论可在 jira 上留言，也可以在邮件列表进行。当问题解决后请关闭 issue。 + +### 邮件讨论内容 +请使用英文进行讨论： + * 第一次参与邮件列表可以简单介绍一下自己。（Hi, I'm xxx ...) + + * 开发功能前可以发邮件声明一下自己想做的任务。（Hi，I'm working on issue TsFile-XXX，My plan is ...） + + +## 常见资料 (xy) +- IoTDB 官网：https://iotdb.apache.org/ + +- 代码库：https://github.com/apache/iotdb/tree/master + +- Go语言的代码库：https://github.com/apache/iotdb-client-go + +- 文档库：https://github.com/apache/iotdb-docs + +- 资源库（包含项目文件等）：https://github.com/apache/iotdb-bin-resources + +- 快速上手：https://iotdb.apache.org/zh/UserGuide/V1.1.x/QuickStart/QuickStart.html + +- Jira 任务管理：https://issues.apache.org/jira/projects/IOTDB/issues + +- Wiki 文档管理：https://cwiki.apache.org/confluence/display/IOTDB/Home + +- 邮件列表: https://lists.apache.org/list.html?dev@iotdb.apache.org + +- 每日构建: https://ci-builds.apache.org/job/IoTDB/job/IoTDB-Pipe/job/master/ + +- Slack: https://apacheiotdb.slack.com/join/shared_invite/zt-qvso1nj8-7715TpySZtZqmyG5qXQwpg#/shared-invite/email \ No newline at end of file From 5644004561fa575fa1700814023e78031e976ee0 Mon Sep 17 00:00:00 2001 From: Haonan Date: Tue, 12 Mar 2024 10:58:18 +0800 Subject: [PATCH 2/3] Update Development-Guide.md --- docs/src/zh/Development/Development-Guide.md | 118 ++++++------------- 1 file changed, 34 insertions(+), 84 deletions(-) diff --git a/docs/src/zh/Development/Development-Guide.md b/docs/src/zh/Development/Development-Guide.md index 4a3e3606b..bd9d644d0 100644 --- a/docs/src/zh/Development/Development-Guide.md +++ b/docs/src/zh/Development/Development-Guide.md @@ -20,7 +20,7 @@ --> # 开发指南 ## 开发约定 -### 代码格式化 (应该没有变化，昊男确认) +### 代码格式化 我们使用 [Spotless plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven) 和 [google-java-format](https://github.com/google/google-java-format) 格式化 Java 代码。你可以通过以下步骤将 IDE 配置为在保存时自动应用格式以 IDEA 为例）： 1.下载 [google-java-format-plugin v1.7.0.5](https://plugins.jetbrains.com/plugin/8527-google-java-format/versions/stable/83169), 安装到 IDEA(Preferences -> plugins -> search google-java-format),更详细的内容请查看[操作手册](https://github.com/google/google-java-format#intellij-android-studio-and-other-jetbrains-ides) 2.从磁盘安装 (Plugins -> little gear icon -> "Install plugin from disk" -> Navigate to downloaded zip file) @@ -29,8 +29,8 @@ 5.安装 [Save Actions](https://plugins.jetbrains.com/plugin/7642-save-actions) 插件 , 并开启插件，打开 "Optimize imports" and "Reformat file" 选项。 6.在“Save Actions”设置页面中，将 "File Path Inclusion" 设置为 .*.java”, 避免在编辑的其他文件时候发生意外的重新格式化 -### 编码风格 (应该没有变化，昊男确认) -我们使用 [maven-checkstyle-plugin](https://checkstyle.sourceforge.io/config_filefilters.html)来保证所有的 Java 代码风格都遵循在项目根目录下的 [checkstyle.xml](https://github.com/apache/iotdb/blob/master/checkstyle.xml) 文件中定义的规则集. +### 编码风格 +我们使用 [maven-checkstyle-plugin](https://checkstyle.sourceforge.io/config_filefilters.html)来保证所有的 Java 代码风格都遵循在项目根目录下的 [checkstyle.xml](https://github.com/apache/tsfile/blob/develop/checkstyle.xml) 文件中定义的规则集. 您可以从该文件中查阅到所有的代码风格要求。当开发完成后，您可以使用 `mvn validate` 命令来检查您的代码是否符合代码风格的要求。 @@ -45,15 +45,15 @@ - 将“将静态 import 与‘*’搭配使用的名称计数”改成 999 或者一个比较大的值。 ## 贡献方式 -### 参与投票 （问昊男投票方式） +### 参与投票 - 1.给发布版本投票 - * 非中文用户，请阅读 https://cwiki.apache.org/confluence/display/IOTDB/Validating+a+staged+Release + - 2.下载投票的版本/rc下所有内容 * https://dist.apache.org/repos/dist/dev/iotdb/ - 3.导入发布经理的公钥 - * https://dist.apache.org/repos/dist/dev/iotdb/KEYS + * https://dist.apache.org/repos/dist/dev/tsfile/KEYS * 最下边有 Release Manager (RM) 的公钥 @@ -115,11 +115,11 @@ * 验证签名和哈希值 ``` - gpg2 --verify apache-iotdb-0.12.0-source-release.zip.asc apache-iotdb-0.12.0-source-release.zip + gpg2 --verify apache-tsfile-1.0.0-source-release.zip.asc apache-tsfile-1.0.0-source-release.zip 出现 Good Singnature - shasum -a512 apache-iotdb-0.12.0-source-release.zip + shasum -a512 apache-tsfile-1.0.0-source-release.zip 和对应的 .sha512 对比，一样就可以。 ``` @@ -149,30 +149,6 @@ 和对应的 .sha512 对比，一样就可以。 ``` - * 验证是否能启动以及示例语句是否正确执行 - - ``` - nohup ./sbin/start-server.sh >/dev/null 2>&1 & - - ./sbin/start-cli.sh - - CREATE DATABASE root.turbine; - CREATE TIMESERIES root.turbine.d1.s0 WITH DATATYPE=DOUBLE, ENCODING=GORILLA; - insert into root.turbine.d1(timestamp,s0) values(1,1); - insert into root.turbine.d1(timestamp,s0) values(2,2); - insert into root.turbine.d1(timestamp,s0) values(3,3); - select * from root.**; - - 打印如下内容： - +-----------------------------------+------------------+ - | Time|root.turbine.d1.s0| - +-----------------------------------+------------------+ - | 1970-01-01T08:00:00.001+08:00| 1.0| - | 1970-01-01T08:00:00.002+08:00| 2.0| - | 1970-01-01T08:00:00.003+08:00| 3.0| - +-----------------------------------+------------------+ - - ``` - 6.回复邮件 验证通过之后可以发邮件了 @@ -191,14 +167,6 @@ The binary distribution: LICENSE and NOTICE [ok] signatures and hashes [ok] - Could run with the following statements [ok] - - CREATE DATABASE root.turbine; - CREATE TIMESERIES root.turbine.d1.s0 WITH DATATYPE=DOUBLE, ENCODING=GORILLA; - insert into root.turbine.d1(timestamp,s0) values(1,1); - insert into root.turbine.d1(timestamp,s0) values(2,2); - insert into root.turbine.d1(timestamp,s0) values(3,3); - select * from root.**; Thanks, xxx @@ -216,42 +184,42 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 - 在 JIRA 上认领 issue：分配给自己。建议添加一句评论：I'm doing this。避免与其他贡献者重复开发。 注：如果发现自己无法认领issue，则是因为自己的账户权限不够。遇到此情况，请向 dev@iotdb.apache.org 邮件列表发送邮件，标题为： [application] apply for permission to assign issues to XXX， 其中XXX是自己的JIRA用户名。 -#### 提交PR (昊男确认流程) +#### 提交PR - 1.如何提交代码 - 贡献途径： - IoTDB 诚邀广大开发者参与开源项目构建，您可以查看 [issues](https://issues.apache.org/jira/projects/IOTDB/issues) 并参与解决，或者做其他改善。 - - 提交 pr，通过 Travis-CI 测试和 Sonar 代码质量检测后，至少有一位以上 Committer 同意且代码无冲突，就可以合并了 + - 提交 pr，通过 GitHub actions 测试和 Sonar 代码质量检测后，至少有一位以上 Committer 同意且代码无冲突，就可以合并了 - PR指南： - - 在 Github 上面可以很方便地提交 [Pull Request (PR)](https://help.github.com/articles/about-pull-requests/)，下面将以本网站项目 [apache/iotdb](https://github.com/apache/iotdb) 为例（如果是其他项目，请替换项目名 iotdb） + - 在 Github 上面可以很方便地提交 [Pull Request (PR)](https://help.github.com/articles/about-pull-requests/)，下面将以本网站项目 [apache/tsfile](https://github.com/apache/tsfile) 为例 * 1.Fork仓库： - - 进入 apache/iotdb 的 [github 页面](https://github.com/apache/iotdb) ，点击右上角按钮 `Fork` 进行 Fork + - 进入 apache/tsfile 的 [github 页面](https://github.com/apache/tsfile) ，点击右上角按钮 `Fork` 进行 Fork * 2.配置 git 和提交修改 - 第一步：将代码克隆到本地： ``` - git clone https://github.com//iotdb.git + git clone https://github.com//tsfile.git ``` **注意:请将 替换为您的 github 名字** clone 完成后，origin 会默认指向 github 上的远程 fork 地址。 - - 第二步：将 apache/iotdb 添加为本地仓库的远程分支 upstream： + - 第二步：将 apache/tsfile 添加为本地仓库的远程分支 upstream： ``` - cd iotdb - git remote add upstream https://github.com/apache/iotdb.git + cd tsfile + git remote add upstream https://github.com/apache/tsfile.git ``` - 第三步：检查远程仓库设置： ``` git remote -v - origin https://github.com//iotdb.git (fetch) - origin https://github.com//iotdb.git(push) - upstream https://github.com/apache/iotdb.git (fetch) - upstream https://github.com/apache/iotdb.git (push) + origin https://github.com//tsfile.git (fetch) + origin https://github.com//tsfile.git(push) + upstream https://github.com/apache/tsfile.git (fetch) + upstream https://github.com/apache/tsfile.git (push) ``` - 第四步：新建分支以便在分支上做修改：（假设新建的分支名为 fix） @@ -281,14 +249,12 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 - 2.日志要有含义： - - 题目用jira编号：[IOTDB-jira号] - - 题目用github的ISSUE编号：[ISSUE-issue号] - 内容里要写#XXXX用于关联 * 4.创建 PR - 在浏览器切换到自己的 github 仓库页面，切换分支到提交的分支 ，依次点击 `New pull request` 和 `Create pull request` 按钮进行创建，如果您解决的是 [issues](https://issues.apache.org/jira/projects/IOTDB/issues)，需要在开头加上 [IOTDB-xxx]。 + 在浏览器切换到自己的 github 仓库页面，切换分支到提交的分支 ，依次点击 `New pull request` 和 `Create pull request` 按钮进行创建。 至此，您的 PR 创建完成，更多关于 PR 请阅读 [collaborating-with-issues-and-pull-requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) * 5. 冲突解决 @@ -297,13 +263,13 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 步骤一：切换至主分支 ``` - git checkout master + git checkout develop ``` 步骤二：同步远端主分支至本地 ``` - git pull upstream master + git pull upstream develop ``` 步骤三：切换回刚才的分支（假设分支名为 fix） @@ -315,7 +281,7 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 步骤四：进行 rebase ``` - git rebase -i master + git rebase -i develop ``` 此时会弹出修改记录的文件，一般直接保存即可。然后会提示哪些文件出现了冲突，此时可打开冲突文件对冲突部分进行修改，将提示的所有冲突文件的冲突都解决后，执行 @@ -330,7 +296,7 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 ``` git push -f origin fix ``` - - 2.需提交的内容：（昊男确认） + - 2.需提交的内容： - Issue 类型：New Feature - 1.提交中英文版本的用户手册和代码修改的 pr。 @@ -340,46 +306,32 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 - 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 或集成测试IT，尽量覆盖多的用例。 * 提交代码和 UT，一般不需要修改用户手册。最好提交相关实验结果，其中包含量化的改进效果和带来的副作用。 - Issue 类型：Bug * 需要编写能够复现此 bug 的 单元测试 UT 或集成测试 IT。 - * 3.代码管理 （昊男确认） + * 3.代码管理 * a.分支管理： - * IoTDB 版本命名方式为：0.大版本.小版本。例如 0.12.4，12 就是大版本，4 是小版本。 + * TsFile 版本命名方式为：1.大版本.小版本。例如 1.1.2，1 就是大版本，2 是小版本。 - master 分支作为当前主开发分支，对应下一个未发布的大版本，每个大版本发布时会切出一个单独的分支归档，如 0.12.x 系列版本的代码处于 rel/0.12 分支下。 + develop 分支作为当前主开发分支，对应下一个未发布的大版本，每个大版本发布时会切出一个单独的分支归档，如 1.1.x 系列版本的代码处于 rc/1.1 分支下。 - 后续如果发现并修复了某发布版本的 bug。对这些 bug 的修复都需要往大于等于该版本对应的归档分支提 pr。如一个关于 0.11.x 版本 bug 修复的 pr 需要同时向 rel/0.11、rel/0.12 和 master 分支提交。 * b.代码格式化: * 提交 PR 前需要使用 mvn spotless:apply 将代码格式化，再 commit，不然会导致 ci 代码格式化检查失败。 - * c.注意事项: - * iotdb-datanode.properties 和 IoTDBConfig 默认值需要保持一致。 - * 如果需要对配置参数进行改动。以下文件需要同时修改： - 1. 配置文件：iotdb-core/datanode/src/assembly/resources/conf/iotdb-datanode.properties - 2. 代码：IoTDBDescriptor、IoTDBConfig - 3. 文档：apache/iotdb-docs/src/UserGuide/{version}/Reference/DataNode-Config-Manual.md、apache/iotdb-docs/src/zh/UserGuide/{version}/Reference/DataNode-Config-Manual.md - 如果你想要在 IT 和 UT 文件中对配置参数进行修改，你需要在 @Before 修饰的方法里修改，并且在 @After 修饰的方法里重置，来避免对其他测试的影响。合并模块的参数统一放在CompactionConfigRestorer 文件里。 * 4. PR 命名 - * 命名方式：分支标签-Jira 标签-PR 名 + * 命名方式：分支标签 - PR 名 - 示例： [To rel/0.12] [TsFile-1907] implement customized sync process: sender + 示例： [To rc/1.1] implement customized sync process: sender * 分支标签 - 如果是向非 master 分支提 pr，如 rel/0.13 分支，需要在 pr 名写上 [To rel/0.13]。如果是指向master分支，则不需要写分支标签。 - - * Jira 标签 + 如果是向非 develop 分支提 pr，如 rc/1.1 分支，需要在 pr 名写上 [To rc/1.1]。如果是指向 develop ，则不需要写分支标签。 - 以 JIRA 号开头，如：[TsFile-1907] implement customized sync process: sender。这样创建 PR 后，机器人会将 PR 链接自动链到对应 issue 上。 - - 注：如果创建 PR 时忘记添加 JIRA 号，或 JIRA 号不规范，则 PR 不会被自动链接到 Jira 上，需要先改正 PR 命名，并手动将 PR 链接贴到 issue 页面（通过留言或链接框）。 * 5. PR 描述 通常 PR 名无法涵盖所有改动，需要添加具体描述，改动了哪些内容。对于较难理解的地方给予一定的解释。 @@ -390,7 +342,7 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 #### 审阅PR - 注意事项： - - 1. PR命名是否规范，新功能和bug修复类型的pr是否带了JIRA 号。 + - 1. PR命名是否规范。 - 2. PR 描述是否清晰。 - 3. 功能测试用例或性能测试报告是否附上。 - 4. 新功能是否有用户手册。 @@ -407,8 +359,6 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 - 选择 squash merge （当且仅当作者仅有一个提交记录，且记录的commitlog清晰，可选择rebase）。 -- 到 JIRA 上关闭对应的 issue，标记修复或完成的版本【注意，解决或关闭 issue 都需要对 issue 添加 pr 或描述，通过 issue 要能够追踪这个任务的变动】。 - ### 贡献文档 贡献用户手册和贡献代码的流程是一样的，只是修改的文件不同。 @@ -449,4 +399,4 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 - 每日构建: https://ci-builds.apache.org/job/IoTDB/job/IoTDB-Pipe/job/master/ -- Slack: https://apacheiotdb.slack.com/join/shared_invite/zt-qvso1nj8-7715TpySZtZqmyG5qXQwpg#/shared-invite/email \ No newline at end of file +- Slack: https://apacheiotdb.slack.com/join/shared_invite/zt-qvso1nj8-7715TpySZtZqmyG5qXQwpg#/shared-invite/email From 30f6034057bf801d537722b19a8f7dbd797c8882 Mon Sep 17 00:00:00 2001 From: Haonan Date: Tue, 12 Mar 2024 11:00:27 +0800 Subject: [PATCH 3/3] Update Development-Guide.md --- docs/src/zh/Development/Development-Guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/src/zh/Development/Development-Guide.md b/docs/src/zh/Development/Development-Guide.md index bd9d644d0..e2c1edc74 100644 --- a/docs/src/zh/Development/Development-Guide.md +++ b/docs/src/zh/Development/Development-Guide.md @@ -49,7 +49,7 @@ - 1.给发布版本投票 - 2.下载投票的版本/rc下所有内容 - * https://dist.apache.org/repos/dist/dev/iotdb/ + * https://dist.apache.org/repos/dist/dev/tsfile/ - 3.导入发布经理的公钥 @@ -140,11 +140,11 @@ * 验证签名和哈希值 ``` - gpg2 --verify apache-iotdb-0.12.0-bin.zip.asc apache-iotdb-0.12.0-bin.zip + gpg2 --verify apache-tsfile-1.0.0-bin.zip.asc apache-tsfile-1.0.0-bin.zip 出现 Good Singnature - shasum -a512 apache-iotdb-0.12.0-bin.zip + shasum -a512 apache-tsfile-1.0.0-bin.zip 和对应的 .sha512 对比，一样就可以。 ``` @@ -173,7 +173,7 @@ ``` ### 贡献代码 #### 贡献流程： - - Apache IoTDB 社区通过 JIRA 上的 issue 进行任务管理。 + - Apache TsFile 社区通过 JIRA 上的 issue 进行任务管理。 Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审阅 pr -> 合并 pr -> 关闭 issue。 #### 创建 issue ：（xy确认方式） @@ -183,11 +183,11 @@ Issue 的完整生命周期：创建 issue -> 认领 issue -> 提交 pr -> 审 #### 认领 issue ：（xy确认方式） - 在 JIRA 上认领 issue：分配给自己。建议添加一句评论：I'm doing this。避免与其他贡献者重复开发。 - 注：如果发现自己无法认领issue，则是因为自己的账户权限不够。遇到此情况，请向 dev@iotdb.apache.org 邮件列表发送邮件，标题为： [application] apply for permission to assign issues to XXX， 其中XXX是自己的JIRA用户名。 + 注：如果发现自己无法认领issue，则是因为自己的账户权限不够。遇到此情况，请向 dev@tsfile.apache.org 邮件列表发送邮件，标题为： [application] apply for permission to assign issues to XXX， 其中XXX是自己的JIRA用户名。 #### 提交PR - 1.如何提交代码 - 贡献途径： - - IoTDB 诚邀广大开发者参与开源项目构建，您可以查看 [issues](https://issues.apache.org/jira/projects/IOTDB/issues) 并参与解决，或者做其他改善。 + - TsFile 诚邀广大开发者参与开源项目构建，您可以查看 [issues](https://issues.apache.org/jira/projects/IOTDB/issues) 并参与解决，或者做其他改善。 - 提交 pr，通过 GitHub actions 测试和 Sonar 代码质量检测后，至少有一位以上 Committer 同意且代码无冲突，就可以合并了 - PR指南： - 在 Github 上面可以很方便地提交 [Pull Request (PR)](https://help.github.com/articles/about-pull-requests/)，下面将以本网站项目 [apache/tsfile](https://github.com/apache/tsfile) 为例