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

原创
08/30 14:41
阅读数 6K

写在开头

从 2021 开始,有一个很有意思的说法经常在各大技术媒体或开源论坛中出现,「开源正在吞噬一切」。不论是否言过其实,从一个行业从业者的切身感知来看,开源确实从少数极客的小众文化成为主流的软件开发模式,有越来越多的企业开始拥抱开源技术,享受到开源技术带来的福利。

一面是开源技术得到更广范围的应用和落地。以我们所处的数据库和大数据领域来看,2021 年全球开源数据库的流行指数首次超过商用数据库,以 Apache Hadoop、Apache Spark、Apache Flink 等为代表的大数据组件几乎构成了大数据生产链路上的事实标准。而另一面,则是开发者对于参与开源项目和社区的热情愈发高涨。不论是出于 掌握技术、解决业务问题、提升业务效率的目的,或者是出于 钻研技术、加强编码能力、提升视野高度的目的,又或者是出于丰富简历、寻求职业机会的目的,参与开源项目对开发者个人而言,是最为有效来提升自己的方式之一。

开源数据库流行指数首次超过商业数据库

过去几年我一直在参与开源项目 Apache Doris 的推广工作,这一期间与许多开发者有过深度的探讨和交流。2022 年 6月 Apache Doris 从 Apache 孵化器毕业正式成为 Apache 顶级项目,让 Apache Doris 在全球范围内受到了更多开发者的关注。在这一过程中也认识到,如何参与到开源项目的讨论和开发,是被许多开发者反复提及的问题,也是新人开发者最为迫切寻求解答的问题。

为了回答上面的问题,就有了本篇文章的诞生。其实参与开源项目并不困难,甚至可以说存在一定的定式,就以我所参与的 Apache Doris 项目为例,我将为大家介绍 Apache Doris 社区的一些工作机制、如何参与社区贡献以及如何完成自己第一个 PR ,希望为想参与开源社区贡献的小伙伴提供一个简单的思路,也希望能有更多开发者能参与 Apache Doris 社区中来,与社区一道成长,一道将国人研发的优秀数据库推广到全球,一道实现分析型数据库技术的革新,一道见证更多不可能的故事发生。

从 README 开始

从开源项目在 GitHub 上成功托管的一刻起,README 文件就随之诞生了。就如同一本书的序言或电子设备的使用说明书,README 文件是开启开源之旅的第一个入口,几乎涵盖了使用和参与开源项目的所有姿势,既包含了项目背景、系统架构、技术特性等技术相关的介绍,也包含了用户该如何安装、部署以及上手使用的操作指南,同时还会提供项目维护者的主要联系方式、相关资料的获取地址以及如何参与贡献的指引等。

以上为 Apache Doris README https://github.com/apache/doris/blob/master/README.md

通过阅读 README 文件,可以对 Apache Doris 社区建立一个相对全面的认识。

参与社区沟通

邮件列表(Mailing List)是 Apache 社区最被认可的交流方式,无论是问题反馈与解答、技术交流与探讨、版本迭代与发布、社区决议与公示等,都可以通过邮件列表的形式来承载。邮件列表异步通信、理性思考、公开透明的特性,也非常适合开源社区的沟通交流,任何人都可以订阅邮件列表来知悉社区动态。

订阅邮件列表操作可以参考以下链接:

订阅邮件列表 https://doris.apache.org/zh-CN/community/subscribe-mail-list

与邮件列表这一异步沟通模式相对的,是以微信、QQ、钉钉等 IM 工具为代表的即时通讯模式。

由于信息传递的效率更高,即时通讯软件几乎成为国内开源社区日常技术沟通和交流的主要方式。以 Apache Doris 社区为例,目前 Apache Doris 社区有超过 20 个微信社群、聚集了超过 8000 人以上用户规模,相对于邮件列表,微信社群无疑承载了更多用户支持和问题解答的职责,每个用户都可以通过 Apache Doris 官网上的入口扫码加入用户社群中,去探讨技术和寻求答疑。

