CANN graph-autofusion 贡献指南从 Issue 讨论、代码规范到 pre-commit 与 PR 合入的完整实战流程【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion本篇技术指南以 CANN graph-autofusion 开源仓库的 CONTRIBUTING.md 为骨架系统讲解参与该昇腾自动融合项目Autofuse / SuperKernel 组件社区贡献的完整流程前置条件行为准则、CLA、GitCode 工作流、Issue 驱动的方案讨论机制、Google 代码规范、commit message 规范、pre-commit 本地自动化clang-format 格式化、ruff、OAT 合规扫描以及四大贡献场景的操作路径。读者学完后即可按规范完成一次从提 Issue到PR 合入的合规贡献闭环并理解流水线 code check 背后的本地实现原理。1. 参与贡献之前cann-community 前置流程CANN graph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合通过自动融合技术加速模型执行当前已开源 SuperKernel 与 Autofuse 两大组件见 README.md。在提交任何代码之前贡献者需要先完成社区准入流程。依据 CONTRIBUTING.md开发者须先前往cann-community社区仓库完成以下前置准备阅读并遵守社区行为准则Code of Conduct完成CLA 协议签署Contributor License Agreement了解源码仓的贡献流程包括如何提交 PRGitCode 工作流流水线触发命令代码检视Code Review规则其他注意事项。从仓库内容可以印证该项目深度依赖 GitCode 平台能力根目录的 .pre-commit-config.yaml 中所有 hook 均从gitcode.com的镜像仓拉取如pre-commit-hooks、mirrors-clang-format、ruff-pre-commit、codespellOAT 工具的 fallback 克隆地址同样指向 GitCode说明整个 CI/CD 与合规体系围绕 GitCode 生态运转。2. 本地代码准备与 PR 提交的五大硬性要点CONTRIBUTING.md 明确列出了开发者准备本地代码与提交 PR 时需要重点关注的 5 个事项这是保证 PR 不被流水线拦截、快速合入的关键。2.1 严格按 PR 模板填写信息提交 PR 时必须按照 PR 模板仔细填写本次 PR 的业务背景、目的、方案等信息。完整的背景与方案描述有助于评审者快速理解变更意图显著提升代码检视效率。2.2 非简单 Bug 修复先提 Issue 讨论方案这是本项目最核心的流程约束若您的修改不是简单的 bug 修复而是涉及以下任一情况新增特性新增接口新增配置参数修改代码流程必须首先通过 Issue 进行方案讨论以避免代码被拒绝合入。即使您不确定本次修改是否可被归为简单的 bug 修复也可以通过提交 Issue 进行方案讨论来获得官方判断。这一约束与方案先行、实现随后的开源协作原则一致能有效避免重复劳动和无效 PR。2.3 遵循 Google 开源代码规范提交 PR 时需确保代码符合 Google 开源代码规范覆盖范围包括代码格式化注释规范变量命名规范函数命名规范类命名规范接口命名规范配置参数命名规范代码流程规范。从仓库实际代码可以印证该规范的落地例如 autofuse/optimize/optimize.cpp、autofuse/common/code_printer.cpp 等源文件均遵循 Google C 风格命名空间、类名大驼峰、函数小驼峰、成员变量下划线后缀等而.clang-format风格的执行则交由 pre-commit 的 clang-format hook 自动完成见下文第 3 节。2.4 安装 pre-commit通过 clang-format 格式化流水线会执行code check未经过 pre-commit 中 clang-format 格式化的代码将被拦截。因此建议在仓库根目录安装 pre-commit# 安装 pre-commit 框架pip 方式 pip install pre-commit # 验证安装 pre-commit --version # 在仓库根目录安装 Git Hooks使本地 commit 时自动检查并格式化 pre-commit installpre-commit install执行后每次git commit都会自动触发 .pre-commit-config.yaml 中配置的全部 hook从根本上避免本地格式化正常、流水线拦截的返工。2.5 rebase 合并无效 commit规范 commit message提交 PR 时如果存在多个无效 commit建议在提交前先进行rebase操作将多个 commit 合并为一个以保持代码提交历史的简洁性和可读性。commit message 需要清晰描述本次变更的意图和内容格式为类型: 简短描述3. Commit Message 规范类型对照表commit message 的类型必须从下表中选择这是流水线与评审者识别变更性质的主要依据| 类型 | 说明 | 示例 | |--|--|--| | feat | 新功能 | feat: 添加用户注册功能 | | fix | 修复 bug | fix: 修复登录态过期问题 | | docs | 文档更新 | docs: 更新 API 使用说明 | | style | 代码格式调整不影响逻辑 | style: 调整代码缩进 | | refactor | 重构非功能新增/修复 | refactor: 优化用户服务类结构 | | perf | 性能优化 | perf: 减少数据库查询次数 | | test | 测试相关 | test: 添加登录功能单元测试 | | chore | 构建/工具链变更 | chore: 更新 webpack 配置 | | ci | CI 配置相关 | ci: 添加自动化测试流程 |4. 流水线 code check 的本地实现.pre-commit-config.yaml 深度解析CONTRIBUTING.md 提到的流水线 code check与pre-commit 中 clang-format在仓库中有完整的本地落地方案即根目录的 .pre-commit-config.yaml。理解这份配置就能理解一次本地 commit 究竟会经历哪些自动化检查。4.1 配置总览该文件声明了minimum_pre_commit_version: 4.0.0并将LICENSES/目录及html/csv/svg文件排除在检查范围之外所有 hook 仅在pre-commit阶段即提交时执行CI 侧关闭了自动修复 PRautofix_prs: false依赖自动升级按月度计划进行。4.2 六大基础检查pre-commit-hooks从 GitCode 的pre-commit/pre-commit-hooks仓rev v4.6.0引入Hook作用trailing-whitespace去除行尾多余空白end-of-file-fixer保证文件末尾有且仅有一个换行符check-yamlYAML 语法校验--allow-multiple-documents允许多文档check-added-large-files拦截误提交的大文件check-merge-conflict检测残留的合并冲突标记detect-private-key防止私钥等敏感信息入库4.3 C 格式化检查clang-format从pre-commit-clang/mirrors-clang-formatrev v18.1.8引入是 CONTRIBUTING 中未格式化代码被拦截的直接执行者- id: clang-format files: \.(c|h|cpp|hpp|cc|hh|cxx|hxx|asc)$ args: - --stylefile # 读取仓库根目录 .clang-format 配置 - --verbose - -i # 原地格式化修改文件 exclude: ^build/|tests/third_party/覆盖 C/C 及昇腾算子源码使用的.asc文件使用--stylefile模式即遵循仓库根目录.clang-format中的项目级风格定义-i表示直接改写文件内容因此本地 commit 时代码会被自动格式化而非仅仅告警。4.4 Python 检查ruff引入ruff-pre-commitrev v0.14.14包含两个 hookruff-check静态检查 Python 代码--output-format github以 GitHub 兼容格式输出问题--fix自动修复可修复项ruff-formatPython 代码格式化与 black 兼容的 ruff 原生 formatter。4.5 拼写检查codespell引入codespellrev v2.4.1用于扫描拼写错误。配置中通过-L白名单放行了 CANN 领域专有名词CANN、cann、NNAL、ASCEND、ascend、EnQue、CopyIn、ArchType、tbe、copyin 等并跳过*.py,*.cpp,*.hpp,*.c,*.h源码文件说明该 hook 主要面向文档与配置类文件的拼写检查。4.6 OAT 合规检查与路径保护local hooks配置末尾定义了两个本地repo: localhookreject-docs-superpowers执行 scripts/reject_forbidden_paths.sh该脚本通过git diff --cached --name-only --diff-filterACMRD -z枚举暂存文件凡命中docs/superpowers/前缀的路径一律拒绝提交并输出中文提示用于保护仓库策略指定目录。oat-check执行 scripts/oat_check.sh即 OAT 开源合规性扫描verbose: true保证检查输出对开发者可见。5. OAT 合规性检查原理、运行与问题处置OATOpen Source Audit Tool是自动集成到 Git 提交流程中的开源合规性检查工具。仓库根目录 OAT.xml 定义了其扫描策略全仓源码适用CANN-2.0许可证policyitem typelicense nameCANN-2.0 path.*与Huawei Technologies Co., Ltd.版权声明同时通过defaultPolicyFilter与copyrightPolicyFilter对 LICENSE、info、xml、csv、yaml、md、toml、svg 等文件类型跳过检查。5.1 检查内容与核心特点文件类型检查禁止提交二进制文件.so、.dll、.exe 等许可证头检查验证源代码文件包含合规的许可证声明增量检查仅检查暂存区staged待提交文件速度较快自动触发每次git commit自动运行详细报告在oat_reports/目录生成result.txt摘要跨平台支持 Windows / Linux / macOS。5.2 从源码看运行机制scripts/oat_check.sh 是当前仓库实际生效的 OAT 执行脚本Python 版替代早期基于 Java 二进制包的版本其核心流程可概括为解释器探测依次探测python3、python、py要求 Python 3.7依赖自愈若未安装oat-py自动执行pip install --quiet oat-py1.0.1收集暂存文件无参数时通过git diff --cached --name-only --diff-filterACM获取暂存文件有参数时直接使用传入文件列表并统一转换为绝对路径组装扫描命令python -m oat -mode s -s repo -r oat_reports -n repo名 -w 1 -f 文件列表若仓库根目录存在 OAT.xml 则追加-oatconfig OAT.xml解析报告从PlainReport_repo.txt中仅提取两类关键计数——Invalid File Type Total Count与License Header Invalid Total Count汇总写入oat_reports/result.txt并清理完整报告文件提交门禁两类问题总数大于 0 时输出合规问题详情并exit 1阻止提交否则exit 0放行。该脚本还内置了 .gitignore 提示若oat_reports/或log/未加入 .gitignore会给出警告避免扫描产物误入库。5.3 手动运行与结果查看# 推荐方式通过 pre-commit 运行 pre-commit run oat-check # 或直接运行脚本 bash scripts/oat_check.sh # 查看扫描摘要报告 cat oat_reports/result.txt摘要报告result.txt的标准输出形态如下以仓库实际脚本 scripts/oat_check.sh 的写入逻辑为准 OAT Scan Result Summary Scan Time: 扫描时间 Project: 仓库名 Files Checked: 检查文件数 ----------------------------------- Invalid File Type Total Count: 0 ----------------------------------- License Header Invalid Total Count: 0 5.4 两类必须修复的合规问题场景一发现无效文件类型如尝试提交 .so/.dll/.exe# 方法 1将二进制文件移出暂存区 git reset HEAD lib/libtest.so # 方法 2将二进制文件加入 .gitignore 后重新提交 echo *.so .gitignore echo *.dll .gitignore echo *.exe .gitignore git add .gitignore git commit -m update: add binary files to gitignore场景二许可证头缺失或格式错误在源文件顶部补充 CANN-2.0 许可证头。仓库所有源码均携带该头例如 scripts/oat_check.sh、OAT.xml 以及 .pre-commit-config.yaml其标准格式为/** * This program is free software, you can redistribute it and/or modify it under the terms and conditions of * CANN Open Software License Agreement Version 2.0 (the License). * Please refer to the License for details. You may not use this file except in compliance with the License. * THIS SOFTWARE IS PROVIDED ON AN AS IS BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. * See LICENSE in the root of the software repository for the full text of the License. */补充后可重新提交git add src/main.cpp src/utils.cpp git commit -m fix: add license headers5.5 环境问题的优雅降级策略从 scripts/oat_check.sh 的源码逻辑看OAT 检查对环境问题采取跳过检查、允许提交的友好策略当 Python 3.7 缺失、oat-py安装失败、oat 扫描返回异常退出码、报告文件缺失时脚本均输出警告后exit 0放行。但真正的合规性问题二进制文件、许可证头缺失会坚决阻止提交exit 1。这一设计保证合规门禁严格的同时不因环境故障阻断开发者正常流程。6. 四大贡献场景与 Issue 流转机制CONTRIBUTING.md 定义了开发者贡献的四大主要场景均以Issue 驱动 /assign认领为统一流转机制在 Issue 评论框中输入/assign或/assign yourself即可将该 Issue 分配给自己进行跟踪处理。6.1 Bug 修复发现项目中的 Bug 后新建 Issue 反馈并跟踪按照提交 Issue / 处理 Issue 任务指引新建Bug-Report|缺陷反馈类 Issue描述 Bug 现象、复现步骤与期望行为在评论框中输入/assign或/assign yourself认领该 Issue修复并提交 PRPR 中关联对应 Issue 编号。6.2 贡献新功能发现功能缺失、希望新增能力时新建Requirement|需求建议类 Issue对新增功能进行说明并提供您的设计方案输入/assign或/assign yourself认领跟踪实现结合第 2.2 节非简单 Bug 修复先提 Issue 讨论的要求方案成熟后再进入编码与 PR 阶段。6.3 文档纠错发现文档描述错误时新建Documentation|文档反馈类 Issue指出对应文档的问题位置与正确描述输入/assign或/assign yourself认领纠正文档描述后提交 PRcommit 类型使用docs:。6.4 帮助解决他人 Issue即使问题不是自己提出的也可以参与协作在 Issue 中发表评论交流解决方案帮助他人解决问题若对应 Issue 需要代码修改同样输入/assign或/assign yourself认领后跟踪协助。7. 一次完整的贡献流程速览综合 CONTRIBUTING.md、.pre-commit-config.yaml、scripts/oat_check.sh 与 docs/zh/precommit_guide.md一次规范贡献的完整闭环如下准入准备在 cann-community 阅读行为准则、签署 CLA、了解 GitCode 工作流与流水线触发命令方案确认非简单 Bug 修复先提 IssueBug-Report / Requirement / Documentation 类型/assign认领本地初始化pip install pre-commit在仓库根目录执行pre-commit install安装 Git Hooks编码与提交遵循 Google 代码规范commit 时自动触发六大基础检查、clang-format 格式化、ruff 检查、codespell 拼写检查、docs/superpowers路径保护与 OAT 合规扫描提交信息遵循类型: 简短描述规范合规问题处置OAT 发现二进制文件或许可证头问题时修复后重新提交必要时可用git commit --no-verify临时跳过但需自行补齐合规PR 提交按 PR 模板填写业务背景、目的、方案存在多个无效 commit 时先 rebase 合并流水线检视等待流水线 code check 通过并接受代码检视Code Review。8. 参考与延伸阅读贡献指南本文依据贡献指南英文版pre-commit 使用指导书OAT 安装步骤、跨平台依赖Java/Maven 版本要求、环境问题场景与处理办法的完整手册.pre-commit-config.yaml本地自动化检查的完整 hook 配置scripts/oat_check.shOAT 合规扫描的实际执行脚本Python 版OAT.xmlOAT 扫描策略CANN-2.0 许可证、版权策略、文件过滤与许可证匹配规则scripts/reject_forbidden_paths.sh受保护路径的拒绝提交逻辑README.md项目整体介绍、构建验证入口docs/zh/build.md与组件文档入口super_kernel/README.md、autofuse/README.md【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考