贡献指南

本项目欢迎广大开发者体验并参与贡献。在参与社区贡献之前，请参见 cann-community 了解行为准则，完成 CLA 协议签署，并熟悉源码仓的贡献流程。

准备工作

开发者在准备本地代码与提交 PR 时，需重点关注以下事项：

1. 提交 PR 时，请按照 PR 模板仔细填写本次 PR 的业务背景、目的、方案等信息。
2. 若您的修改涉及新增特性、新增接口、新增配置参数或修改代码流程等（非简单 bug 修复），请务必先通过 Issue 进行方案讨论，以避免代码被拒绝合入。若不确定修改是否属于"简单 bug 修复"，建议提交 Issue 进行讨论。

贡献场景

开发者贡献场景主要包括：

• 贡献新算子
• 算子 Bug 修复
• 算子优化
• 文档纠错
• 帮助解决他人 Issue

---

一、贡献新算子

算子开发贡献流程如下：

本仓生态算子面向特定网络与场景定制开发，支持定制算法快速验证使用。如果您有全新的算子希望基于 NPU 设计与实现，欢迎在 Issue 中提出您的想法与设计方案，并将算子贡献至 experimental 对应算子分类目录。完整的贡献过程如下：

1. 创建 Issue 需求

新建 Requirement|需求建议 类 Issue，并阐明新增算子的设计方案。Issue 一般需包含以下内容：

• 背景信息
• 价值/作用
• 设计方案

具体操作步骤请参阅：Issue 操作指南。

2. 需求评审

创建需求类 Issue 后，需申报 SIG 议题，并在指定时间参加 Ops-transformer SIG 例会评审。

• 会议议题&纪要
• 会议链接

紧急需求处理：

若需求紧急，可申请临时 SIG 会议：

1. 填写议题申请：议题申请
2. 发送邮件给 maintainer，建议邮件主题注明：申请临时 SIG 议题及议题内容

需求接纳：

若需求被接纳，SIG 成员将为您分配合适的算子分类路径（如：experimental/attention），请将贡献算子提交至 experimental 对应算子分类目录。

3. PR 提交

生态最简算子交付件

experimental/${op_class}          # 算子分类（experimental 目录下）
├── ${op_name}                    # 算子名
│   ├── ${op_name}.cpp            # 算子 Kernel 实现文件
│   ├── examples                  # 算子示例目录（看护基础场景，须可编译执行）
│   ├── tests                     # 测试目录（含定制场景用例）
│   │   └── test_${op_name}.py    # 算子测试文件
│   ├── CMakeLists.txt            # 算子编译配置文件
│   └── README.md                 # 算子 README 文档

PR 提交须知

提交前准备：

• 建议在需求评审通过后，再提交 PR。
• 提交 PR 前需完成开发环境准备，并仔细了解项目特定的开发规范和版权声明要求（如涉及开源代码片段引用，请参考片段引用指导），确保您的贡献符合项目标准，签署 CLA。具体操作步骤请参阅：PR 操作指南。

交付件要求：

类型	要求	参考资料
代码交付件	需提供算子 Kernel 实现、算子测试文件	fast_kernel_launch_example
文档交付件	算子 README 文档为必选，其余文档可视情况提供	文档贡献指南
精度要求	新贡献算子需满足精度标准	生态算子开源精度标准
覆盖率要求	算子测试文件需覆盖算子核心功能与主要分支，满足 UT 覆盖率要求；本地可通过 bash build.sh --experimental -u --cov 生成 lcov 覆盖率报告自查，CI 侧将按 tests/test_config.yaml 配置统计覆盖率	构建与测试说明
example 看护要求	需提供算子 example 看护算子基础场景，example 须可编译执行（本地可通过 bash build.sh --experimental --run_example ${op_name} eager 编译并执行验证，运行模式及可选参数详见 bash build.sh --help），CI 会按 tests/test_config.yaml 配置触发 examples 验证	fast_kernel_launch_example
用例上库要求	面向特定网络与场景定制的生态算子，其定制场景用例（典型网络 shape、典型配置下的功能与精度验证用例）须随代码一并上库至算子 tests 目录，确保算子可持续回归验证，用例生成规则参考生态算子开源精度标准	生态算子开源精度标准

