CANN ascend-transformer-boostATBGitcode 贡献工作流全指南从 Fork 到 PR 合入【免费下载链接】ascend-transformer-boost本项目是CANN提供的是一款高效、可靠的Transformer加速库基于华为Ascend AI处理器提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost本指南以 docs/contributors/gitcode-workflow.md 为主体系统讲解向 CANN ascend-transformer-boostATB加速库提交代码的完整 Gitcode 工作流从 Fork 个人分支、克隆到本地、分支管理与同步到提交 PR、关联 Issue、通过门禁检查和代码检视再到回退提交、解决冲突与合并提交等高频操作。读完本文你将掌握一套可复制的开源贡献实操流程并理解仓库门禁标签体系cann-cla/yes、ci-pipeline-passed、SC-SUCC、lgtm、approved的获取与闭环方法确保自己的 PR 能够顺利合入 ATB 主仓。1. 工作流全景与准备工作1.1 从 Issue 到 PR 合入的完整链路ATB 是 CANN 开放项目下的 Transformer 加速库其代码贡献采用标准的 Fork Pull Request 模式个人开发者无法直接向社区仓库 push 代码只能先在 Gitcode 上将官方仓库 fork 到个人账号在个人分支上完成开发与验证再通过 PR 将变更提交回主仓经门禁检查与检视者确认后合入。完整流程可归纳为发现/创建 Issue → /assign 认领 → Fork 官方仓库 → 克隆到本地 → 拉取个人分支 → 本地开发与构建验证 → 提交并推送分支 → 创建 PR → 关联 Issue → 评论 compile 触发门禁 → 门禁通过 检视意见闭环 → 获取 lgtm / approved 标签 → 自动合入 → 关闭 Issue关于 Issue 的创建与认领规范可参考 Issue 提交指南 和 贡献指南工作流中涉及的 Bot 评论命令可参考 CANN 社区命令参考。1.2 安装 Git开展工作流前请先在电脑上安装 Git 软件。若此前未使用过 Git可在搜索引擎中查找与自身操作系统Windows / Linux / macOS匹配的 Git 安装教程安装完成后可在终端执行git --version确认安装成功。1.3 找到 ATB 仓库在 CANN 的代码托管平台上找到 ascend-transformer-boostATB仓库后续所有 Fork、克隆、PR 操作都以该仓库为起点。仓库的克隆地址见第 2 节与本地构建说明可参见 编译与构建。2. 准备本地代码2.1 Fork 个人分支打开 ascend-transformer-boost 项目首页点击页面右上角的Fork按钮按照指引建立一个属于个人的云上 fork 分支。Fork 后你的个人账号下会生成一个独立的仓库副本地址形如https://gitcode.com/$user_name/ascend-transformer-boost后续所有修改都在这个个人仓库中完成与官方主仓互不影响。注意如果 Fork 失败并提示个人账号下已存在同名仓库原因通常是你的个人账号下已有名为ascend-transformer-boost的仓库例如之前 Fork 过。由于 Gitcode 通过个人账号 仓库名寻址不允许同名仓库并存可先修改或删除个人账号下的旧仓库再重新 Fork详见 常见问题与回答。2.2 把 Fork 分支克隆到本地① 创建本地工作目录为便于本地代码的查找和管理先创建本地工作目录mkdir ${your_working_dir}② 配置 Git 用户名和邮箱如已配置可跳过把 Git 的user设置为你的 Gitcode 个人名称git config --global user.name your Gitcode Name配置你的邮箱git config --global user.email emailyour_email.com提示该邮箱会成为 commit 的 committer 邮箱也是后续 CLA 校验的凭证见第 9 节请务必与 Gitcode 账号的提交邮箱保持一致。③ 注册 SSH 公钥避免每次输入账号密码生成 SSH 公钥ssh-keygen -t rsa -C your_emailexample.com cat ~/.ssh/id_rsa.pub登录 Gitcode 个人账户点击右上角个人头像进入个人设置页面在个人设置 → 安全设置下点击SSH 公钥在添加公钥内把cat命令获取到的公钥内容添加进去。在个人电脑上验证 SSH 注册是否生效ssh -T gitgitcode.com如果获得如下成功提示则表示 SSH 公钥已生效Hi $user_name! Youve successfully authenticated, but GITCODE.COM does not provide shell access.④ 复制远程仓库到本地切换到本地路径cd $your_working_dir在远程仓库首页单击克隆/下载得到$remote_link克隆时需创建令牌并输入以替代密码登录然后在本地执行# 下载个人 fork 仓库到本地 git clone https://gitcode.com/$user_name/ascend-transformer-boost.git # 设置本地工作目录的上游源官方原始仓库 git remote add upstream https://gitcode.com/cann/ascend-transformer-boost.git克隆完成后本地仓库会同时拥有两个远程源origin你的个人 fork和upstream官方主仓。origin用于推送你的个人分支upstream用于同步官方最新代码。2.3 拉取个人开发分支先更新本地分支到官方最新状态git fetch upstream git checkout master git rebase upstream/master再创建本地个人分支git checkout -b myfeaturemyfeature为个人分支名称后续所有代码修改都在这条分支上进行。分支命名建议语义化例如fix-xxx、add-xxx-op便于检视者理解 PR 意图。3. 本地构建和验证开发完成或开发过程中需要在本地完成构建与验证。ATB 的构建入口为bash scripts/build.sh进入仓库根目录执行即可完成编译cd ascend-transformer-boost bash scripts/build.sh该脚本支持多种参数以满足不同场景常用参数包括--use_cxx11_abi1/--use_cxx11_abi0启用/禁用 C11 ABI--torch_atb编译 pybind11 并生成 torch_atb 的 whl 包--debug设置构建类型为 Debug 模式--clean-first构建前清理所有构建历史unittest/kernelunittest/pythontest/alltest构建并运行对应类型的测试。完整的构建参数、ATB 关键文件与测试框架说明可参见 编译与构建 和 测试框架指南。对于算子类贡献可参考 从开发一个简单算子出发 或 开发指南 完成本地算子开发、构建与精度验证。4. 保持分支与 master 的同步社区代码在持续演进开发周期较长时你的个人分支会与官方 master 产生偏差。在myfeature分支上执行如下命令保持同步git fetch upstream git rebase upstream/master重要执行同步时请不要使用git pull替代上面的fetchrebase。pull默认会生成合并提交使提交历史变得混乱、代码更难理解。你可以通过修改.git/config文件或执行git config branch.autoSetupRebase always命令改变git pull的默认行为使其使用rebase。5. 在本地工作目录提交变更完成代码修改后提交变更git add . git commit -m 提交内容描述提交信息建议采用语义化描述如fix: correct xxx in xxx op、feat: add xxx operator并在必要处补充详细说明便于检视者与后续维护者理解。如果在前一次提交的基础上继续编辑、构建和测试了更多内容可以使用git commit --amend将新修改并入上一次提交避免产生冗余的提交记录。6. 将变更推送到远端分支准备提交审查或仅作异地备份时将分支推送到你在 Gitcode 上的 fork 仓库git push -f origin myfeature-f为强制推送由于 rebase / amend 会改写提交历史本地分支与远端分支的提交哈希不再一致此时需要强制推送覆盖远端旧记录。7. 在 Gitcode 上创建 Pull Request访问你的个人 fork 仓库页面https://gitcode.com/$user/ascend-transformer-boost单击Pull Request新建 PR。在创建新 PR 的界面确认源分支你的myfeature分支和目标分支官方仓库的master填写 PR 标题与描述后创建。PR 是对项目主分支的一次合并为保证合并质量请谨慎操作。建议在 PR 描述中说明变更背景、改动内容、验证结果并关联对应的 Issue见第 8 节。补充根据 贡献指南提交 PR 前建议先在 fork 仓中将AtlasAccount和openLiBingCI添加为成员权限至少为开发者及以上同时确认已有对应的 Issue若无则按模板创建。8. 将 Pull Request 与处理的 Issue 关联PR 与 Issue 的关联是社区问题跟踪闭环的关键一个 PR 应明确对应它要解决的 IssuePR 合入后该 Issue 将被自动关闭。访问仓库的Issue列表进入你本次 PR 所处理的对应 Issue 页面。在 Issue 右侧的Pull Requests中选择你提交的 PR 进行关联。完成关联后当 PR 被合并时关联的 Issue 将被自动关闭。提示PR 创建后若出现needs-issue标签说明当前 PR 未关联 Issue。请先将 PR 关联到对应 Issue再在 PR 评论区执行/check-issue让机器人重新校验校验通过后该标签会被移除详见 贡献指南。9. 查看门禁状态与代码检视意见9.1 触发门禁检查PR 提交后需要在 PR 评论区输入compile触发门禁CI检查。检查耗时因仓库而异请关注检查状态并及时修改问题。当页面显示CI任务执行 成功且右上角标签显示ci-pipeline-passed时表示门禁检查通过。如果门禁检查任务中有任务失败可点击对应日志详情中的点击跳转查看日志中的失败原因据此调整代码后重新评论compile触发检查。补充除了compile主流水线ATB 社区还支持评论compile#openlibing触发协同任务通过后获得SC-SUCC标签失败则为SC-FAIL。若提交 PR 后长时间未触发 CI通常是网络或调度原因导致 webhook 未及时到达可再次评论compile重试详见 常见问题与回答。9.2 门禁标签体系合入必要条件根据 贡献指南PR 合入必须满足以下标签与要求必须具备的标签标签含义cann-cla/yesCLA 校验通过ci-pipeline-passed主流水线compile通过SC-SUCC协同任务compile#openlibing通过lgtm检视者确认代码质量approvedcommitters 同意合并禁止存在的标签cann-cla/no、ci-pipeline-failed、SC-FAIL、needs-issue。检视意见要求PR 中所有检视意见/讨论必须全部处理完成无未解决意见。9.3 标签获取与常用 Bot 命令ATB 社区由 Bot 维护开发者可在 PR / Issue 评论区通过评论触发命令完整命令表见 CANN 社区命令参考命令使用范围作用/check-claPR强制重新检查 PR 的 CLA 状态通过打上cann-cla/yes否则打上cann-cla/no/check-issuePR重新校验 PR 是否关联 Issue通过后移除needs-issuecompilePR触发主流水线通过打上ci-pipeline-passed失败打上ci-pipeline-failed标签 72 小时时效过期需重新评论compile#openlibingPR触发协同任务通过打上SC-SUCC失败打上SC-FAIL/lgtmPR检视者添加代码已评审标签lgtm/approvePRcommitters 添加同意合并标签approved/check-prPR检查 PR 标签是否满足条件满足则合并/assignIssue将 Issue 分配给自己处理各标签的获取路径如下cann-cla/yes完成 CLA 签署并确认提交邮箱匹配后在 PR 评论区执行/check-cla刷新校验结果ci-pipeline-passed评论compile触发主流水线通过后获得有 72 小时时效之后被删除需重新评论SC-SUCC评论compile#openlibing触发协同任务通过后获得lgtm处理并回复完所有检视意见后在评论区输入QK_25415 nino888 goodpeople233 looking for lgtm检视并说明需要lgtm标签由检视者确认代码质量后添加approved在技术问题、流程标签和检视意见全部闭环后在评论区输入QK_25415 nino888 goodpeople233 looking for approved检视并说明需要approved标签由有权限的检视者最终确认后添加。满足以上全部条件后PR 将自动合入请及时确认问题已解决并关闭对应 Issue。9.4 查看代码检视意见门禁检查通过后PR 会被分配给一个或多个检视者。检视者将进行彻底的代码检视以确保提交的正确性——不仅包括代码逻辑正确也包括注释、文档等规范性内容。你可以在 PR 列表内找到自己提交的 PR查看检视者对 PR 的评论和评审意见并逐一回复、修改。10. 常用 Git 操作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 SHAsingle commit普通单提交# SHA 为要回退的单提交的哈希值 git revert SHA回退会创建一个新提交以撤销变更将其推送到远程工作目录git push ${your_remote_name} myrevert用该分支创建一个 PR 提交回退。10.2 处理提交冲突如果 PR 页面出现冲突标记说明你的分支与目标分支之间存在冲突需要先在本地解决先将分支切换到 master 上并完成 master 的 rebasegit checkout master git fetch upstream git rebase upstream/master再切换到你的开发分支开始 rebasegit checkout yourbranch git rebase master此时 Git 会提示冲突文件可通过vi等工具查看冲突内容冲突区域以、、标记分隔。解决冲突后将修改加入暂存区并继续git add . git rebase --continue git push -f origin yourbranch10.3 合并提交压缩 Commit如果按检视意见修改后产生了多次提交为便于检视者继续评审可以将多次提交压缩为一个在本地分支上查看提交日志git log将顶部的 n 个提交记录聚合到一起n 为数字git rebase -i HEAD~n把需要压缩的日志前面的pick都改成ss是squash的缩写。注意必须保留一个pick如果将所有pick都改成s就没有合并目标了会发生错误。修改完成后按ESC键再输入:wq会跳出编辑提交备注的界面输入e进入合并提交备注编辑页面把需要合并的备注都删掉只保留合并目标的备注再按ESC键输入:wq保存退出。完成提交git push -f origin yourbranch回到 Gitcode 上的 PR 提交页面查看即可看到之前的多次提交已合并为一次。11. 提交前的合规检查pre-commit / OATATB 仓库在提交环节还内置了代码质量与合规检查能力。仓库根目录的 pre-commit 配置见 pre-commit 配置指导书集成了代码格式化clang-format与 OATOpen Source Audit Tool合规扫描OAT 检查由 scripts/oat_check.sh 驱动主要校验两类问题无效文件类型禁止提交二进制文件.so、.dll、.exe等许可证头缺失/错误源码文件必须包含合规的许可证声明。本地安装 pre-commit 后pip install pre-commit并在仓库根目录执行pre-commit install每次git commit会自动触发格式化与合规检查。OAT 检查报告生成在oat_reports/result.txt当发现二进制文件或许可证头问题时提交会被阻止需修复后重新提交。另外根据 贡献指南ATB 软件编码遵循 CANN Open Software License Agreement Version 2.0见 LICENSE。新建的.cpp、.cc、.h等源文件头部需添加版权声明.py、.sh等文件需添加对应的#注释声明并将[Name of the copyright owner]替换为你的署名或雇主名称、年份替换为实际创建年份。12. 全流程自检清单提交 PR 前建议对照以下清单逐项确认已签署 CLA个人/法人/法人贡献者且 commit 邮箱与 Gitcode 提交邮箱一致已完成 Issue 创建与/assign认领并确认 PR 已关联对应 Issue已在 fork 仓添加AtlasAccount与openLiBingCI为成员已基于upstream/masterrebase 并解决冲突本地构建与测试通过新文件已添加 CANN Open Software License Agreement Version 2.0 版权声明本地 pre-commit / OAT 检查通过无二进制文件与许可证头问题PR 评论区已评论compile与compile#openlibing标签cann-cla/yes、ci-pipeline-passed、SC-SUCC已就位已处理全部检视意见并获取lgtm与approved标签PR 合入后确认问题已解决并关闭对应 Issue。遵循以上流程你的代码贡献即可顺利进入 ATB 社区主仓。工作流中遇到具体问题时还可查阅 常见问题与回答 与 命令参考 获取进一步帮助。【免费下载链接】ascend-transformer-boost本项目是CANN提供的是一款高效、可靠的Transformer加速库基于华为Ascend AI处理器提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考