感谢您考虑为 OpPlugin 做出贡献！我们欢迎任何形式的贡献，包括错误修复、功能增强、文档改进等。无论您是经验丰富的开发者还是第一次参与开源项目，您的帮助都是非常宝贵的。
OpPlugin 是 Ascend Extension for PyTorch（torch_npu）的算子插件，为使用 PyTorch 框架的开发者提供便捷的 NPU 算子库调用能力。本项目旨在为 torch_npu 提供运行所需要的算子适配文件。
op-plugin
├── ci/ # CI 构建脚本
│── docs/ # 项目文档
├── op_plugin/ # 核心算子插件实现
│ ├── ops/ # 算子实现
│ │ ├── aclops/ # ACL 算子内核实现
│ │ ├── atb/ # ATB 算子实现
│ │ └── opapi/ # OpAPI 算子封装
│ ├── python/ # Python 接口
│ ├── config/ # 算子配置
│ ├── utils/ # 工具类
│ └── third_party/ # 第三方依赖
├── examples/ # 示例代码
│ ├── aclnn_extension/ # ACLNN 扩展示例
│ ├── cpp_extension/ # C++ 扩展示例
│ └── framwork_cpp_extension/ # 框架 C++ 扩展示例
├── torchnpugen/ # 代码生成工具
│ ├── struct/ # 数据结构生成
│ ├── api/ # API 生成
│ └── templates/ # 代码模板
└── test/ # 测试用例| 模块 | 说明 |
|---|---|
op_plugin/ops/aclops |
ACL 算子内核实现：基于 AscendCL 的算子底层实现 |
op_plugin/ops/atb |
ATB 算子实现：Transformer 加速库算子封装 |
op_plugin/ops/opapi |
OpAPI 算子封装：PyTorch 算子接口适配层 |
op_plugin/config |
算子配置：derivatives.yaml 定义算子求导规则 |
torchnpugen |
代码生成工具：自动生成算子适配代码 |
test/test_base_ops |
算子测试：覆盖各算子的功能验证 |
我们热情期待您的加入！每一个贡献都是推动 OpPlugin 进步的重要力量：
- 反馈问题：报告 Bug 或提交功能建议，帮助我们发现并解决问题
- 贡献代码：提交代码修复或新功能实现，直接参与项目开发
- 完善文档：改进文档或补充缺失内容，提升项目可读性
- 代码审查：审查 Pull Request，帮助提升代码质量
- 分享传播：在博客、社交媒体上分享项目，给仓库点个 ⭐
本项目热烈欢迎各种形式的贡献，期待您的参与！
如果您有新功能建议或性能优化想法，我们热情邀请您提交 Issue 与社区深入讨论。
Issue 类型：需求/功能建议
需要包含的内容：
- 功能背景：该功能解决什么问题、能为用户带来什么价值
- 功能描述：详细描述建议的功能
- 设计方案：技术思路、关键模块设计、上下游组件关系
- 预期收益：功能目标、性能指标、精度表现
如果您发现 Bug 或文档问题，我们真诚欢迎您的反馈和修复建议。
Bug Report 格式：
- 环境信息：OpPlugin 版本、torch_npu 版本、Python 版本、CANN 版本等
- 问题描述：添加标签以便在问题仪表板上突出显示
- 复现步骤：尽可能详细地描述如何重现问题
- 预期行为：描述您预期发生的行为
- 给审稿人的特别说明：如有任何特殊情况
修复流程：
- 在 Issue 中找到对应的 Bug 描述
- 评论
/assign认领该任务 - 创建分支进行修复
- 提交 Pull Request
如果您有能力解决他人提出的问题，我们热烈期待您在 Issue 中分享您的解决方案。
在您第一次向 OpPlugin 社区提交代码之前，需要签署 CLA。
对于个人贡献者，详细信息请参考 ICLA 在线文档。
-
Fork 仓库：在 GitCode 平台点击仓库右上角 "Fork" 按钮，将仓库克隆到个人账户
-
克隆到本地：
git clone https://gitcode.com/<your-username>/op-plugin.git cd op-plugin
-
创建开发分支：
git checkout -b {new_branch_name} origin/master -
代码开发：请遵循 代码规范
-
代码测试：运行测试确保代码功能正常
-
门禁检查：运行 CI 检查，确保代码通过编译、静态检查、UT 测试
-
提交 Pull Request：提交 PR 并等待代码审查
-
社区评审：如果涉及 patch、头文件宏、API 接口等更新，需提交社区评审
以下类型的修改需要社区评审：
- Patch 替换：对 PyTorch 原生接口的 patch 替换
- 头文件宏更新：新增或修改宏定义
- API 接口变更：新增、修改或删除公共 API
- 核心组件变更：内存管理、设备管理等核心模块的修改
计算类新增 API 接口约束：
对于计算类新增 API 接口，提交者需要额外提供精度测试结果，确保新接口的计算精度符合要求。精度测试应包括：
- 与 PyTorch CPU/GPU后端的对比结果
- 误差范围统计（最大误差、平均误差、均方根误差等）
- 典型场景验证（如神经网络模型中的实际表现）
- 入参全覆盖：所有入参类型均需覆盖，包括必填参数、可选参数、默认值场景
- 测试方法：通过等价类划分、边界值分析等测试方法，覆盖正常传参与异常传参场景
- 异常处理：验证异常场景的报错信息是否准确、友好
- 测试用例数量：每个 dtype 泛化 100~200 个测试 case
- 算子覆盖：正向算子和反向算子分别按照 2 个 API 生成测试用例
- 精度阈值：计算结果误差需在允许范围内，确保与 CPU/GPU 结果一致
算子适配开发需交付以下内容：
| 交付件 | 说明 |
|---|---|
| yaml 配置 | 在 op_plugin_functions.yaml 中声明算子版本、schema、适配方式 |
| 前反向绑定配置 | 在 derivatives.yaml 中配置算子的前反向绑定关系（仅需前反向绑定的算子） |
| 算子适配代码 | 在 op_plugin/ops/opapi/ 或 op_plugin/ops/aclops/ 目录下实现算子接口 |
| 单元测试用例 | 在 test/test_base_ops/ 目录下编写功能测试和精度测试 |
| 接口文档 | 更新算子对外接口文档（自动生成或手动补充） |
请遵循这些风格，使 OpPlugin 易于开发、审查和维护。
- Python：建议使用 PEP 8 编码样式
- C++：建议使用 Google C++ 编码指南
可使用工具检查代码格式：CppLint、CppCheck、pylint
- Python：建议使用 pytest
- C++：建议使用 Googletest Primer
测试用例的设计意图应该通过它的注释名称来反映。
我们鼓励开发人员重构代码以消除代码异味。所有的代码都应该符合编码风格和测试风格的需求。
本项目使用 pre-commit 在提交代码前自动执行静态检查与风格修复，确保代码质量一致性。
# 安装 pre-commit 工具
pip install pre-commit
# 在仓库根目录注册 Git hooks
pre-commit install# 对所有已暂存文件执行检查（提交时自动触发）
git commit -m "your message"
# 只检查当前在工作区中的修改的文件
pre-commit run
# 手动对所有文件执行一次完整检查
pre-commit run --all-files
# 手动指定检查工具运行，以下命令hook-id在.pre-commit-config.yaml中查看。
pre-commit run <hook-id>
# 自动修复代码风格（仅运行具备 auto-fix 能力的 hook）
pre-commit run ruff-check
pre-commit run ruff-format
pre-commit run clang-format部分 hook（如
ruff-format、clang-format）会直接修改文件，修复后需重新git add再提交。
| 工具 | 版本 | 适用范围 | 功能说明 |
|---|---|---|---|
| trailing-whitespace | v4.6.0 | 所有文件 | 删除行尾多余空白字符 |
| end-of-file-fixer | v4.6.0 | 所有文件 | 确保文件以换行符结尾 |
| check-yaml | v4.6.0 | YAML 文件 | 校验 YAML 语法合法性 |
| check-added-large-files | v4.6.0 | 所有文件 | 阻止提交超大文件 |
| check-merge-conflict | v4.6.0 | 所有文件 | 检测未解决的合并冲突标记 |
| detect-private-key | v4.6.0 | 所有文件 | 检测私钥等敏感信息泄露 |
| check-json | v4.6.0 | JSON 文件 | 校验 JSON 语法合法性 |
| ruff-check | v0.14.14 | Python 文件 | Python lint 检查，并自动修复可修复问题 |
| ruff-format | v0.14.14 | Python 文件 | Python 代码格式化（替代 black） |
| codespell | v2.4.1 | 非代码文件 | 拼写错误检查（跳过 .py/.cpp/.h 等源码文件） |
| pylint | v4.0.5 | Python 文件 | Python 代码质量深度检查 |
| bandit | v1.9.4 | Python 文件 | Python 安全漏洞静态扫描 |
| typos | v1.32.0 | 所有文件 | 快速拼写错误检测（基于 Rust 实现） |
| clang-format | v18.1.8 | C/C++ 文件 | C/C++ 代码格式化，读取 .clang-format 配置 |
编译构建：
# 安装依赖并编译
bash ci/build.sh
# 或使用 CMake 手动编译
mkdir build && cd build
cmake ..
make -j$(nproc)合入检查清单（详细要求参考 PR 模板）：
- 代码编译通过
- 静态检查通过（CppLint、CppCheck 等）
- UT 测试用例通过
- 代码风格符合规范（PEP 8、Google C++ Style）
- 提交信息规范（符合 Conventional Commits）
- PR 标题正确使用类型标签（feat、fix、refactor、docs、test 等）
- 代码注释完备，正确记录错误日志
- 代码实现进行了返回值、空指针等校验
- 计算类 API 新增需提供精度测试结果
测试用例位置：
test/test_base_ops/- 算子基础功能测试test/core_tests/- 核心功能测试
运行测试：
# 安装测试依赖
pip3 install -r test/requirements.txt
# 运行单个测试文件
python test/test_base_ops/test_add.py
# 或使用 run_test.py
python test/run_test.py -i test_add门禁异常主要包含如下几种，请根据相关提示解决：
- 编译异常：请检查代码编译失败的原因，解决问题后重新编译
- 静态检查异常：请依照提示查找代码中的问题并解决（如代码风格、潜在 Bug 等）
- UT 测试未通过：请根据提示查找测试用例不通过项并检查原因
-
推送代码到远程仓库：
git add . git status git commit -m "Your commit title" git commit -s --amend # 添加详细描述 git push origin {new_branch_name}
-
创建 Pull Request
在 GitCode 上创建 Pull Request，根据 PR 模板 完整填写：
- 合入来源
- 修改方案
- 资料变更
- 接口变更
- 功能验证
- CheckList
确认信息完整准确后提交 Pull Request，等待代码审查。
我们致力于为所有参与者提供一个友好、安全、包容的环境：
- 尊重差异：尊重不同的观点和经验，包容多元文化
- 开放心态：接受建设性的批评，持续学习和进步
- 聚焦贡献：关注对社区最有利的事情，推动项目发展
- 同理心：对其他社区成员表示同理心，互帮互助
我们为您提供多种沟通渠道，方便您参与社区互动：
- Issues：用于报告 Bug、提出功能建议
- Pull Requests：用于代码审查和讨论
我们热烈欢迎每一位开发者积极参与社区讨论！期待与您共同成长：
- 发现未解决的问题：欢迎在 Issue 中发表评论，展示您的解决方案
- 遇到长期未处理的问题：建议在解决前进行预检查，避免重复工作
- 成功解决了自己报告的问题：也请分享您的解决方案，让社区一起学习和进步
有任何疑问，随时欢迎在社区中交流讨论，期待您的精彩贡献！