合规检查：

• 代码是否符合《C++ 编程规范》
• 代码是否编译通过
• Markdown 文档语法是否符合规范
• 使用 git 进行代码提交前，可以参考 pre-commit 工具使用说明来使您的代码提交更合规高效

提交规范：

• 贡献目录：按 SIG 成员意见提交至指定目录 experimental/${op_class}，可参考已有算子文件放置规则。
• PR 提交：通过 git 命令提交目标分支 PR，检查 PR 标题是否清晰、PR 描述是否规范（指明更改内容和原因、是否关联对应 Issue）、是否签署 CLA。

说明：若希望直接贡献项目标准算子，其交付件与提交规范参见项目标准算子 PR 上库要求；生态算子转换为项目标准算子的流程，参见生态算子转换为项目标准算子。

4. CI 门禁

通过评论 compile 指令触发开源仓门禁，并依据 CI 检测结果进行修改。目前 CI 门禁包含以下检查项：

• 代码编译
• 静态检查（如涉及 codecheck 误报，请提交给 SIG 成员屏蔽）
• UT 测试（含覆盖率统计）
• 冒烟测试

门禁通过后，请在关联的 Issue 中 @ Committer。

5. Committer 检视

Committer 检视后将反馈检视意见，请根据意见修改，完成后 @ Committer。

6. Maintainer 合入

Committer 检视通过后，将标注 /lgtm 标签。Maintainer 最终审核，确认无问题后，将标注 /approve 标签合入 PR。

---

二、算子 Bug 修复

如果您在本项目中发现了某些算子 Bug，希望对其进行修复，欢迎您新建 Issue 进行反馈和跟踪处理。

您可以按照 提交 Issue/处理 Issue 任务 指引新建 Bug-Report|缺陷反馈 类 Issue 对 Bug 进行描述。

---

三、算子优化

如果您对本项目中某些算子实现有泛化性增强或性能优化思路，希望着手实现这些优化点，欢迎您对算子进行优化贡献。

您可以按照 提交 Issue/处理 Issue 任务 指引新建 Requirement|需求建议 类 Issue 对优化点进行说明，并提供您的设计方案。

---

四、文档纠错

如果您在本项目中发现某些算子文档描述错误，欢迎您新建 Issue 进行反馈和修复，文档规范参考 文档贡献指南。

您可以按照 提交 Issue/处理 Issue 任务 指引新建 Documentation|文档反馈 类 Issue 指出对应文档的问题。

---

五、帮助解决他人 Issue

如果社区中他人遇到的问题您有合适的解决方法，欢迎您在 Issue 中发表评论交流，帮助他人解决问题和痛点，共同优化易用性。

如果对应 Issue 需要进行代码修改，您可以在 Issue 评论框中输入 /assign 或 /assign @yourself，将该 Issue 分配给您，跟踪协助解决问题。

---

附录

项目标准算子介绍

本仓算子分为两类：正文所述的生态算子，以及项目标准算子（即非 experimental 算子），二者对比如下：

对比维度	项目标准算子	生态算子
目标场景	主流模型场景，追求高性能、高精度、高泛化	特定网络与场景定制开发
使用方式	随正式版本发布，支持作为项目标准算子使用	支持定制算法快速验证使用
贡献目录	${op_class}/${op_name}	experimental/${op_class}/${op_name}
交付件要求	完整交付件（op_host、op_kernel、UT、README 等）	最简交付件（Kernel 实现、example、测试文件、README），并满足覆盖率、example 看护与定制场景用例上库要求
评审重点	性能、精度、泛化性全面评审	功能正确性、定制场景适配、用例与覆盖率完备性

