摘要： 成为开源项目贡献者，可能是多数开发者的一个小目标。但是，已经 2025 年了，拼写错误都被人改的差不多了，还有哪些途径可以成为开源项目贡献者？都已经 2025 年了，又能上哪里找到适合新手参与的开源项目，又是顶级开源项目呢？本文将结合作者个人经验，为你提供一份详细指南，不标题党，不忽悠，每天投入一小时，与你携手七天成为 Apache 顶级开源项目的贡献者。
如何选择一个开源项目
每个开源项目都有一定的问题列表，会罗列一些项目中的 Bug 清单或 Feature 清单。有些项目会直接使用 Github 的 Issues 功能进行管理，也有的项目会通过 JIRA 等软件管理。
如果是初次尝试参与开源项目，个人建议选择通过 Github 的 Issues 管理 Bug/Feature 清单的项目。并寻找主要由国人主导的项目，因为这类项目通常对初次尝试参与开源贡献的新人比较友好。
之后我们需要查看项目的活跃度，一定要选择活跃的社区，如果在过程中遇到问题，也会感受到更多的支持。活跃度可评判的依据比较多，一方面是可通过 Insights 查看近期 commit，以及贡献者数，另一方面可通过 Pull requests 与 issue 的处理速度来判断。
接下来才是确认是否能够参与其中的关键，查看 Issues。可以通过 good first issue、volunteer wanted 或者 easy、first等 关键字对应 label 进行筛选。如果过滤后打上这类标签的 Issue 比较多，那么便可以从中筛选适合自己的任务。
建议优先选择没有 Assignee 的 issue，通常这类 issue 都是暂时无人认领的。如果发现自己能解决的 issue 恰好有人认领的话，也不要担心，先看看该 issue 的更新时间，如果更新时间比较久，比如半年或一年前，那么可以在 issue 中留言询问并 @ 项目组成员是否可重新分配给自己。这种情况下通常时前人半途而废了，一般情况下项目组成员都会很乐意重新分配的。
对于从事开发工作不久的同学来讲，如果我们对于开源组件或框架的使用有限。在这种情况下，可以先尝试扩充对开源项目的认识。可以通过比较知名的软件基金会来了解，像是 Apache 和 CNCF 等。可以通过 Apache 项目列表（Apache Github 仓库列表）和 CNCF 的 Landscape 来扩充对开源项目的认知。
我个人便是通过上述方式找到了 ShardingSphere，从 0 到 1 完成了 3 个 issue。截止目前 ShardingSphere 项目中还有许多适合初次参与开源项目的 good first issue，除了少部分时间更早的补充单元测试相关的 issue 外，还有大量的 Doris 语法验证与修复 issue 等待大家参与。
先叠个甲，本文并非广告。 单纯是看到这些适合新人，却又长期无人处理的 issue 略感遗憾。但是因为此前我已经修复过类似 issue ，所以不想借此刷 commit 数量，又希望能有更多人迈出第一步，真正参与到开源项目中。
如果你也想尝试为顶级开源项目贡献一点力量的话，可以凭 ShardingSphere 作为起步。接下来的内容，我将结合个人经验以 Doris SQL 的验证与修复为切入点（截止 2025 年 1 月 1 日相关 issue 还比较多，具体看链接），带领大家一步步实现开源项目的贡献。理想情况下，每天拿出 1 个小时的时间，一周便可以完成一个 issue 。让我们开始吧！
第一步：阅读指南与本地开发环境初始化
一旦我们决定为某个项目贡献，首先我们需要查看该项目社区中 “贡献者指南 ” 和 ”开发环境指南“ 相关文档。一个为了了解并遵循社区的开发流程与规范，参与贡献。另一个为了我们能够顺利启动本地开发环境，进行开发。
其中 ShardingSphere 的相关文档链接如下：
如果已经在 GitHub 上 fork 过相应项目，后续如果想再次贡献，可以在自己的仓库下，点击 Sync fork 按钮执行代码库之间的同步，更新项目最新代码。
将 ShardingSphere clone 到本地后，参照文档在工程根目录执行以下命令，完成依赖与部分生成式代码的安装与编译：
./mvnw clean install -DskipITs -DskipTests -Prelease
并通过如下命令建立相应分支：
git checkout master
git fetch apache
git rebase apache/master
git push origin master # 可选操作
git checkout -b issueNo
如果你日常使用 IntelliJ IDEA 作为开发工具，执行完上述操作后，工程中理论上应该不会再有错误提示。可以执行后续操作了。
因为 ShardingSphere 的 SQL 解析相关功能基于 ANTLR 实现，通过遍历由 ANTLR 生成的 SQL 语法树加工处理 SQL 语句。而我们的工作是严重 SQL 语句的解析，那么需要通过插件市场搜索并安装 ANTLR v4 插件，利用该插件帮助我们验证编写的 ANTLR 语法文件（.g4 文件）是否正确。
至此，我们的开发环境便准备完毕，接下来需要处理验证环境。因为我们要验证对 Doris 的 SQL 解析是否正确，所以需要能够在本地运行 Doris ，接下来以 Docker 运行 Doris 为例进行讲解。
因为 Apache Doris 在 Docker Hub 上提供的官方镜像为编译镜像，并非应用。我们采用通过第三方发布的镜像，主页链接和相关命令如下：
docker pull yagagagaga/doris-standalone:3.0.3
镜像比较大，耐心等待后可执行下方命令启动，或根据上方提供的主页链接选择相应命令：
docker run -itd --privileged=true --name my-doris -p 8030:8030 -p 8040:8040 -p 9030:9030 yagagagaga/doris-standalone
启动需要一定时间，一定要耐心等待，直到看到启动如下信息，可以认为已成功启动：
==========================================================
Everything is ready, enjoy!
==========================================================
FE WebUI: http://127.0.0.1:8030/
BE WebUI: http://127.0.0.1:8040/
MySQL : mysql -uroot -h127.1 -P9030
JDBC : jdbc:mysql://127.0.0.1:9030?useSSL=false&useServerPrepStmts=true&cachePrepStmts=true
: jdbc:arrow-flight-sql://127.0.0.1:10030? useServerPrepStmts=false&cachePrepStmts=true&useSSL=false&useEncryption=false
随后可以访问 localhost:8030 登陆 Doris 控制台，账号为 root，初始密码默认为空。登陆后的控制台 Playground 页面如下所示：
至此，我们便完成了开发与验证环境的搭建。
第二步：了解项目工程结构与模块
坦诚地讲， ShardingSphere 的模块划分实在是太多了。如果你是为了解决 Doris SQL 验证相关 issue，那么可以不用了解每个模块的功能。你可以在后续感兴趣的情况下，通过官方源码解读来了解模块之间的关系与作用：
与 SQL 解析相关模块集中在 parser 中，可以按照下面的路径找到 ShardingSphere 所支持的数据存储系统模块，进而找到对应的 SQL 解析语法文件，同时你可以通过下方图片作为辅助参考找到目标文件。
shardingsphere -> parse -> sql -> dialect -> doris
接下来展开 doris 模块，可根据下方图示路径定位所有涉及 Doris 相关 SQL 语句的语法文件。
doris -> src -> main -> antlr4 -> imports -> doris
你可以大致浏览一下上述路径中的 ANTLR 语法文件。通常情况下，我们需要验证的 SQL 所涉及的部分主要集中在 DALStatement.g4、DCLStatement.g4、DDLStatement.g4、和 DMLStatement.g4 中。我们会在下一步中简要介绍 ANTLR ，接下来我们结合下方图示，先介绍一下 ANTLR 插件的使用。
如果你在上一步在 IDEA 中成功安装 ANTLR 插件，那么在语法文件中选择对应的规则并右键后，可以点击 “Test Rule xxx”（其中 xxx 为具体规则名）。会在 IDEA 下方出现 ANTLR Preview 窗口，窗口左上方会显示对应语法文件和规则，当你需要切换不同规则时，需要选中不同的规则并点击 “Test Rule xxx”。一定要确保语法文件和规则的正确选择，尤其是当你发现修改了语法规则却未生效的时候！
之后我们在 ANTLR Preview 窗口左侧文本框中输入相应 SQL ，便会在右侧解析生成语法树。该插件主要是帮助我们：
- 检查对应规则是否能够正常生成语法树；
- 检查生成的语法树是否正确，且符合数据存储系统官方文档的描述；
至此，我们便完成对工程结构模块的了解，以及 ANTLR 插件的使用和用途的了解。
第三步：速成 ANTLR
有了上一步中直观的体验后，这一步，我们对将要使用的 ANTLR 知识做一个简单快速的介绍。同时建议参考 ShardingSphere 社区成员的文档对 ANTLR 形成一个快速上手。
ShardingSphere 中对 ANTLR 的使用也是将语法拆分成两部分：语法分析器语法 和 词法分析器语法 。通常，语法分析器语法定义使用 grammar 进行声明，而词法分析器语法定义则使用 lexer grammar 声明。
上文中提到我们验证 SQL 主要集中在 DALStatement.g4、DCLStatement.g4、DDLStatement.g4、和 DMLStatement.g4 这 4 个文件中，也就是语法分析文件，当然，不排除有修改词法分析文件的情况。
如果你了解 SQL 语句并使用过正则表达式，那么再看语法文件可能会略感熟悉，也大致能够猜出各个规则的含义。我们截取 doris 包下 DMLStatement.g4 文件片段，介绍一下主要的语法规则。代码片段如下：
grammar DMLStatement;
import BaseRule;
insert
: INSERT insertSpecification INTO? tableName partitionNames? (insertValuesClause | setAssignmentsClause | insertSelectClause) onDuplicateKeyClause?
;
insertSpecification
: (LOW_PRIORITY | DELAYED | HIGH_PRIORITY)? IGNORE?
;
insertValuesClause
: (LP_ fields? RP_ )? (VALUES | VALUE) (assignmentValues (COMMA_ assignmentValues)* | rowConstructorList) valueReference?
;
fields
: insertIdentifier (COMMA_ insertIdentifier)*
;
一个语法规则，基本格式结构为 规则名 : 规则组合 ; 。基本上 ShardingSphere 的语法分析文件中，完全由大写字母组成的关键字均是自定义的 “词法”，如代码片段中：INSERT、LP_、RP_、COMMA_ 。其余基本符合驼峰命名的皆为 “语法规则”，如代码片段中：insert、insertSpecification、tableName 等。
面临多个规则组合，匹配顺序为从左到右。括号的含义和其他编程语言等同，余下主要操作符含义如下：
|：表示匹配任意一个，如代码片段中：insertValuesClause | setAssignmentsClause | insertSelectClause ；*：表示匹配零次或多次，如代码片段中：(COMMA_ insertIdentifier)* ；?：表示匹配零次或一次，如代码片段中：(LP_ fields? RP_ )?；+：表示匹配零次或一次。
切记，如果修改了任何 ANTLR 语法文件，都需要我们重新执行上文中提到的 install 命令，好让 ANTLR 根据新的语法文件生成相关运行时文件。
如果修改了 ANTLR 语法文件，大概率需要修改相应 Java 代码。
ANTLR 提供两种针对语法树遍历的机制：语法分析树监听器（Listener） 和 语法分析树访问器（Visitor）。可以粗略的认为一种是被动，另一种为主动。ShardingSphere 采用语法分析树访问器的方式，所以编译工程后会根据 ANTLR 语法文件生成相应 Visitor 类。之后我们只需要继承该 Visitor 类实现我们的自定义内容即可。如下图所示 ShardingSphere 中关于 Doris 的自定义 Visitor 类，这里项目对 Visitor 有更高维度的封装，不过核心原理并没有区别。
如果你仔细观察自定义 Visitor 类，可以发现每个 Visitor 类和 ANTLR 语法文件之间名称的关联性，通过查看类中的方法，也会发现与规则名称的关联性。这有助于我们定位需要修改的具体方法。
之后就是针对语法文件的变化调整代码实现。至此，基于上述 ANTLR 的知识足够我们开启 issue 修复之路。
第四步：验证并修复 ANTLR
在这一步中，我将结合本人此前修复的 MySQL 相关 issue ，讲解验证与修复 ANTLR 语法文件的过程。并在结尾在简单分析一个 Doris 相关 issue ，但不会展开。
首先需要通过本地 Docker 中运行的 MySQL 数据库，验证 issue 中涉及的所有 SQL 语句，是否正确并且在数据库中能够正确执行。之后通过 ANTLR 语法文件执行对应规则，查看是否能够生成正确的语法树。
在此过程中发现 ShardingSphere 在解析下面三条 MySQL 对应 SQL 语句时无法构建语法树：
SELECT * FROM t1 USE INDEX (i1) IGNORE INDEX (i2) USE INDEX (i2);
SELECT * FROM t1
USE INDEX () IGNORE INDEX (i2) USE INDEX (i1) USE INDEX (i2);
SELECT * FROM t1
USE INDEX (i1,i2) IGNORE INDEX (i2);
上述三条 SQL 均属于在使用索引提示时对语法规则的错误。其中一条 SQL 在解析语法树的过程中，错误如下图所示。
首先，我们先定位语法文件 DMLStatement.g4 。之后，通过阅读 MySQL 官方文档，我们确认 USE INDEX 的语法规则：
The syntax for index hints has the following characteristics: （索引提示的语法有以下特点：）
- It is syntactically valid to omit
index_listforUSE INDEX, which means “use no indexes.” Omittingindex_listforFORCE INDEXorIGNORE INDEXis a syntax error.- 在
USE INDEX中省略index_list是允许的，相当于 “不使用索引”。而在FORCE INDEX或IGNORE INDEX中省略index_list则为语法错误。 ）
由此可以得知在 indexHint 语法规则并非通过 , 连接，而且 indexName 可以不填写。于是便可以尝试对该语法规则进行修复，具体修改如下图所示：
当我们修改并完成 ANTLR 语法文件的验证后，==需要通过如下命令重新编译项目==（其实只需要重新编译指定模块便可）。至此便完成对语法文件的修复。
mvn -T 2C clean install -DskipTests
我们选取一个 Doris 相关 issue 中的一条 SQL 进行简单的分析：
ALTER RESOURCE "showPolicy_1_resource" PROPERTIES("s3.connection.maximum" = "1111")
通过 Doris 官方文档 了解 RESOURCE 的含义与相关语法。因为 S3 的 RESOURCE 创建比较麻烦，我们可以试着在本地创建一个 JDBC RESOURCE ，并尝试执行 ALTER RESOURCE 。参考下方图示：
之后我们在 ShardingSphere 进行验证，根据错误提示以及语法文件中所定义的规则，大致能够猜出是没有支持对 RESOURCE 的 ALTER 语句。这个可能会比较麻烦，需要我们参考 alterTable 规则定义一个 alterResource 规则并添加到 alterStatement 规则组合中。
第五步：增加单元测试
在上一步中，我们完成了对 SQL 的验证，并修改了 ANTLR 语法文件。此时不急着修改 Visitor 类中的代码，我们需要先为该场景增加测试用例，并在测试用例的帮助下，再尝试修改代码。
面对 ShardingSphere SQL 验证类 issue，官方 issue 创建人员均会在 issue 中列出如下说明：
After the above SQL parsing problem is repaired, the corresponding Test needs to be added.
- Add the corresponding
sql-casein thesql/supporteddirectory.- Add case assertions in the case directory of the
shardingsphere-test-it-parsermodule.- Run
org.apache.shardingsphere.test.it.sql.parser.internal.InternalSQLParserIT
简单来说并不需要我们通过编码来实现测试用例，而是按照规则增加对应 SQL 的测试场景即可。这里，继续结合本人此前修复的 MySQL 相关 issue ，讲解如何添加测试用例：
首先我们需要通过如下路径定位到两个关键的 XML 文件，路径如下：
模块：test -> it -> parser 包：resources -> case | sql -> supported
其中 supported 路径下的 XML 文件是我们需要添加的 SQL 用例，而 case 路径下的 XML 文件，是需要我们针对这个用例编写解析后规则切片。可以结合下图示例辅助理解。
所谓规则切片，相当于 SQL 解析为抽象语法树之后，在规则组合中，每个规则对应 SQL 字符串的起止位置。当执行单元测试时，会以我们编写的内容为预期，验证 ShardingSphere 对于该 SQL 的解析是否正确。该 XML 文件中，每个标签基本对应 ANTLR 文件中的规则，具体可参考文件中其他用例来编写。
完成用例的编写，定位到 InternalSQLParserIT 或 InternalDorisParserIT 执行单元测试即可，通过查看 IDEA 中测试用例执行情况，经 id 定位到新增用例，确认是否需要修改相关 Visitor 实现。
第六步：修改 Visitor 实现
如果在上一步中新增的测试用例正常通过，那么很幸运，你可以跳过这一步了。否则，意味着我们需要修改相应 Visitor 代码来适配 ANTLR 语法解析。这一步中，我将继续结合本人此前修复的 MySQL 相关 issue ，讲解针对自定义 Visitor 的修改过程。
接着上一步对 ANTLR 语法文件的修改与编译，结合失败测试用例，我们需要改写 SQLStatementVisitor 对应实现，具体在MySQLDMLStatementVisitor 中的方法如下：
@Override
public ASTNode visitIndexHint(final IndexHintContext ctx) {
//do some process.
}
结合上文中的 ANTLR 语法修改，具体修改内容如下图所示，如果你不了解 ANTLR 运行时 Context 中的内容，结合上一步中的单元测试，可以 debug 来逐步了解，这一步并不复杂也没有想象中那么难，耐心一点即可。
第七步：提交与 PR
当我们成功完成上述步骤后，先不要急着提交和创建 PR，在此之前为了避免代码格式等问题，我建议以此在项目根目录下执行两个命令：
./mvnw spotless:check -Pcheck -T1C
./mvnw checkstyle:check -Pcheck -T1C
因为 ShardingSphere 集成了代码格式检查和格式调整 Maven 插件，所以我们先通过预设格式对我们修改代码进行格式化，再进行格式检查。确保代码格式无问题后提交代码，按要求创建 PR 即可。否则在创建 PR 之后会触发流水线，执行代码格式检查，失败的话 PR 是不会被合并的。
待所有流水线内容通过后，剩下的就交给时间吧，等待 PR 合并主干即可。
最后，感谢你为社区所做的贡献，同时也请祝贺一下自己，成为 ShardingSphere 的贡献者！
最后
在大家参与贡献的过程中，一定要熟读官方文档，按照社区规范行事。 如果你在完成 Doris sql 验证相关 issue 的过程中，遇到什么需要帮助的内容，如果你愿意，可以留言或私信与我联系，我看到的话，一定会尽我可能的为你提供帮助。
关联阅读
- Apache 项目列表
- Apache Github 仓库列表
- CNCF Landscape
- ShardingSphere 贡献者指南
- ShardingSphere 开发环境指南
- doris-standalone Docker 镜像
- 【Vol.1】Apache ShardingSphere 源码解读-张亮
- 开源入门——如何参与 Apache ShardingSphere SQL 解析
- ANTLR 基础入门
你好，我是 HAibiiin，一名探索技术之外更多可能性的 Product Engineer。如果本篇文章对你有所启发或提供了一定价值，还请不要吝啬点赞、收藏和关注。
近期文章推荐：
