写点什么

开源指南|如何从零开始参与 Apache 顶级开源项目?(二)

作者:SelectDB
  • 2022 年 9 月 15 日
    北京
  • 本文字数:7617 字

    阅读完需:约 25 分钟

开源指南|如何从零开始参与 Apache 顶级开源项目?(二)

作者:苏奕嘉|SelectDB 生态研发工程师

写在开头

上一篇文章 如何从零开始参与 Apache 顶级开源项目?我们介绍了 Apache Doris 社区的工作机制、如何参与社区贡献以及如何完成第一个 PR,更多是从大而全的角度来介绍参与开源项目的一些定式,希望能为新人开发者提供一个简单的思路。


思路固然重要,而详细的指引也是新人开发者真正参与开源的关键,在本篇文章中,我们将会为大家介绍以下内容:

  1. 参与 Apache Doris 开发至少需要掌握哪些技术栈

  2. Apache Doris 开发环境搭建

  3. 代码结构介绍以及代码改动

  4. 如何进行文档贡献

  5. 如何提交一个合格的 PR

  6. 如何解决冲突以及 Rebase 代码

  7. ci 检查失败该如何处理


本文将通过以上内容为新人开发者提供一个详尽的入门指引,希望有更多热爱开源的小伙伴可以加入到 Apache Doris 社区中,无论是文档贡献或代码开发,亦或是参与宣传推广和分享应用案例,都是社区非常欢迎的贡献方式。那么接下来我们将展开各项详细说明。

第 0 步:掌握技术栈

Apache Doris 的系统架构非常精简,只有 Frontend(FE) 和 Backend(BE) 两类进程,FE 节点主要负责用户请求的接入、查询解析规划、元数据的管理以及节点管理相关工作,BE 节点主要负责数据存储、查询计划的执行。


除此以外,Apache Doris 不依赖任何其他的组件,例如不依赖 HDFS 进行数据存储、不依赖 Zookeeper 进行分布式管控,相对于 Druid、Clickhouse 之类的 OLAP 数据库,Apache Doris 架构精简的优势极大的降低了运维压力,同时,Doris 无论是在升级还是扩缩容方面都更加的便捷。


FE 由 Java 语言编写, BE 出于性能考虑使用 C++ 语言实现, 开发 过程中 必备 技术栈 包括


  • FE:Java、Maven

  • BE:C++

第 1 步:Apache Doris 开发环境搭建

Apache Doris 主要代码语言为 Java 和 C++,我们分别就 FE 和 BE 的开发环境搭建进行说明。


FE 开发环境


FE 中的 Java 代码由 Maven 管理,推荐使用 IntelliJ IDEA 进行开发,

IntelliJ IDEA 的开发环境搭建可以参阅 官方文档

https://doris.apache.org/zh-CN/community/developer-guide/fe-idea-dev


在工程创建完成后,建议配置 IDEA 如下两个功能,以方便通过代码格式检查:

  • Editor -> Code Style -> Java 中配置 Imports Order。

  • Imports Order 的具体顺序可参阅 官方文档 ,链接:

  • https://doris.apache.org/zh-CN/community/developer-guide/java-format-code

  • Save Actions 设置保存时自动格式化。建议在格式化选项中仅勾选 Optimize importsReformat only changed code ,以保证 Import 顺序,同时避免未变更的代码被自动格式化。


BE 开发环境

BE 开发环境请参阅 官方文档 :

https://doris.apache.org/zh-CN/community/developer-guide/be-vscode-dev


BE 的代码自动格式化请参阅 官网文档 ,链接:

https://doris.apache.org/zh-CN/community/developer-guide/cpp-format-code


Apache Doris 使用 clang-format 进行代码格式化,并在 build-support 目录下提供了封装脚本:

  • clang-format.sh.


  • 格式化 be/srcbe/test 目录下的 C/C++ 代码。


  • check-format.sh.


  • 检查 be/srcbe/test 目录下的 C/C++ 代码格式,并将 diff 输出,但不会修改文件内容。