项目标准算子交付件

${op_class}                           # 算子分类
├── ${op_name}                        # 算子名
│   ├── op_host                       # 算子定义、Tiling 相关实现
│   │   ├── ${op_name}_def.cpp        # 算子定义文件
│   │   ├── ${op_name}_tiling.cpp     # 算子 Tiling 实现文件
│   │   ├── ${op_name}_tiling_${sub_case}.cpp  # 可选，子场景 Tiling 实现，${sub_case} 表示子场景（如 arch35）
│   │   ├── ${op_name}_tiling_${sub_case}.h    # 可选，子场景 Tiling 实现头文件
│   │   └── CMakeLists.txt
│   ├── op_kernel                     # 算子 Kernel 目录
│   │   ├── ${op_name}.cpp            # Kernel 入口文件，包含主函数和调度逻辑
│   │   ├── ${op_name}.h              # Kernel 实现文件，定义 Kernel 头文件，包含函数说明、结构定义、逻辑实现
│   │   ├── ${op_name}_tiling_data.h  # TilingData 文件，存储 Tiling 策略相关配置信息
│   │   └── ${op_name}_tiling_key.h   # TilingKey 文件，定义 Tiling 策略的 key，标识不同划分方式
│   ├── CMakeLists.txt                # 算子编译配置文件，保留原文件即可
│   ├── README.md                     # 算子说明文档
│   └── tests                         # 算子测试文件
│       └── ut                        # 算子 UT 测试文件

完整的算子目录结构（含各可选交付件）参见项目目录结构。

说明：op_host 目录下参与编译的 Tiling 实现文件，文件名须包含 _tiling 标识（如 ${op_name}_tiling.cpp、${op_name}_tiling_${sub_case}.cpp），否则不会被编译系统识别。针对子场景（如特定架构 arch35）拆分 Tiling 实现时，请遵循此命名规则。

项目标准算子 PR 上库要求

交付件要求：

类型	要求	参考资料
代码交付件	需提供 op_host 算子 Tiling 实现、op_kernel 算子 Kernel 实现、算子 UT 测试文件	算子开发指南
文档交付件	算子 README 文档为必选，其余文档可视情况提供	文档贡献指南

合规检查：

• 代码是否符合《C++ 编程规范》
• 是否符合标准算子基础编程规范
• 代码是否编译通过
• Markdown 文档语法是否符合规范

提交规范：

• 贡献目录：按 SIG 成员意见提交至指定算子分类目录（如 attention/${op_name}），可参考已有算子文件放置规则。
• PR 提交：通过 git 命令提交目标分支 PR，检查 PR 标题是否清晰、PR 描述是否规范（指明更改内容和原因、是否关联对应 Issue）、是否签署 CLA。

生态算子转换为项目标准算子

生态算子面向特定网络与场景定制开发，当算子稳定成熟后，可申请转换为项目标准算子。转换需满足以下条件：

• 项目标准算子要求：算子已在目标网络与场景中稳定验证，性能与精度满足项目标准算子的使用要求。
• 泛化性要求：算子具备良好的泛化能力，能够支撑主流模型场景的通用使用诉求。

转换流程如下：

1. 发起 Requirement|需求建议 类 Issue，说明算子的实际场景验证情况与泛化性表现，申请将算子从 experimental/${op_class}/${op_name} 迁移至对应算子模块目录 ${op_class}/${op_name}。
2. 申报 SIG 议题并参加评审：在议题申请页填写转换议题完成申报，并按议题安排参加 Ops-transformer SIG 例会评审（会议链接）；经 SIG 评审接纳后，按"项目标准算子交付件"标准补齐交付件（如 op_host Tiling 实现等）。
3. 通过 CI 门禁与 Committer 检视、Maintainer 合入后完成转换；转换后的算子后续随正式版本发布，支持作为项目标准算子使用。