乐趣区

关于开源:开源指南｜如何从零开始参与-Apache-顶级开源项目二

jiezi

作者：苏奕嘉|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-C…

在工程创立实现后，倡议配置 IDEA 如下两个性能，以不便通过代码格局查看：

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

    •   Imports Order 的具体程序可参阅 官网文档，链接：
    •   https://doris.apache.org/zh-C…
  • 在 Save Actions 设置保留时主动格式化。倡议在格式化选项中仅勾选 Optimize imports 和 Reformat only changed code，以保障 Import 程序，同时防止未变更的代码被主动格式化。

BE 开发环境

BE 开发环境请参阅 官网文档，链接：

https://doris.apache.org/zh-C…

BE 的代码主动格式化请参阅 官网文档，链接：

https://doris.apache.org/zh-C…

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

  • clang-format.sh.

<!—->

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

<!—->

  • check-format.sh.

<!—->

  • 查看 be/src 和 be/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/dor… 仓库中

Website 代码目录构造能够参考链接：https://doris.apache.org/zh-C…

dev 文档与以后 Master 版本统一，位于 https://github.com/apache/dor…

  • 如果须要批改的文档只波及以后 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/dor…。中文博客目录在 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 doris
git add docs/zh-CN/docs/data-table/data-partition.md
git add docs/en/docs/data-table/data-partition.md
git 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-C…）来理解。
  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 所须要的技术栈并非肯定是工程能力的技术栈，也能够在非代码奉献层面做些力不从心的事件，咱们欢送开源爱好者参加到社区中来。

退出移动版