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

wubx

发布于 2022-04-27 17:27:50

9910

发布于 2022-04-27 17:27:50

文章被收录于专栏：MySQLBeginner

本篇文章受众：

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

为什么要向 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