如何贡献代码和文档¶

开始之前¶

GitHub 或社区提交问题¶

欢迎为项目贡献任何代码或文档，但是建议先在 GitHub 或社区上提交一个问题，和大家共同讨论。

签署贡献者许可协议（CLA）¶

什么是 CLA？

签署协议链接：vesoft inc. Contributor License Agreement

单击按钮 Sign in with GitHub to agree 签署协议。

如果有任何问题，请发送邮件至info@vesoft.com。

修改单篇文档¶

NebulaGraph 文档以 Markdown 语言编写。单击文档标题右侧的铅笔图标即可提交修改建议。

该方法仅适用于修改单篇文档。

批量修改或新增文件¶

该方法适用于贡献代码、批量修改多篇文档或者新增文档。

Step 1：通过 GitHub fork 仓库¶

NebulaGraph 项目有很多仓库，以 NebulaGraph 仓库为例：

访问 github.com/vesoft-inc/nebula。
在右上角单击按钮Fork，然后单击用户名，即可 fork 出 NebulaGraph 仓库。

Step 2：将分支克隆到本地¶

定义本地工作目录。

# 定义工作目录。
working_dir=$HOME/Workspace

将user设置为 GitHub 的用户名。
```
user={GitHub 用户名}
```

克隆代码。

mkdir -p $working_dir
cd $working_dir
git clone https://github.com/$user/nebula.git
# 或：git clone git@github.com:$user/nebula.git

cd $working_dir/nebula
git remote add upstream https://github.com/vesoft-inc/nebula.git
# 或：git remote add upstream git@github.com:vesoft-inc/nebula.git

# 由于没有写访问权限，请勿推送至上游主分支。
git remote set-url --push upstream no_push

# 确认远程分支有效。
# 正确的格式为：
# origin    git@github.com:$(user)/nebula.git (fetch)
# origin    git@github.com:$(user)/nebula.git (push)
# upstream  https://github.com/vesoft-inc/nebula (fetch)
# upstream  no_push (push)
git remote -v

（可选）定义 pre-commit hook。

请将 NebulaGraph 的 pre-commit hook 连接到.git目录。

hook 将检查 commit，包括格式、构建、文档生成等。
```
cd $working_dir/nebula/.git/hooks
ln -s $working_dir/nebula/.linters/cpp/hooks/pre-commit.sh .
```
pre-commit hook 有时候可能无法正常执行，用户必须手动执行。
```
cd $working_dir/nebula/.git/hooks
chmod +x pre-commit
```

Step 3：分支¶

更新本地主分支。

cd $working_dir/nebula
git fetch upstream
git checkout master
git rebase upstream/master

从主分支创建并切换分支：
```
git checkout -b myfeature
```
Note

由于一个 PR 通常包含多个 commits，最终合入 upstream/master 分支时，我们会将这些 commits 挤压（squash）成一个 commit 进行合并。因此强烈建议创建一个独立的分支进行更改，这样在合入时才容易被挤压。合并后，这个分支可以被丢弃。如果未创建单独的分支，而是直接将 commits 提交至 origin/master，在合入时，可能会出现问题。若未创建单独的分支（或是 origin/master 合并了其他的分支等），导致 origin/master 和 upstream/master 不一致时，用户可以使用 hard reset 强制两者进行一致。例如：
```
git fetch upstream
git checkout master
git reset --hard upstream/master
git push --force origin master
```

Step 4：开发¶

代码风格

NebulaGraph 采用cpplint来确保代码符合 Google 的代码风格指南。检查器将在提交代码之前执行。

单元测试要求

请为新功能或 Bug 修复添加单元测试。

构建代码时开启单元测试

详情请参见使用源码安装 NebulaGraph。

Note

请确保已设置-DENABLE_TESTING = ON启用构建单元测试。

运行所有单元测试

在nebula根目录执行如下命令：
```
cd nebula/build
ctest -j$(nproc)
```

Step 5：保持分支同步¶

# 当处于 myfeature 分支时。
git fetch upstream
git rebase upstream/master

在其他贡献者将 PR 合并到基础分支之后，用户需要更新 head 分支。

Step 6：Commit¶

提交代码更改：

git commit -a

用户可以使用命令--amend重新编辑之前的代码。

Step 7：Push¶

需要审核或离线备份代码时，可以将本地仓库创建的分支 push 到 GitHub 的远程仓库。

git push origin myfeature

Step 8：创建 pull request¶

访问 fork 出的仓库https://github.com/$user/nebula （替换此处的用户名$user)。
单击myfeature分支旁的按钮Compare & pull request。

Step 9：代码审查¶

pull request 创建后，至少需要两人审查。审查人员将进行彻底的代码审查，以确保变更满足存储库的贡献准则和其他质量标准。

添加测试用例¶

添加测试用例的方法参见 How to add test cases。

捐赠项目¶

Step 1：确认项目捐赠¶

通过邮件、微信、Slack 等方式联络 NebulaGraph 官方人员，确认捐赠项目一事。项目将被捐赠至 NebulaGraph Contrib 组织下。

邮件地址：info@vesoft.com

微信：NebulaGraphbot

Slack：Join Slack

Step 2：获取项目接收人信息¶

由 NebulaGraph 官方人员给出 NebulaGraph Contrib 的项目接收者 ID。

Step 3：捐赠项目¶

由您将项目转移至本次捐赠的项目接受人，并由项目接收者将该项目转移至 NebulaGraph Contrib 组织下。捐赠后，您将以 Maintain 角色继续主导社区项目的发展。

GitHub 上转移仓库的操作，请参见 Transferring a repository owned by your user account。

最后更新: September 4, 2023