如何贡献代码和文档¶

开始之前¶

GitHub 或社区提交问题¶

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

签署贡献者许可协议 CLA ¶

打开 CLA 服务登录页面。
单击 Sign in with GitHub。
阅读并同意协议 vesoft inc. Contributor License Agreement。

如果有任何问题，请提交 issue。

修改单篇文档¶

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 6, 2024