目前 Apache Doris 社区有一支专职的用户支持团队帮助社群中的用户定位和解决问题,尽管这能带来更好的用户体验(用一些社区用户的话说, Apache Doris 社区的技术支持力度甚至比一些商业软件的支持力度还要大),但微信社群天然存在的信息割裂、冗余信息过多、知识无法沉淀等弊端依然存在,因此社区也一直在寻求更加合理和可持续的方法,例如 Slack 社群以及 GitHub Discussion,希望在保持用户体验的同时也能提升沟通和解决问题的效率,这也是我们更为推荐的沟通方式。

加入 Slack Join the Slack

GitHub Discussion https://github.com/apache/doris/discussions

善用官网与文档

官方网站和文档是深入了解一个开源项目最主要和高效的方式,熟读文档对于掌握开源项目的重要性不言而喻,在此也不再赘述。

2022 年 7 月,在社区力量的支持下我们对 Apache Doris 官网和文档结构进行了一次整体改版,除了对各个页面视觉和交互效果的整体优化以外,还增加了文档的全文检索和版本切换等重要功能,可以对当前版本文档的任意字段进行搜索,帮助用户快速检索和定位到需要查询的内容。

如何提交你的第一个 Pull Request

参与开源项目并为其作出贡献的方法有很多,包括功能开发、测试 Case 编写、流程工具改进、文档完善、博客撰写等等,任何对于项目的贡献都是有价值并且受欢迎的。在提交的贡献正式合入后,将自动成为项目的贡献者并出现在项目的贡献者列表中。

Apache Doris 社区有着清晰的贡献者成长标准,贡献者在对项目有着足够的贡献后,有机会通过推选和投票成为 Committer,拥有代码库的合入权限,并且名字将出现在 Apache 网站列表中 。更进一步,还有机会成为项目的 PMC Member(项目管理委员会成员),对项目的重要决策拥有投票权。

Apache Doris PMC/Committer 名单:https://doris.apache.org/zh-CN/community/team

每一个贡献从最初的发起到最终的合入,大致会经历以下的步骤:

  • 发现问题或优化项
  • Fork 代码仓库
  • 本地开发与自测
  • 创建 Pull Request
  • 等待 Code Review
  • 审核通过并合入 Master

寻找第一个贡献点

接下来聊聊如何寻找到一个贡献点,往往这也是大多数人跨入开源世界大门的第一步,有幸跨入的话则会发现门门外是两种完全不同的风景。

或许是在浏览文档时发现了一个小的错漏,例如发现一个小的错别字或者发现某个链接失效,又或许可能是已有的文档在细节描述或语义表达上有可提升的空间,可以把订正或补全开源文档作为第一个出发点,帮助文档质量得到提升,这也是参与开源项目的重要途径。

文档贡献 https://doris.apache.org/zh-CN/community/how-to-contribute/contribute-doc

也有可能是在使用开源项目过程中发现了一个 Bug ,或者应用其某一业务场景中发现还存在一些未被满足的功能点,经过阅读和分析代码后认为凭借自身能力可以对其进行改进,这时可以在 GitHub 上搜索是否有人与你具有相同的想法或问题,如果没有的话可以创建一个 Issue,并按照 Issue 模版依次补充相关信息。

同时在 Issue 列表中可以通过 Label 筛选出带有“good first issue” 的 Issue,通常是社区为新贡献者专门留出来的开发任务,并且在 Apache Doris 社区还会定期将新手任务汇总在置顶的 Issue 中。如果是第一次参与开源项目,可以选择这些简单任务进行练习,熟悉整个 Pull Request 提交流程之余还可以感受到社区对新人的友好度。

Good First Issue https://github.com/apache/doris/issues/11706

通常系统架构方面的修改或者重要的功能引入需要在社区进行充分的讨论与交流,可以在邮件组中发起讨论,也可以提交 Issue 发起,同时在 Doris Improvement Proposals 中提交详细的设计文档,帮助其他开发者了解功能的设计动机、需求与详细方案。

DSIP https://cwiki.apache.org/confluence/display/DORIS/Doris+Improvement+Proposals

Fork 代码仓库

在确定贡献点之后就可以开始上手开发了,第一步就是 Fork 代码。进入 Apache Doris 的 GitHub 后 点击右上角的 Fork 按钮进行 Fork。如果喜欢 Apache Doris,也可以点击旁边的 Star 🌟按钮关注代码仓库)

