开源指南｜如何从零开始参与 Apache 顶级开源项目？（二）
作者：苏奕嘉｜SelectDB 生态研发工程师
写在开头
上一篇文章 如何从零开始参与 Apache 顶级开源项目？ 我们介绍了 Apache Doris 社区的工作机制、如何参与社区贡献以及如何完成第一个 PR，更多是从大而全的角度来介绍参与开源项目的一些定式，希望能为新人开发者提供一个简单的思路。
思路固然重要，而详细的指引也是新人开发者真正参与开源的关键，在本篇文章中，我们将会为大家介绍以下内容：
[*]参与 Apache Doris 开发至少需要掌握哪些技术栈
[*]Apache Doris 开发环境搭建
[*]代码结构介绍以及代码改动
[*]如何进行文档贡献
[*]如何提交一个合格的 PR
[*]如何解决冲突以及 Rebase 代码
[*]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 imports 和 Reformat 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/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 // 一些静态网页相关代码
使用中经常涉及到的开发目录有：
[*]FE 代码目录：fe/
[*]BE 代码目录：be/
[*]Thrift 等代码生成目录：gensrc/
[*]扩展功能代码目录：extension/
[*]回归测试目录：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 端的步骤是三步：
[*]add 文件
[*]commit 暂存提交
[*]push 推送远端
如果 使用的 是 Git 命令行工具，应执行以下的通用流程：
git add <file>
git commit -s -m "some description here"
git push origin feat-xxx
[*]add <file> ：添加本次改动的文件目录，如果想添加所有改动文件，不需要一一指定，使用 git add --all 即可。
[*]commit 暂存提交：将暂存提交内容和描述信息到本地，-s 参数一定要添加，-m 参数后面是本次提交内容的描述信息。
[*]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 内容，应该有三部分组成：
[*]正确的分支指向，即你当前修正的分支提交到目标源仓库分支，这里我们是从 FreeOnePlus/doris/docs-data-table 分支回归合并到 apache/doris/master 分支来。
[*]正确的标题名称，不同的改动内容，需要配以不同的类型标题来进行划分，如果不按如下的通用格式书写，会导致 PR 合入失败，格式应为：[<type>](<scope>) <subject> (#pr)，比如文档标题应以 开头，如我们示例的这次改动，应该命名为： (docs)Partition table document correction 或者 Partition table document correction。如果是 Bug 修复的代码改动，那应该以 作为标题前缀，(<scope>)一定要有，更多类型可以阅读官方文档（https://doris.apache.org/zh-CN/community/how-to-contribute/commit-format-specification/）来了解。
[*]详略得当的修改内容说明，往往开源社区会预制一个模板，目标是清晰的描述修改内容，以便于 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 所需要的技术栈并非一定是工程能力的技术栈，也可以在非代码贡献层面做些力所能及的事情， 我们欢迎开源爱好者参与到社区中来。
https://my.oschina.net/u/5735652/blog/5577980
页:
[1]