ascend-boost-comm 贡献指南：基于 GitCode 的 Fork–PR 协作工作流全流程实战-港品优选

ascend-boost-comm 贡献指南：基于 GitCode 的 Fork–PR 协作工作流全流程实战

【免费下载链接】ascend-boost-comm算子公共平台，南向对接不同组织开发的算子库，北向支撑不同加速库应用，实现M x N算子能力复用项目地址: https://gitcode.com/cann/ascend-boost-comm

本文以 ascend-boost-comm 仓库官方文档 GitCode Workflow 为主线，系统讲解向该算子公共平台提交代码的完整协作流程：从 Fork 个人分支、克隆与 SSH 配置、创建本地分支与本地构建验证，到提交 Pull Request（PR）、关联 Issue、通过 CI 门禁与代码检视，以及回退提交、解决冲突、合并提交等高频实战操作。读完本文，你将能够独立走通一次从"云端 Fork"到"代码合入 master"的完整贡献闭环，并掌握与社区 CLA / CI 机器人协作的关键注意事项。

1. 开展工作流前的准备

在开始 GitCode 工作流之前，需要确认以下两项基础条件：

安装 Git：请先确保本机已经安装 Git 软件。关于 Git 的安装与基础用法，可通过 Google、Baidu 等搜索引擎获取帮助。
找到目标仓库：ascend-boost-comm 是 Ascend 代码托管平台（GitCode）上的一个开源仓库，其原始（上游）地址为https://gitcode.com/cann/ascend-boost-comm。后续所有 Fork、Clone、Upstream 操作都围绕该仓库展开。

补充：ascend-boost-comm 是 CANN 的算子公共平台，南向对接不同组织开发的算子库，北向支撑不同加速库应用，实现 M × N 算子能力复用。项目官方约定的贡献三步流程为：Fork 仓库 → 修改并提交代码 → 创建 Pull Request（见 README_en.md）。在正式开始前，还建议先阅读贡献指南，其中要求贡献者先签署 CLA（Contributor License Agreement）：社区按 Corporate、Corporate Contributor、Individual、Enterprise Admin 四类提供签署入口，未签署时 PR 会被打上ascend-cla/no红色标签（详见第 9 节）。

2. 准备本地代码

2.1 Fork 个人分支

打开 ascend-boost-comm 项目的首页。
点击页面右上角的Fork按钮，按照指引在云端建立一个属于"个人"的 fork 分支。

提示：如果 Fork 失败，通常是个人账号下已存在同名仓库（GitCode 通过"个人账号 + 仓库名"寻址，不允许同名仓库并存），可先修改个人账号下已有仓库的名称和路径，再重新 Fork（见常见问题）。

2.2 把 Fork 分支克隆到本地

按以下步骤将 fork 仓库的代码下载到本机。

① 创建本地工作目录，便于后续代码的查找与管理：

mkdir ${your_working_dir}

② 完成 Git 用户名和邮箱的全局配置（若已配置过可跳过）。将user.name设置为你的 GitCode 个人名称：

git config --global user.name "your Gitcode Name" git config --global user.email "email@your_email.com"

③ 完成 SSH 公钥注册（若未注册，后续每次推送都需要重新输入账号和密码）：

生成 SSH 公钥：

ssh-keygen -t rsa -C "your_email@example.com" cat ~/.ssh/id_rsa.pub

登录 GitCode 账号添加公钥：点击右上角"个人头像"进入个人设置，在个人设置 → 安全设置 → SSH 公钥中，将cat命令获取到的公钥内容添加到"添加公钥"区域。
在本机完成 GitCode 的 SSH 注册验证：
```
ssh -T git@gitcode.com
```
如果得到如下"成功"提示，则表示 SSH 公钥已经生效：
Hi $user_name! You've successfully authenticated, but GITCODE.COM does not provide shell access.

④ 复制远程仓库到本地：

切换到本地工作目录：
```
cd $your_working_dir
```
在需要下载的远程仓库首页单击"克隆/下载"，获取$remote_link。克隆弹窗默认展示 HTTPS 与 SSH 两个标签页，其中 HTTPS 方式需要创建个人访问令牌（Token）代替登录密码：
在本机执行如下命令：先克隆你的 fork 仓库，再为本地目录添加"上游源"（原始仓库）：
```
# 下载 fork 仓库到本地 git clone https://gitcode.com/$user_name/ascend-boost-comm.git # 设置本地工作目录的上游源（原始仓库） git remote add upstream https://gitcode.com/cann/ascend-boost-comm.git
```
说明：origin指向你的个人 fork，upstream指向社区主仓库。此后同步主仓库更新、创建 PR 都依赖这两个远程源，请务必配置完整。

