Ascend Boost Comm 基于 Gitcode 的贡献工作流:从 Fork 分支开发到 Pull Request 合入全解析
Ascend Boost Comm 基于 Gitcode 的贡献工作流:从 Fork 分支开发到 Pull Request 合入全解析
本文是面向 Ascend Boost Comm(CANN 算子公共平台)贡献者的完整实战指南,系统讲解基于 Gitcode 代码托管平台的协作流程:从准备工作、Fork 个人分支、本地克隆与构建验证,到提交变更、创建 Pull Request、关联 Issue、触发门禁(CI)检查并处理代码检视意见,最后覆盖回退提交、解决冲突、合并提交等高频运维操作。读完本文,你将能够独立完成一次从"个人分支开发"到"PR 合入主干"的完整提交流程,并掌握与 CANN 社区 Bot 交互的关键命令。
工作流全景:一次贡献的完整生命周期
Ascend Boost Comm 仓库(CANN 的算子公共平台,南向对接不同组织开发的算子库,北向支撑不同加速库应用)使用 Gitcode 平台进行协作。一次标准的贡献通常包含以下环节:
Fork 个人分支 → 克隆到本地 → 创建开发分支 → 本地构建与验证
→ 保持与 master 同步 → 本地提交 → 推送到远端 fork
→ 创建 Pull Request → 关联 Issue → 触发门禁(/compile) → 代码检视 → 合入
本文后续章节将按照这一流程逐一展开,并在每步给出可直接执行的命令。相关协作交互命令的完整说明可参考 CANN 社区用户交互流程。
1. 开展工作流前的准备
1.1 安装 Git
请先确保您的电脑上已经安装了 Git 软件。如您需了解 Git 的安装与基本用法,可以在 Google、百度或其他搜索引擎上求助相关内容。
1.2 找到目标仓库
在开展 Gitcode 工作流之前,您需要先在 Ascend 的代码托管平台上找到 Ascend Boost Comm 仓库。仓库根目录的 README.md 描述了项目定位与目录结构:src/ 存放主体源代码(算子加载 mki_loader、调度 schedule、工具类 utils 等),example/ 提供算子调用示例,tests/ 存放测试代码。
2. 准备本地代码
2.1 Fork 个人分支
- 找到并打开对应开放项目的首页;
- 点击右上角的
Fork按钮,按照指引,建立一个属于"个人"的云上 fork 分支。
Fork 之后,您就拥有了一个与上游仓库(原始仓库)内容一致、但归属自己账户的云端副本,后续所有代码修改都将在个人 fork 上开展,避免直接污染主干分支。
2.2 把 fork 分支克隆到本地
请按照以下步骤将 repository 内的代码下载到您的计算机上。
1)创建本地工作目录:便于本地代码的查找和管理。
mkdir ${your_working_dir}
2)完成 Git 上用户名和邮箱的全局配置(如果您之前已经完成过此项配置,请忽略)。把 Git 的 user 设置成您 Gitcode 的个人名称:
git config --global user.name "your Gitcode Name"
配置您的 Git 邮箱:
git config --global user.email "email@your_email.com"
3)完成 SSH 公钥注册(如果您没有完成此注册,每次都要重新输入账户和密码)。
- ① 生成 SSH 公钥:
ssh-keygen -t rsa -C "your_email@example.com"
cat ~/.ssh/id_rsa.pub
- ② 登录您个人的 Gitcode 账户并添加您的 SSH 公钥:请在 Gitcode 网页点击右上角的"个人头像"进入个人账户,并点击个人头像下的"个人设置",进入个人设置页面。在"个人设置 -> 安全设置"下,点击"SSH 公钥",在"添加公钥"内把
cat命令获取到的 SSH 公钥添加进去。 - ③ 在个人电脑上完成 Gitcode 在 SSH 上的注册验证:
ssh -T git@gitcode.com
如果获得如下"成功"提示,则表示 SSH 公钥已经生效:
Hi $user_name! You've successfully authenticated, but GITCODE.COM does not provide shell access.
4)复制远程仓库到本地:
- ① 切换到本地路径:
cd $your_working_dir
- ② 复制远程仓库到本地:您可以在需要下载的远程仓库首页,单击"克隆/下载",得到
$remote_link(您需要创建令牌并输入以替代密码登录)。然后在本地电脑执行如下命令:
# 下载远程仓库到本地(这里以个人 fork 后的地址为例)
git clone https://gitcode.com/$user_name/ascend-boost-comm.git
# 设置本地工作目录的上游源(原始仓库)
git remote add upstream https://gitcode.com/cann/ascend-boost-comm.git
这里的关键一步是 git remote add upstream:origin 指向您的个人 fork,upstream 指向原始仓库(cann/ascend-boost-comm)。这种双远端配置是后续"同步上游最新代码"与"向主干发起 PR"的基础。
2.3 拉分支
先更新您的本地分支:
git fetch upstream
git checkout master
git rebase upstream/master
再创建本地个人分支:
git checkout -b myfeature
myfeature 为个人分支名称,后续在此分支上编辑和修改代码。建议分支名与您要解决的问题(Issue)相关联,例如 fix-xxx、feature-xxx,便于后续在 PR 中识别变更意图。
3. 本地构建和验证
在提交代码之前,请先在本地完成构建与验证。Ascend Boost Comm 的本地构建与验证说明参见仓库根目录 README.md 的使用说明与编译说明。
从 README.md 可以整理出本地验证的基本流程:
- 编译入口为 scripts/build.sh,常用目标包括
testframework、example、release等,完整参数可执行bash scripts/build.sh help查看。 - 工程默认对 C++ 代码启用
-Werror(见 cmake/host_config.cmake)。在 GCC 12 及以上 环境中,PyTorch 等第三方头文件可能产生警告并导致编译失败,请在命令末尾追加--no_werror:
bash scripts/build.sh testframework --no_werror
bash scripts/build.sh example --no_werror
- 单算子快速验证(以
example中的 addcustom 算子为例):先编译 testframework,再编译 example,然后 source 环境变量并运行测试用例:
cd ascend-boost-comm
bash scripts/build.sh testframework
bash scripts/build.sh example
source output/mki/set_env.sh
python example/tests/pythontest/optest/test_addcustom.py
运行前请确认已执行 source output/mki/set_env.sh,且 CANN / NPU 驱动环境可用。自定义算子的完整开发流程可参考自定义算子开发示例。
4. 保持您的分支和 master 的同步
开发期间上游主干可能持续演进,为保证 PR 合入时冲突最小,建议定期同步:
# 当前位于 myfeature 分支时执行
git fetch upstream
git rebase upstream/master
执行 merge 的时候,请不要使用 git pull 替代上面的 fetch + rebase。因为这种方式会使提交历史变得混乱,并使代码更难被理解。您也可以通过更改文件达到目的,在 .git/config 文件中通过 git config branch.autoSetupRebase always 去改变 git pull 的行为:
git config branch.autoSetupRebase always
rebase 会把您的本地提交"重放"到上游最新提交之上,形成一条干净的线性历史,便于检视者逐条审查。
5. 在本地工作目录提交变更
提交您的变更:
git add .
git commit -m "提交内容描述"
您可能会在前次提交的基础上,继续编辑、构建并测试更多内容,可以使用 git commit --amend 继续添加提交。--amend 会把新的改动合并进最近一次提交(同时可修改提交信息),避免产生大量无意义的中间提交。
提示:提交信息建议遵循仓库的 MR 标题规范(如
<a href="https://link.gitcode.com/i/25d45f0a0b8890b44ab4441bbbf180ec" target="_blank">bug/feature/task] Fix XX issue / Add XX feature / Rectify XX issue),详见[代码提交规范中的 MR 格式说明。
6. 将变更推送到您的远端目录
准备进行审查(或只是建立工作的异地备份)时,将分支推到您在 gitcode.com 的 fork 分支:
git push -f origin myfeature
-f(force)用于强制推送:由于此前执行过 rebase,本地提交历史已被重写,普通推送会被拒绝,此时需要强制推送以更新远端分支。请确保 origin/myfeature 上只有您自己的提交、没有他人协作的提交时再使用 -f。
7. 在 Gitcode 上创建一个 Pull Request
- 访问您个人账户下
ascend-boost-commfork 仓库的页面,单击+ Pull Request。
- 在创建新 PR 的界面,确认源分支(您的
myfeature)和目标分支(上游的master),选择创建。
提交 PR 是对项目主分支的一次合并,为保证合并的质量,请谨慎操作。
仓库为 PR 提供了标准的描述模板(见 .gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md),包含描述区与 checklist,要求提交者在创建 PR 时自检以下事项:
- 是否通过本地 IDE 对代码进行静态检查;
- 是否通过本地 IDE 对代码进行格式化处理;
- 是否进行空指针校验;
- 是否进行返回值校验;
- 是否正确释放 new/malloc 申请的内存;
- 是否充分考虑接口的异常场景;
- 是否正确记录错误日志。
模板中的 checklist 与仓库 pre-commit 静态检查(详见 pre-commit/pyproject.toml 中针对 ruff、pylint、bandit 的规则配置)共同构成了代码质量的第一道防线。
8. 将 Pull Request 与处理的 Issue 进行关联
- 访问仓库的
Issue列表,进入您本次 Pull Request 所处理的对应 Issue 页面; - 在 Issue 右侧的
Pull Requests中选择您提交的 PR 进行关联。
完成关联后,当 PR 被合并时,关联的 Issue 将被自动关闭。这一机制保证了"问题 → 修复 → 合入 → 关闭"的闭环可追溯,也是检视者快速理解 PR 背景的捷径。
9. 查看门禁状态以及代码检视意见
查看门禁状态
PR 提交后,请输入 /compile 触发门禁检查。从仓库的 CI 流水线配置 .gitcode/workflows/ascend-boost-comm_action.yml 可以看到,流水线的触发条件正是对 PR 评论内容的匹配(comments: '^(?:\/)?compile*')。检查时间每个仓库有所不同,请关注检查状态,并及时修改问题。
当页面显示"CI 任务执行 成功",且右上角标签显示 ci-pipeline-passed 时,即表示门禁检查通过。若编译失败,PR 会被打上 ci-pipeline-failed 标签(详见 CANN 社区用户交互流程 中 /compile 命令的说明)。
从 .gitcode/workflows/ascend-boost-comm_action.yml 的流水线定义可以看到,该仓库的门禁检查覆盖以下任务(各任务复用了 .gitcode/scripts/ 下的脚本):
| 任务 | 作用(从流水线配置推断) |
|---|---|
| PreBuild(镜像准备) | 准备编译与检查所需的基础镜像版本 |
| codecheck | 代码静态检查(pre-commit 规则) |
| x86_compile / arm_compile | x86 与 ARM 双架构编译验证 |
| UT_Test | 单元测试(对应 .gitcode/scripts/ut.sh) |
| staticcheck(markdown / codespell / tag_closed / resource_existence / link_validity) | 文档、拼写、标签闭合、资源存在性、链接有效性等静态检查 |
如果门禁检查任务中有任务失败,可以点击对应的 日志详情 中的 点击跳转 查看日志中的失败原因,对代码进行调整后重新提交。
查看代码检视意见
门禁检查通过后,您提交的 PR 会被分配给一个或多个检视者。这些检视者将进行彻底的代码检视,以确保提交的正确性,不仅包括代码的正确,也包括注释和文档等。您可以在 PR 列表内找到您提交的 PR,并看到对该 PR 的评论和评审意见。
检视通过后,社区 Bot 通过评论命令推进合入流程:检视者使用 /lgtm 添加"代码已经评审过"的标签,committers 使用 /approve 添加同意合并的标签,最终由 branch_keeper 使用 /merge 完成合入。各命令的使用范围与面向对象详见 CANN 社区用户交互流程。MR 评审的协作细则(如评审者人数、合入节奏、冲突处理原则)可参考代码提交规范中的 Code Review Merging 一节。
10. 常用操作
10.1 回退一个提交
如果您想回退提交,请采用下面的方式。
注意:如果您具有上游写访问权限,请不要使用 Gitcode UI 中
Revert按钮创建 PR,因为 Gitcode 会在主存储库而不是您的 fork 中创建 PR 分支。
- 创建一个分支并用 upstream 进行同步:
# 创建分支
git checkout -b myrevert
# 用 upstream 同步分支
git fetch upstream
git rebase upstream/master
-
根据您希望还原的提交类型选择命令:
-
merge commit(SHA 为要回退的 merge commit 的哈希):
git revert -m 1 SHA -
single commit(SHA 为要回退的单个提交的哈希):
git revert SHA
-
-
这将创建一个新的提交以回退到更新前,然后把这个提交推送到远程工作目录:
git push ${your_remote_name} myrevert
- 最后用这个分支创建一个 PR 即可完成回退合入。
10.2 处理提交冲突
如果您发现提交的 PR 带有冲突标记,说明您提交的 PR 和主干分支存在冲突,您需要处理冲突。
- 先将分支切换到 master 上,并完成 master 的 rebase:
git checkout master
git fetch upstream
git rebase upstream/master
- 再将分支切换到您使用的分支上,并开始 rebase:
git checkout yourbranch
git rebase master
- 此时您可以在 Git 输出中看到冲突的提示,您可以通过
vi等工具查看冲突的具体位置; - 解决冲突以后,再把修改提交上去:
git add .
git rebase --continue
git push -f origin yourbranch
git rebase --continue 会让 rebase 流程继续执行;由于 rebase 重写了提交历史,推送时必须使用 -f 强制推送。
10.3 合并提交(Squash)
如果您提交了一个 PR 以后,根据检视意见完成修改并再次提交,您不想让审阅者看到多次提交的 PR,因为这不便于继续在检视中修改,那么您可以合并提交。合并提交是通过压缩 Commit(squash)来实现的。
- 先在本地分支上查看日志:
git log
- 把顶部的 n 个提交记录聚合到一起(n 是一个数字):
git rebase -i HEAD~n
把需要压缩的日志前面的 pick 都改成 s,s 是 squash 的缩写。注意必须保留一个 pick,如果将所有的 pick 都改成了 s 就没有合并的目标了,会发生错误。
-
修改完成以后,按
ESC键,再输入:wq,会跳出一个界面询问是否进入编辑提交备注的页面,输入e以后,进入合并提交备注的页面。请把需要合并的备注都删掉,只保留合并目标的备注,再按ESC键,输入:wq保存退出即可。 -
最后完成提交:
git push -f origin yourbranch
- 回到 Gitcode 上的 PR 提交页面查看,您就可以看到之前的多次提交已经合并为一条干净的提交历史。
附:仓库内相关参考资源
- 本地构建与验证:README.md 的使用说明、编译说明;
- 社区 Bot 交互命令:CANN 社区用户交互流程;
- 提交与评审规范:代码提交规范、贡献指南;
- PR 描述模板:.gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md;
- CI 流水线定义:.gitcode/workflows/ascend-boost-comm_action.yml 及 .gitcode/workflows/ 下的各检查任务配置;
- pre-commit 静态检查规则:pre-commit/pyproject.toml。