第 2 步:代码结构介绍及代码改动

代码结构介绍

我们将介绍 Apache Doris Master 分支为例的代码模块都有哪些,便于大家快速检索。


master-``9a74ad1 为例,根目录索引如下:


├── be                  // BE 代码目录├── bin                 // FE/BE 的启停脚本├── build_plugin.sh     // FE 插件编译脚本├── build.sh            // Doris 编译脚本├── build-support       // 编译用辅助脚本├── CODE_OF_CONDUCT.md  // 贡献者代码行为准则├── conf                // FE/BE 的配置文件├── contrib             // 第三方贡献代码,如 udf├── CONTRIBUTING_CN.md  ├── CONTRIBUTING.md├── DISCLAIMER├── dist                // 许可证目录├── docker              // Doris 开发镜像的 Dockerfile├── docs                // 文档目录├── env.sh├── extension           // 扩展功能代码,如 flink connector 等├── fe                  // FE 代码目录├── fe_plugins          // FE 插件目录├── fs_brokers          // Broker 代码目录├── gensrc              // thrift/protobuf 等代码生成目录├── LICENSE.txt├── NOTICE.txt├── README.md├── regression-test     // 回归测试目录├── run-be-ut.sh        // BE 单元测试运行脚本├── run-fe-ut.sh        // FE 单元测试运行脚本├── run-tegression-test.sh├── samples             // 示例代码目录├── thirdparty          // 第三方依赖库目录├── tools               // 一些辅助工具├── tsan_suppressions├── ui                  // FE 前端代码目录└── webroot             // 一些静态网页相关代码
复制代码


使用中经常涉及到的开发目录有:


  1. FE 代码目录:fe/


  1. BE 代码目录:be/


  1. Thrift 等代码生成目录:gensrc/


  1. 扩展功能代码目录:extension/


  1. 回归测试目录:regression-test/

FE
├── check├── fe-common   // 一些 FE 模块的通用代码├── fe-core     // FE 模块主代码├── hive-udf    // hive-udf 模块代码├── java-udf    // java-udf 模块代码├── pom.xml├── README└── spark-dpp   // Spark Load 所依赖的 Spark 导入程序代码
复制代码


fe-core 目录下是 FE 的代码核心模块。


├── main            │   ├── cup         // 语法定义文件│   ├── java        // 主代码│   ├── jflex       // 词法定义文件│   ├── antlr4      // 词法分析器│   └── resources└── test             // 单元测试    ├── java    └── resources
复制代码


在主代码路径下,也就是上述树状的 main/java/org/apache/doris/ 目录下,有如下的主要代码部分:


├── alter         // 表结构变更操作相关的代码。包括表结构变更,物化视图等。├── analysis      // 包含所有SQL语法的java实例类├── backup        // 备份恢复操作相关的代码├── blockrule     // SQL 黑名单相关代码├── catalog       // 包含元数据操作的主类和各种数据库、表、分区的元数据实例类├── clone         // 数据副本修复和均衡相关的代码├── cluster       // 已废弃├── common        // 一些工具类和通用定义├── consistency   // 数据一致性校验相关的代码├── deploy        // 部署相关代码├── external      // Doris on Elasticsearch相关的代码├── ha            // 元数据高可用相关的代码├── http          // http v1 代码├── httpv2        // http v2 代码(逐步替换v1)├── journal       // 元数据日志相关的代码├── ldap          // LDAP 认证相关代码├── load          // 导入作业相关代码├── master        // FE Master角色相关的操作代码,如元数据Checkpoint,BE任务汇报的处理等。├── metric        // FE 监控指标相关的代码├── monitor       // JVM 监控相关代码├── mysql         // MySQL协议层相关代码├── nereids       // 优化器相关代码├── PaloFe.java   // Main函数入口├── persist       // 元数据持久化相关的代码├── planner       // 查询优化器相关的代码├── plugin        // Frontend端插件管理相关代码├── policy        // 存储策略相关代码├── qe            // 用于处理各类SQL请求相关的代码。如查询请求的处理类、DDL请求的处理类等├── resource      // 资源标签相关的代码├── rewrite       // 查询优化器重写规则相关的代码├── rpc           // Frontend和Backend之间RPC协议相关的代码├── service       // Frontend侧各种服务器端代码├── statistics    // 统计信息相关代码├── system        // 集群节点的实例类和集群节点管理相关的代码├── tablefunction // 表函数相关代码├── task          // Frontend发往Backend的各类任务相关的代码└── transaction   // 导入事务相关代码
复制代码
BE
├── CMakeLists.txt  // CMake 编译文件├── src             // 主代码目录└── test            // 单元测试
复制代码