2.3 拉分支

先更新本地主分支，使其与上游 master 保持一致：

git fetch upstream git checkout master git rebase upstream/master

再创建本地个人开发分支：

git checkout -b myfeature

myfeature为个人分支名称，后续的代码编辑与修改都将在该分支上进行，避免直接污染 master 分支。

3. 本地构建与验证

代码修改完成后，需要在本地完成构建与验证。官方文档指向了使用说明（README_en.md 的 Usage Instructions 一节），其中给出了两种典型应用场景，这里摘录关键流程供贡献者参考。

环境准备要点（详见环境设置）：

编译依赖（必需）：Python 3.10.x 或 3.11.x、cmake ≥ 3.20、gcc/g++ 建议 7.3.1-11.x；若使用 GCC ≥ 12，编译命令需追加--no_werror（项目默认开启-Werror，见 cmake/host_config.cmake）。
运行示例/测试依赖（仅编译运行示例和测试时需要）：PyTorch ≥ 2.1.0 及与之匹配的 torch_npu。

场景一：单算子项目验证（以 example/ops/addcustom 下的 addcustom 算子为例）。首次编译需先编译 testframework，再编译 example：

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 驱动环境可用。若要开发自己的自定义算子，可参考自定义算子开发示例以及示例算子的算子实现 addcustom_operation.cpp 与测试用例 test_addcustom.py。

场景二：随加速库一起编译打包：将 ascend-boost-comm 与加速库（如 Ascend Transformer Boost）放在同级目录，先用算子命名空间作为参数编译 ascend-boost-comm 并把输出拷贝到加速库的 3rdparty 目录，再编译加速库即可。

补充：编写代码时请遵守代码提交规范：AscendC 相关代码使用驼峰命名，CCE intrinsic 相关变量使用小写字母加下划线，类名使用大驼峰；目录和文件名使用小写字母加下划线，且内容需与文件中的主类或主接口保持一致。同时，新增源码文件（如.cpp、.cc、.h、.py、.sh）需在文件头部添加 CANN Open Software License Agreement Version 2.0 的版权声明（模板见贡献指南）。

4. 保持分支与 master 同步

在开发过程中，主仓库 master 可能不断有新代码合入。为保证分支始终基于最新代码，需要在myfeature分支上执行：

# 在 myfeature 分支上执行 git fetch upstream git rebase upstream/master

注意事项：合并（同步）时不要使用git pull替代上述fetch+rebase组合，因为git pull默认的 merge 行为会使提交历史变得混乱，增加代码理解与检视的难度。如果确实希望保留git pull的用法，可以通过修改.git/config文件改变git pull的默认行为：

git config branch.autoSetupRebase always

5. 在本地工作目录提交变更

提交你的变更：

git add . git commit -m "提交内容描述"

如果在前一次提交的基础上继续编辑、构建并测试了更多内容，可以使用--amend将新改动追加到上一次提交：

git commit --amend

补充：根据代码提交规范，MR（PR）统一标题格式建议为[bug/feature/task] Fix XX issue / Add XX feature / Rectify XX issue，提交说明中应简要描述需求来源、修改内容等，涉及接口变更时需特别说明并与上游组件同步。另外，commit 中使用的邮箱必须与 GitCode 提交邮箱一致，否则会触发ascend-cla/no标签（详见第 9 节）。

6. 将变更推送到远端 fork 仓库

当改动准备进入评审（或只是想建立一份远端备份）时，把分支推送到你在 GitCode 上的 fork 仓库：

git push -f origin myfeature

说明：这里使用-f（force）是因为经过rebase重写后的提交历史与远端不一致，需要强制推送覆盖。仅在个人 fork 分支上使用-f是安全的，但不要对多人共享的分支随意强推。

7. 在 GitCode 上创建 Pull Request

访问你在https://gitcode.com/$user/ascend-boost-comm的 fork 仓库页面，单击右上角的+ Pull Request（或+ 新建 Pull Request）按钮。
在创建新 PR 的界面中，确认源分支（source）和目标分支（target）：源分支是你的myfeature个人分支，目标分支通常是上游主仓库的master，确认无误后创建 PR。

提交 PR 是对项目主分支的一次合并操作，为保证合并质量，请谨慎操作：提交前确保本地构建与测试已通过，提交信息清晰规范。

8. 将 Pull Request 与处理的 Issue 进行关联