Fork 完成后回到自己的 GitHub 账号下就可以找到 Fork 的项目,这时对自己 Fork 的项目拥有了任意修改的权限,可以将代码 Clone 到本地进行开发。

(1)将代码 Clone 到本地:

git clone https://github.com/<your_github_name>/doris.git

Clone 完成后,origin 会默认指向 GitHub 上的远程 Fork 地址。

(2)将 apache/doris 添加为本地仓库的远程分支 Upstream:

cd  doris
git remote add upstream https://github.com/apache/doris.git

(3)检查远程仓库设置:

git remote -v
origin https://github.com/<your_github_name>/doris.git (fetch)
origin    https://github.com/<your_github_name>/doris.git (push)
upstream  https://github.com/apache/doris.git (fetch)
upstream  https://github.com/apache/doris.git (push)

(4)新建分支以便在分支上做修改:

git checkout -b <your_branch_name>

注意: <your_branch_name> 为您自定义的分支名字。

创建完成后可进行代码开发和自测。

创建 Pull Request

开发并自测完成后即可将代码提到自己 Fork 的远程分支中,再通过 Pull Request 的方式将 Commits 提交合入。

详细 Pull Request 提交指南可以参考以下文档:

代码提交指南 https://doris.apache.org/zh-CN/community/how-to-contribute/pull-request

(1)提交代码到远程分支:

git commit -a -m "<you_commit_message>"
git push origin <your_branch_name>

(2)创建 Pull Request

在浏览器切换到自己的 github 页面,切换分支到提交的分支 <your_branch_name> ,点击 Compare & pull request 按钮进行创建,如下图所示:

(3)准备分支

这时候,会出现 Create pull request 按钮,如果没有请检查是否正确选择了分支,也可以点击 “compare across forks” 重新选择 Repo 和分支。

(4)填写 Commit Message

这里请填写 Pull Request 的详细内容,在 Apache Doris 社区对于 Commit 格式有明确的规范,具体可以参考:

Commit 格式规范 https://doris.apache.org/zh-CN/community/how-to-contribute/commit-format-specification/

(5)等待 GitHub 检查和 Code Review

点击 Create pull request 进行创建后,Pull Request 创建完成后会自动触发 GitHub 的检查任务,只有通过检查后代码才能被合入。

Github Checks https://cwiki.apache.org/confluence/display/DORIS/Github+Checks+Guidance

创建的 Pull Request 在接受 GitHub Check 的同时,也需要接受社区的 Review。在 Apache Doris 社区,我们欢迎所有人参与到代码的 Review 中来,通过开放式讨论保证代码质量,最终由具有代码合入权限的开发者给出合入意见,至少需要有一个非作者的 Committer 给出 +1 才能被合入。

Code Review 指南 https://doris.apache.org/zh-CN/community/how-to-contribute/contributor-guide#code-review

(6)代码合入

最终通过 GitHub 检查任务以及 Code Reivew 的 Pull Request 会在一个工作日后被合入进 Master,至此恭喜成为 Apache Doris Contributor!

Enjoy it!

其实参与开源项目不存在什么门槛,绝大多数开源项目是自由开放、且非常欢迎有更多人能参与进来的。与其说不知道该如何参与开源项目,个人感觉可能是信息传递障碍带来的些许隔阂,也许只需要一个简单的发往 dev 邮件组的邮件就可以解决。

无论是提交 Issue 或参与 PR Review,或者是修改和完善文档,又或者是分享技术博客和应用案例,都是参与开源贡献,也期待有更多的你一道参与进来。

- End -

 

如果你对 Apache Doris 感兴趣,请加入 Doris!我们也发起了 征文活动 邀你讲讲与 Doris 相遇 相知 相识的故事,不仅有精美礼品相送,还可获得 SelectDB 全渠道曝光加持!

最后,欢迎更多的开源技术爱好者加入 Apache Doris 社区,携手成长,共建社区生态。


展开阅读全文
加载中

作者的其它热门文章

打赏
5
24 收藏
分享
打赏
0 评论
24 收藏
5
分享
返回顶部
顶部