其中,主要代码目录包含如下内容:


├── agent                   // FE 下发的 agent task 相关处理类├── common                  // 通用类├── env                     // 文件系统操作类├── exec                    // 执行算子相关代码├── exprs                   // 表达式、函数计算相关代码├── gen_cpp                 // ├── geo                     // 地理位置函数相关代码├── glibc-compatibility     // GLIBC 兼容代码├── gutil                   // Google gutil 相关代码├── http                    // BE 端 http server 相关代码├── io                      // ├── olap                    // 存储层代码├── runtime                 // 查询层运行时相关代码├── service                 // BE 对外服务接口相关代码├── tools                   // 辅助工具相关代码├── udf                     // 用户自定义函数相关代码├── util                    // 一些工具类└── vec                     // 
复制代码


gensrc


├── Makefile├── proto       // protobuf 定义文件├── script      // 一些辅助脚本,包括函数定义代码生成模板等└── thrift      // thrift 定义文件
复制代码


extension


├── DataX                   // DataX doriswriter 插件├── dbt-doris               // DBT 插件├── logstash                // logstash 导入插件└── mysql_to_doris          // MySQL 导入插入
复制代码


regression-test


├── common         // 回归测试框架通用代码├── conf           // 配置类文件├── data           // 测试结果集├── framework├── plugins        // 插件目录├── script         // 脚本目录└── suites         // 测试代码目录
复制代码


如果对以上某个模块感兴趣,均可以通过目录检索对照完成快速定位。

代码改动

这里的代码改动不仅指 Java / C++ / Python 等编程语言的改动,文档内容改动、代码注释改动等,也都属于代码改动范畴,所述代码改动均可以通过目录检索定位到对应的位置来修改。


举例:

  • 文档修改,需要到 /docs 目录下修改对应的 .md 文件。


  • 代码修改,到指定目录下修改相应的文件内容。

第 3 步:参与文档贡献

在 Apache Doris 官网目前的文档结构中,文档被分为历史文档与 dev 文档。在开发过程如果发现文档勘误,需要在不同仓库目录下对文档提交修改。


其中,历史文档有 0.15 和 1.1 两个版本号,文档版本号与 Apache Doris 内核版本保持一致,位于 https://github.com/apache/doris-website


Website 代码目录结构可以参考链接:https://doris.apache.org/zh-CN/community/how-to-contribute/contribute-doc


dev 文档与当前 Master 版本一致,位于 https://github.com/apache/doris/tree/master/docs


  • 如果需要修改的文档只涉及当前 dev 版本,直接在 Master 上进行修改并提交 PR 。


  • 如果需要修改的文档同时出现在 dev 版本及历史版本中,则需要分别在 doris-website 和 apache/doris 两个代码仓库提交 PR。


举例说明:


1) 文档修改。 以下面文档示例,在 Apache Doris 官网中,我们发现有一篇文章的描述出现错误,需要删除该内容。

首先在 apache/doris 代码仓库的 master 分支中找到对应的该文档,中文文档在 docs/zh-CN/docs/data-table/data-partition.md ,找到需要删除的语句描述进行删除。



