本篇文章受众:

  • 想加入开源项目的开发者
  • 在校学生,希望加入感兴趣的项目,获得实习|工作机会
  • 想从事数据库内核研发的人员


为什么要向 Github 提交代码

github 是一个代码手艺人交流的平台,开发者搞基交流平台,开发者通常直接亮出 github account 进行认识对方,面试时通过 github account 来了解这个人的代码基本能力。

对于想从事某个方向开发的的朋友尽早的参与到该方向的项目,对于职业发展非常有利。特别对于在校学生,如果能提早到参与到一些开源项目,基本相当于拿到了入职的 offer 。


如何选择优秀的项目

这个话题比较大不过有几点建议:

• 选择项目活跃度高的: 提交的 issue 及 pr 可能得到的响应较快,参与后反馈也比较好。

• 参与有商业支持的开源项目: 目前来看商业项目。早在 2015 年我们技术圈已经流传一句话,中国的不可能会有比较优秀的个人开源项目, 一个优秀的个人,基本上一段时间后他的 KPI 就会改变,参与的项目可能就不会再维护了。目前从实际情况看,只有商业公司的开源项目可能会长久。这里面还有一个坑,某些商业公司也开源了一堆项目,更多就是为了 KPI 开源,这类项目的特点就是开源后再不更新代码,或是很短一段时间就不更新代码了。

• Github Trending 经常上榜单。能上 Github Trending 的项目,基本都属于该方向比较优秀的项目,活跃及规范都应该不会差的。

• 选择符合个人爱好的方向的项目: 我是数据库方向从业了 15 年以上,更多就是在关注数据库这个方向的项目。目前这个方向也符合国家及全球的追求的方向。如果没有特别的爱好,可以看看这个方向。

