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

仓廪实则知礼节，衣食足则知荣辱。这篇文章主要讲述如何向 github 上开源项目提交代码相关的知识，希望能为你提供帮助。
本篇文章受众：

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

为什么要向 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 给的提示：

文章图片

存在安全，不规范方面的问题，需要进行修复，从这点看 Rust 也是一门非常严格的约束的语言。
提交分支及pull request
对分支提交 commit 后，在个人的 fork 项目里，可以看到 pull request ，直接发起请求就可以了。例如：https://github.com/datafuselabs/databend/pull/4824
提交的代码会经过 Databend 的 ci 构建程序进行构建及测试全部通过，这个过程需要很长的时间，需要经历 github 的 CI 把 Databend 编译出来后，走一下各种测试，如下：

文章图片

如果构建中有问题或是代码有不合理的地方， 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修复可能不需要]
清理分支
到这里恭喜你应该得到这里代码被合并了，可以安全删除分支

文章图片

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

总结
本篇文章到这里就接近尾声了。这里面省略了 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
【如何向 github 上开源项目提交代码】