英文文档在 docs/en/docs/data-table/data-partition.md ,步骤如上,删除对应英文描述。



需要注意的是:文档类的修正 定需要同时修改中文和英文 两个 文档 修改后,分别创建 Pull Request 进行提交。


2) 提交 Blog 目前 Apache Doris 官网提供了 Blog 功能,欢迎所有人分享优质技术内容到官网 Blog 中。Blog 不区分文档版本,所有版本通用, 因此 只需要在 apache/doris-website 中提交一次 PR 无需在多个版本中重复提交。


中英文 Blog 处于不同的目录下,英文博客位于根目录下的 Blog 中,链接 https://github.com/apache/doris-website/tree/master/blog。中文博客目录在 i18n/zh-CN/docusaurus-plugin-content-blog 。提交 Blog 时,只需要将中英博客对应的 markdown 文件分别置于两个目录下,需要注意的是,中英文博客的文件名称需要保持一致。

第 4 步:如何提交一个合格的 PR

看到这一步,相信有很多小伙伴已经迫不及待要开始代码提交之路,先别着急,还有一些问题需要解决。比如:如何快速找到想要改动或者擅长的代码模块呢?


接下来 介绍 如何提交代码到远端 完成一个合格的 PR


严格来讲,提交本地改动到 Remote 端的步骤是三步:


  1. add 文件

  2. commit 暂存提交

  3. push 推送远端


如果 使用的 是 Git 命令行工具,应执行以下的通用流程:


git add <file>git commit -s -m "some description here"git push origin feat-xxx
复制代码


  1. add <file> :添加本次改动的文件目录,如果想添加所有改动文件,不需要一一指定,使用 git add --all 即可。

  2. commit 暂存提交:将暂存提交内容和描述信息到本地,-s 参数一定要添加,-m 参数后面是本次提交内容的描述信息。

  3. push 推送远端:是执行推送本地改动到远端的动作, feat-xxx 代表要提交的分支,还有一些参数,如 -f 参数,作用在当 commits 记录不满意,仍需强制覆盖远程分支的参数,根据具体情况灵活调整。


如果使用的是 Git GUI 工具,如 IDE 的 Git 插件,SourceTree、SmartGit、TorToiseGit 等,根据相对应的功能模块按步骤操作即可。


以上面修改的文档提交为例,我们执行如下操作:


cd dorisgit add docs/zh-CN/docs/data-table/data-partition.mdgit add docs/en/docs/data-table/data-partition.mdgit commit -s -m "Fixed incorrect description of column length limit in partition bucketing documentation."git push origin docs-data-table
复制代码


可以注意到, commit 描述都是用英文,鼓励大家使用英文描述来提交 commit 以及 PR 。



当进行提交时如果提示输入 GitHub 账号名和密码,输入后又提示鉴权失败,原因是未配置 SSH 免密机器,需要在账户 settings 中创建 token 来当做密码,具体流程不再赘述。成功后提示如下:



提交后,我们回到个人 Gitgub 账户下 Fork 后的代码库,发现有黄色提示框来提示有改动,我们可以创建一个 PR 来回归上游代码库,操作如下:


点击按钮 Compare & pull request 创建一个 PR。