访问仓库的Issues列表，进入本次 PR 所处理的对应 Issue 页面。
在 Issue 右侧的Pull Requests区域，选择你提交的 PR 进行关联。完成关联后，当该 PR 被合并时，关联的 Issue 会被自动关闭。

补充：关于 Issue 的提交与处理，可参考 Issue 提交指南：在仓库 Issue 板块单击"新建 Issue"，按诉求选择 Issue 类型并按照系统模板详细填写标题与内容后创建即可，无需填写负责人，仓库接口人会定时审视并按类型分配。如果你想认领某个 Issue，在评论区输入/assign或/assign @yourself即可将 Issue 指派给自己（见贡献指南）。

9. 查看门禁状态与代码检视意见

查看门禁（CI）状态

PR 提交后，在 PR 评论区输入/compile触发门禁检查。检查时间因仓库而异，请持续关注检查状态，并及时修改暴露的问题。
当页面显示"CI 任务执行成功"，且 PR 右上角标签显示ci-pipeline-passed时，表示门禁检查通过：
如果门禁检查任务中有任务失败，可点击对应"日志详情"中的"点击跳转"，在日志中查看失败原因并据此调整代码。

补充：根据常见问题，如果 PR 提交后迟迟未触发 CI，通常有两种原因：一是网络或任务调度导致 webhook 通知延迟，此时在 PR 评论区评论/retest可重新触发；二是仓库刚创建不久、Jenkins 侧尚未建立构建工程，此时/retest不生效，需等待系统自动创建工程。

查看代码检视意见

门禁检查通过后，PR 会被分配给一个或多个检视者。检视者会进行彻底的代码检视以确保提交的正确性——不仅包括代码本身，也包括注释和文档。你可以在 PR 列表中找到自己提交的 PR，并查看针对该 PR 的评论和评审意见。

补充：PR 页面上的常见状态标签含义如下（详见常见问题）：
ascend-cla/no（红色）：PR 包含未签署 CLA 的贡献者的 commit。CLA 检查基于 commit 信息（邮箱）验证，若 commit 邮箱与 GitCode 提交邮箱一致，直接用该邮箱签署 CLA 即可；若不一致，可在 GitCode 个人设置中添加并设置提交邮箱，或通过git config --global user.name/user.email调整本地 commit 邮箱后重新签署。
ascend-cla/yes（绿色）：CLA 已签署，合规。
ci-pipeline-passed（绿色）：CI 流水线通过。
存在冲突（红色）：PR 与主仓库存在冲突，需按"常用操作 → 处理提交冲突"解决。
此外，社区合入代码依赖评审流程：非 maintainer 贡献者不能直接向仓库（包括保护分支与非保护分支）push 代码；maintainer 对非保护分支可直接 push，但对保护分支也只能通过评论由 CI-bot 代为合入。通过评论/lgtm、/approve合入可以保证一份代码至少获得提交者以外一位 maintainer 的评审同意。

常用操作

回退一个提交

如果想回退提交，请按以下步骤操作。

注意：如果你具有上游（主仓库）写权限，请不要使用 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 即可。

处理提交冲突

当 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

合并提交（Squash）

提交 PR 后，如果根据检视意见完成修改并再次提交，不想让审阅者看到多次提交记录（多次提交不便于继续在检视中修改），可以压缩（squash）提交，将多个 commit 合并为一个。

先在本地分支上查看日志：
```
git log
```
将顶部的 n 个提交记录聚合到一起（n 为数字）：
```
git rebase -i HEAD~n
```
把需要压缩的日志前面的pick都改成s（squash 的缩写）。注意必须保留至少一个pick——如果所有pick都改成了s，就没有了合并的目标，会发生错误。
修改完成后按ESC键，再输入:wq保存退出。此时会跳出一个界面询问是否进入编辑提交备注的页面，输入e进入合并提交备注的编辑页。请把需要合并的备注都删掉，只保留合并目标的备注，然后按ESC键，输入:wq保存退出。
最后完成推送：
```
git push -f origin yourbranch
```
回到 GitCode 上的 PR 提交页面查看，即可看到之前的多次提交已合并为一次。

至此，你已经掌握了 ascend-boost-comm 项目从 Fork、克隆、建分支、本地构建验证，到提交 PR、关联 Issue、通过 CI 门禁与代码检视，以及回退提交、解决冲突、合并提交的完整 GitCode 协作工作流。这套流程同样适用于 CANN 社区其他开源仓库的代码贡献，建议在实操中配合贡献指南、代码提交规范与常见问题一起查阅，确保提交规范、合规且顺利合入。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析