CANN graph-autofusion 贡献指南：从 Issue 讨论、代码规范到 pre-commit 与 PR 合入的完整实战流程-平芜编程栈

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）；
了解源码仓的贡献流程，包括：
- 如何提交 PR；
- GitCode 工作流；
- 流水线触发命令；
- 代码检视（Code Review）规则；
- 其他注意事项。

从仓库内容可以印证，该项目深度依赖 GitCode 平台能力：根目录的 .pre-commit-config.yaml 中所有 hook 均从gitcode.com的镜像仓拉取（如pre-commit-hooks、mirrors-clang-format、ruff-pre-commit、codespell），OAT 工具的 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 install

pre-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 的类型必须从下表中选择，这是流水线与评审者识别变更性质的主要依据：

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 侧关闭了自动修复 PR（autofix_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-yaml	YAML 语法校验（`--allow-multiple-documents`允许多文档）
check-added-large-files	拦截误提交的大文件
check-merge-conflict	检测残留的合并冲突标记
detect-private-key	防止私钥等敏感信息入库

4.3 C++ 格式化检查（clang-format）

从pre-commit-clang/mirrors-clang-format（rev v18.1.8）引入，是 CONTRIBUTING 中"未格式化代码被拦截"的直接执行者：

- id: clang-format files: \.(c|h|cpp|hpp|cc|hh|cxx|hxx|asc)$ args: - "--style=file" # 读取仓库根目录 .clang-format 配置 - "--verbose" - "-i" # 原地格式化修改文件 exclude: ^build/|tests/third_party/

覆盖 C/C++ 及昇腾算子源码使用的.asc文件；
使用--style=file模式，即遵循仓库根目录.clang-format中的项目级风格定义；
-i表示直接改写文件内容，因此本地 commit 时代码会被自动格式化而非仅仅告警。

4.4 Python 检查（ruff）

引入ruff-pre-commit（rev v0.14.14），包含两个 hook：

ruff-check：静态检查 Python 代码，--output-format github以 GitHub 兼容格式输出问题，--fix自动修复可修复项；
ruff-format：Python 代码格式化，与 black 兼容的 ruff 原生 formatter。

4.5 拼写检查（codespell）

引入codespell（rev 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: local）hook：

reject-docs-superpowers：执行 scripts/reject_forbidden_paths.sh，该脚本通过git diff --cached --name-only --diff-filter=ACMRD -z枚举暂存文件，凡命中docs/superpowers/前缀的路径一律拒绝提交并输出中文提示，用于保护仓库策略指定目录。
oat-check：执行 scripts/oat_check.sh，即 OAT 开源合规性扫描，verbose: true保证检查输出对开发者可见。

5. OAT 合规性检查：原理、运行与问题处置

OAT（Open Source Audit Tool）是自动集成到 Git 提交流程中的开源合规性检查工具。仓库根目录 OAT.xml 定义了其扫描策略：全仓源码适用CANN-2.0许可证（policyitem type="license" name="CANN-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-py>=1.0.1"；
收集暂存文件：无参数时通过git diff --cached --name-only --diff-filter=ACM获取暂存文件；有参数时直接使用传入文件列表，并统一转换为绝对路径；
组装扫描命令：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 headers"

5.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；
修复并提交 PR，PR 中关联对应 Issue 编号。

6.2 贡献新功能

发现功能缺失、希望新增能力时：

新建Requirement|需求建议类 Issue，对新增功能进行说明，并提供您的设计方案；
输入/assign或/assign @yourself认领，跟踪实现；
结合第 2.2 节"非简单 Bug 修复先提 Issue 讨论"的要求，方案成熟后再进入编码与 PR 阶段。

6.3 文档纠错

发现文档描述错误时：

新建Documentation|文档反馈类 Issue，指出对应文档的问题位置与正确描述；
输入/assign或/assign @yourself认领，纠正文档描述后提交 PR（commit 类型使用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 修复先提 Issue（Bug-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.sh：OAT 合规扫描的实际执行脚本（Python 版）
OAT.xml：OAT 扫描策略（CANN-2.0 许可证、版权策略、文件过滤与许可证匹配规则）
scripts/reject_forbidden_paths.sh：受保护路径的拒绝提交逻辑
README.md：项目整体介绍、构建验证入口（docs/zh/build.md）与组件文档入口（super_kernel/README.md、autofuse/README.md）

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

CANN graph-autofusion 贡献指南：从 Issue 讨论、代码规范到 pre-commit 与 PR 合入的完整实战流程