一个合格的 PR 内容,应该有三部分组成:


  1. 正确的分支指向,即你当前修正的分支提交到目标源仓库分支,这里我们是从 FreeOnePlus/doris/docs-data-table 分支回归合并到 apache/doris/master 分支来。

  2. 正确的标题名称,不同的改动内容,需要配以不同的类型标题来进行划分,如果不按如下的通用格式书写,会导致 PR 合入失败,格式应为:[<type>](<scope>) <subject> (#pr),比如文档标题应以 [docs] 开头,如我们示例的这次改动,应该命名为: [docs](docs)Partition table document correction 或者 [docs]Partition table document correction。如果是 Bug 修复的代码改动,那应该以 [fix] 作为标题前缀,(<scope>)一定要有,更多类型可以阅读官方文档(https://doris.apache.org/zh-CN/community/how-to-contribute/commit-format-specification/)来了解。

  3. 详略得当的修改内容说明,往往开源社区会预制一个模板,目标是清晰的描述修改内容,以便于 review 同学和其他同学能更快的了解你做的改动,按文档内容要求来填写即可。参考如下:



合格的 PR 三部分完成后,即可点击右下角的 Create pull request 按钮完成 PR 创建。提交 PR 成功后,跳转至 PR 详情页,这时候需要注意 ci 检查是不是全部能够通过,假如失败了,需要及时修复。


第 5 步:如何解决冲突

提交 PR 时发生代码冲突一般是由于多人编辑同一个文件引起的,解决冲突主要通过以下步骤即可:

(1)切换至主分支

git checkout master
复制代码

(2)同步远端主分支至本地

git pull upstream master
复制代码

(3)切换回刚才的分支(假设分支名为 fix)

git checkout fix
复制代码

(4)进行 rebase

git rebase -i master
复制代码


此时会弹出修改记录的文件,一般直接保存即可。会提示哪些文件出现了冲突,此时可打开冲突文件对冲突部分进行修改,将提示的所有冲突文件的冲突都解决后,执行


git add .git rebase --continue
复制代码


依此往复,直至屏幕出现类似 rebase successful 字样即可,此时您可以进行往提交 PR 的分支进行更新:


git push -f origin fix
复制代码

第 6 步:ci 检查如何处理和修改

如果 PR 没有问题,通过 Reviewers 进行 Review 以后,很快会将 PR 合并进去,这样 PR 的生命周期也就到此结束了,如果社区其他同学提出了疑问,他们或许会在 PR 底下的评论区提出自己的质疑,记得要及时响应。


如果代码改动没有被合入,Reviewer 指出了问题所在,需要进一步修改时,无需重新走一遍流程创建一个新的 PR 进行改动,更无需从 Fork 仓库开始。


只需要在本地继续修改即可,修改成后将改动 commit & push 到远端, PR 会自动追踪和更新内容, Reviewers 进行二次 review 即可,修改后需要至少一个非作者的 Committer 给出 LGTM 或者 +1 后方可合并入。

Enjoy it again!

参与开源项目的方式是多种多样的,无论是提交 Issue 或参与 PR Review,或是修改和完善文档,亦或是分享技术博客和应用案例,都是参与开源贡献的一种方式。


同时,有很多不起眼、但富有意义的工作希望得到更多开发者的帮助:


  • 在即将发布的 1.2 版本中将会支持 Java UDF,欢迎参与编写 Java UDF;

  • 在回归测试库中有大量测试 Case ,大多需要编写 SQL 脚本来完成功能和性能测试的,非常欢迎根据自己的业务场景提供回归测试 Case 来帮助 Doris 发版更加稳定。

  • 还有诸如各种 build.sh、build_plugins.sh 、docker-compose.yaml 、dockerfile 等脚本,等你来改进和新增。

  • 发现文档内有描述谬误、解释不清、示例错误、排版问题甚至错别字和错误的标点符号,都可以提交 PR 参与到对 Apache Doris 的贡献中来。


与此同时,Apache Doris 社区特别欢迎所有用户根据自己的业务来书写相应的最佳实践文档,或者在使用过程中对某个功能或者某个模块的详细使用文档,比如《 MySQL 数据迁移至 Doris 的最佳实践》等。


综上,贡献 Apache Doris 所需要的技术栈并非一定是工程能力的技术栈,也可以在非代码贡献层面做些力所能及的事情, 我们欢迎开源爱好者参与到社区中来。

发布于: 刚刚阅读数: 4
用户头像

SelectDB

关注

极速易用 开源开放 2022.04.20 加入

The enterprise-grade cloud-native distribution for Apache Doris.

评论

发布
暂无评论
开源指南|如何从零开始参与 Apache 顶级开源项目?(二)_数据库_SelectDB_InfoQ写作社区