如何贡献

1. 前言

感谢您为TuGraph做出贡献，我们由衷地希望有更多社区的同学加入进来，一起建设一个更好的图数据库项目。

对于优秀社区贡献者，我们将颁发TuGraph优秀社区贡献者证书。

2. 贡献什么

我们随时都欢迎任何贡献，无论是简单的错别字修正，BUG 修复还是增加新功能。请踊跃提出问题或发起 PR。我们同样重视文档以及与其它开源项目的整合，欢迎在这方面做出贡献。 对于任何修改，尤其是较为复杂的修改，建议新建一个issue ，按照BUG或者PR的模板填写。

3. 准备工作

3.1. 了解TuGraph

建议您从文档地图开始，了解TuGraph的特性和接口。

3.2. 准备环境

对于文档贡献，可以直接通过文档，点击右上角的”在GitHub上编译”直接修改并提PR。

对于代码贡献，通常需要在搭建编译执行的环境，可以采用Docker部署或本地部署。

3.3. 许可协议

在贡献代码之前，请您稍微花一些时间了解为TuGraph贡献代码的流程，并阅读 个人贡献者许可协议 或 公司贡献者许可协议，参与贡献则视为同意上述协议。

4. 贡献代码流程

4.1. 提交issue

不论您是修复 TuGraph 的 bug 还是新增 TuGraph 的功能，在您提交代码之前，请在 TuGraph 的 GitHub 上提交一个 issue，描述您要修复的问题或者要增加的功能。这么做有几个好处:

  • 不会与其它开发者或是他们对这个项目的计划发生冲突，产生重复工作。

  • TuGraph 的维护人员会对您提的 bug 或者新增功能进行相关讨论，确定该修改是不是必要，有没有提升的空间或更好的办法。

  • 在达成一致后再开发，并提交代码，减少双方沟通成本，也减少 pull request 被拒绝的情况。

4.2. 获取源码

要修改或新增功能，在提交 issue 后，fork一份 TuGraph Master代码到您的代码仓库。

4.3. 拉分支

TuGraph 所有修改都在分支上进行，修改完成后提交 pull request，在 Code Review 后由项目维护人员 Merge 到 Master。 因此，在获取源码步骤介绍后，您需要:

  1. 下载代码到本地，这一步您可以选择git/https方式，近年github的权限要求更加严格，比如git方式需要更复杂的ssh key(https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)，https方式不能直接使用用户名密码验证，请按照指引授权。 git clone https://github.com/您的账号名/tugraph-db

  2. 拉分支准备修改代码: git branch add_xxx_feature

  3. 执行完上述命令后，您的代码仓库就切换到相应分支了。执行如下命令可以看到您当前分支: git branch -a

  4. 如果您想切换回 Master，执行下面命令: git checkout -b master

  5. 如果您想切换回分支，执行下面命令: git checkout -b “branchName”

4.4. 编译运行

代码的编译运行流程可以参考ci脚本

4.5. 配置 Github 信息

在您的机器执行 git config –list ，查看 git 的全局用户名和邮箱。检查显示的 user.name 和 user.email 是不是与自己 github 的用户名和邮箱相匹配。

如果公司内部有自己的 gitlab 或者使用了其他商业化的 gitlab，则可能会出现不匹配的情况。这时候，您需要为 TuGraph DB 项目单独设置用户名和邮箱。设置用户名和邮箱的方式请参考 github 官方文档。

4.6. 修改代码提交到本地

拉完分支后，就可以修改代码了。

**修改代码注意事项 **

代码⻛格保持一致：TuGraph 通过 cpplint 来保持代码格式一致，IDE可以通过.clang来配置风格。在提交代码前，务必本地检查代码风格，否则ACI将报错。

补充单元测试代码：新有修改应该通过已有的单元测试,应该提供新的单元测试来证明以前的代码存在 bug，而新的代码已经解决了这些 bug ,您可以用如下命令运行所有测试: ./unit_test 也可以通过IDE来辅助运行。

**其它注意事项 **

请保持您编辑的代码的原有⻛格，尤其是空格、换行等。 对于无用的注释，请直接删除。 对逻辑和功能不容易被理解的地方添加注释。 及时更新文档。 修改完代码后，请按照如下格式执行命令提交所有的修改到本地: git commit -am ‘(feat) 添加xx功能’ git commit -am ‘(fix) 修复xx问题’`

4.7. 提交代码到远程仓库

在代码提交到本地后，接下来就可以与远程仓库同步代码了，执行如下命令提交本地修改到 github 上: git push origin “branchname”

如果前面您是通过 fork 来做的，那么这里的 origin 是 push 到您的代码仓库，而不是 TuGraph 的代码仓库。

提交合并代码到 Master 的请求 在的代码提交到 GitHub 后，您就可以发送请求来把您改好的代码合入 TuGraph Master 代码了。此时您需要进入您在 GitHub 上的对应仓库，按右上⻆的 pull request 按钮。选择目标分支，一般就是 master，系统会通知 TuGraph 的人员， TuGraph 人员会 Review 您的代码，符合要求后就会合入主干，成为 TuGraph 的一部分。

请注意会自动检查CI，以及所有Commits中的贡献者是否签署了cla，通过后会有绿色的标识。

4.8. 代码 Review

在您提交代码后，您的代码会被指派给维护人员 Review，请耐心等待。如果两个工作日后，仍然没有人对您的提交给予任何回复，可以在 PR 下面留言，并 @ 对应的人员。

对于代码 Review 的意⻅会直接备注到到对应 PR 或者 Issue。如果觉得建议是合理的，也请您把这些建议更新到您的代码中。

4.9. 合并代码到Master

在代码 Review 通过后，就由 TuGraph 维护人员操作合入 Master，在此过程中维护人员可能会指定新的Reviewer，提出新的意见需要修改。一般这一步不用参与，代码合并之后，您会收到合并成功的提示。