我现在个人主要在云原生数仓 Databend (https://github.com/datafuselabs/databend),如果你对云原生数仓这个方向有兴趣,欢迎你参与进来。这个项目的开发者都是超级处女座,每个地方都是做的一板一眼,通过这个项目的参与,可以把自我训练成高素质的开发人员。本次贡献代码提交,我们也以 Databend[2] 这个项目为代表。


从事数据库开发需要的知识

说到数据代码提交,少不要学习数据库相关的知识,这里做一些推荐:

•学习资料推荐

1、 数据库书(必读

    •《数据库系统:设计、实现与原理(基础篇》) 有同事反馈至少刷 3-5 次

    •《Oracle Database 9i 10g 11g编程艺术:深入数据库体系结构》 用不用 Oracle 都推荐阅读, 受益非常大的一本书。

2、扩展阅读

•《Inside Microsoft SQL Server T-SQL Query 》任意版本都是经典

•《事务处理概念与技术》 神作,不推荐非专业的看,建议以上书都看完了,有一定的编程并行,锁相关的经验看再来阅读。

3、开发语言:

• Linux C/C++

• Rust

这方面建议找一些简单的书先看入门就可以。然后再深入。Rust 推荐学习 rustlings 这个教程就可以,Linux C/C++ 就不做推荐了,书太多了, 所以这里不再推荐。

建议在这些语言上可以实现一些: list, btree, 一些常见的算法后再看后面的课程。

以上资料可能有点老,特别是书籍,如果你有认为好的资源也欢迎补充。数据库内核实战的书也比较多,但上面的书是我认为比较好的入门书籍。

4、 系列课程:

•  cmu15-445 没有之一,这个目前数据库内核入门的最佳内容。B 站,Youtube 上都有对应的视频,网上也有对应的 PPT 及 GITHUB 上有对应的 Repo,目前来看数据代码入门比较好的资料。

•  阅读专业方向的 Page : 目前看这个是一个比较靠谱的方向。这也是一个很痛苦的开始,例如刚开始时,会感觉所有的单词都认识,但拼到一块不太容易搞明白他们想表达的是什么。坚持,坚持,坚持就好。

•  感兴趣项目的 howto 也是不错的资料

5、实战

•  从学习到输出,这个过程也建议可以总结一些 blog 进行发布和业界的朋友进行交流。

•  我另外一个感受,多看看别人提供的 PR,新鲜热乎的 PR ,对应的对方的分支还没删除时,可以更清晰的看到一个功能的开发或是修复的过程,是一个非常好的学习方式。


提交代码的大概步骤

一个开源项目参与的过程大概如下:

•  阅读代码提交要求

•  Fork 代码及构建开发环境

•  选择 issue 或是提 issue

•  创建分支,在分支上进行开发及提交

•  本地测试

•  提交分支及pull request

•  清理分支

阅读代码提交要求

Databend 在代码提交前首先建议阅读 :

Your first Databend Pull Request[3] https://databend.rs/doc/contributing/good-pr

整个文章让大家提交代码时,要进行测试及利用

make lint

进行代码格式化及分析,可以帮着分析一下代码中不符合安全要求等方面的代码。需要软件安装( Databend 源码下):

make setup -d

省去了很多环境安装的复杂操作。

Fork 代码及构建开发环境

下面以 Linux 或是 Mac 作为参考

1、 Fork 源码及下载源码

在 Github 贡献代码,是需要先 Fork 代码到个人仓库下,然后拉到本地,构建开发环境 参考: Getting and Building Databend from source [4]

git clone https://github.com/datafuselabs/databend
cd databend

这里的地址换成个人 fork 的项目地址就好。如果长期关注一个项目,建议也 watch 一下,这样可通过 Github 的通知了解项目的 issue 及 pr 提交情况。

2、 开发环境构建:Databend 为开发定制了开发环境安装的自动化脚本,可以在 clone 的目录下执行:

# 安装 build 环境
make setup -b
# 安装 dev 环境
make setup -d

如果你是你的国内网络,推荐阅读:国内源码编译 Databend[5] 如果可以搞定翻墙的可以忽略。

3、 源码编译

•  Debug 版本编译

make build

开发中功能测试验证问题,用 Debug 编译就行,这个编译比较快的,如果将来想用于生产环境的编译,建议使用 build-native 编译。

make build-native

该编译方法编译出来的二进制比 Debug 性能高上十几倍。

如果有兴趣的可以测一下你机器大概的能力是什么样,一些参考:

•  make build 

•  make build-native

类型

build

build-native

mac 16-inch 2019 i9

7m34s

21m12s

Ubuntu AMD 5950X 32G

3m25s

5m22s

mac pr0 14 2021 m1 pro

4m2s

8m27s

各位看客可以看感受一下,如果你有兴趣了,也可以把你的配置及编译时间留言分享给大家,目前看到最快的机器可以在 3min+ 完成编译。

4、 源码测试 Databend 中测试比较多,有基本的源码单元测试, Stateless 测试。 如果是做的框架代码开发,一般需要单元测试,另一类就可以写功能的 Stateless 测试。为了保证的代码是可以通过编译及测试用例通过,需要进行下面的操作。

# 单元测试
make unit-test

# stateless 测试
make stateless-test

# 代码分析及格式化
make lint

对于上面的三个测试,推荐:stateless-test, make lint 是必过的。

对于测试这块想了解更多的可以关注 Databend 如何写测试 [6]

这一步非常关键,需要大概明白,当前的测试结果是什么样,后面修改代码及添加功能,测试也需要是通过的和上面的输出结果是一致的。

选择 issue 或是提 issue

对于初学者建议搜一些已经 close 的 issue 代码学习一下。或是一些热乎的 pr 看看在个人的分支上练习一下。当有一定的感觉后,可以看看 good-for-first issue, 也可以看看当前的 Roadmap[7] 找找感兴趣的方向,提新的 issue 或是完成现有的 issue 都是可以的。

对于有意向的 issue 可以评论中评论:

/assignme

机器人会主动把对应的 issue 分派给你。对于别人已经 assign 过的 issue 如果对方,长期没有行动,也可以利用评论进行交流,获取新的 assign 。

开源项目:有一个建议 issue 先行, 做什么提前要声明,公开交流,利用 issue 的评论进行交流。这里要多看 github 的通知。我们很多贡献者通知他领参与贡献的礼品,但也有从来没回复的。估计就是没看 github 的通知。

推荐浏览器扩展工具:Notifier for GitHub 不错过任何 github 的通知。

提交分支及开发

好了,现在我们已经有了本地代码及编译通过的分支及对应测试通过, 如果我们也拿到了心仪的 issue 或是创建了新的 issue ,接下来就是我们要开干的时间了。

•创建分支 例如我这里需要给 Databend 添加一个: show schemas; 的功能,我这里创建一个分支:

# 创建分支 support-show-schemas
git branch support-show-schemas
# 切换到创建的分支上
git checkout support-show-schemas

然后就可以在这个分支上的代码进行开发及测试

本地测试

本地测试,基本的流程还是

# 单元测试
make unit-test

# stateless 测试
make stateless-test

# 代码分析及格式化
make lint

因为我这个属于添加一个功能,只需要 stateless 测试和 make lint 。

其中 make lint 非常重要,我这个开发中,第一次代码提交:

} else if self.consume_token("DATABASES") {
self.parse_show_databases()
} else if self.consume_token("SCHEMAS") {
self.parse_show_databases()
} else if self.consume_token("SETTINGS") {

最终修改为:

} else if self.consume_token("DATABASES") || self.consume_token("SCHEMAS") {
self.parse_show_databases()
} else if self.consume_token("SETTINGS") {

本地功能测试没有任何问题,show schemas 也支持了。但是用 make lint 给的提示:

如何向 github 上开源项目提交代码_开源项目

存在安全,不规范方面的问题,需要进行修复,从这点看 Rust 也是一门非常严格的约束的语言。

提交分支及pull request

对分支提交 commit 后,在个人的 fork 项目里,可以看到 pull request ,直接发起请求就可以了。例如:https://github.com/datafuselabs/databend/pull/4824

提交的代码会经过 Databend 的 ci 构建程序进行构建及测试全部通过,这个过程需要很长的时间,需要经历 github 的 CI 把 Databend 编译出来后,走一下各种测试,如下:

如何向 github 上开源项目提交代码_github_02

如果构建中有问题或是代码有不合理的地方, Reviewers 也会直接利用评论和你交流。你可以在这个 branch 上进行修改及提交达到最终 ci 通过及 Reviewers 把 PR 合并(所有的 CI 构建正确的完成,就可以获得机器人的一个投票,然后再获得一个 reviewer 的投票就可以自动合并)。

BTW:代码合并也会在 Github 的通知中提示。

拉取别人的 PR 进行验证

技巧 例如对某一个功能特别感兴趣,看到别人提交的 PR ,还没合并到 main 中怎么去验证呢? 有两种办法:

•clone 对应人的 databend 切换到对应的分支上验证•修改 .git/config

[remote "origin"]
url = git@github.com:datafuselabs/databend.git
fetch = +refs/heads/*:refs/remotes/origin/pr/*

添加 pr 这个选项,拉取别人的 PR ,参考命令

git fetch upstream pull/PRId/head:LocalBranchName

这块总结一下 正常的一个功能开发及提交代码需要包含三部分:

 • 功能[实|修复]代

• 相应的测试代码

 • 文档介绍[bug修复可能不需要]

清理分支

到这里恭喜你应该得到这里代码被合并了,可以安全删除分支

如何向 github 上开源项目提交代码_数据库_03

如果为了管理方便,就可以删除到对应的分支就可以了。所以说想学习别人的提交功能修复或是开发,看别人分支需要尽早 :) 。


总结

本篇文章到这里就接近尾声了。这里面省略了 git 的操作,整体上希望给大家形成一个主线方便你参与到开源项目中来。如果你参与到开源项目中来,你就会无形中认识了很多大牛,让你的视野及认知也会有一个新的提高,如果你能得到对方的认可,基本把个人放到一个新的起步线,我周边有朋友通过参与开源项目去海外大厂工作,移民的,也有直接拿到项目的 Offer。

当然开源项目的参与,也不只是提交代码,也有很多开源社区的文化建设也可以参与(适合英语好,爱交际的朋友)。

最后祝愿各位可以找到个人喜欢的项目参与进行,也祝愿各位参与的项目有一个好前景。

References

​[1]​​ Databend: https://github.com/datafuselabs/databend

​[2]​​ Databend: https://github.com/datafuselabs/databend

​[3]​​ Your first Databend Pull Request: https://databend.rs/doc/contributing/good-pr

​[4]​​ Getting and Building Databend from source : https://databend.rs/doc/contributing/building-from-source

​[5]​​ 国内源码编译 Databend: https://github.com/wubx/dba-in-databend/blob/main/install/compile_databend_in_china/complie-databend-in-china.md

​[6]​​ Databend 如何写测试 : https://www.bilibili.com/video/BV1P44y1s7Q7

​[7]​​ Roadmap: https://github.com/datafuselabs/databend/issues/4591