CANN pyasc 贡献指南：从特性分级、Issue 创建到代码合入的完整实践-北京尧图网络

CANN pyasc 贡献指南从特性分级、Issue 创建到代码合入的完整实践【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyascCANN pyasc 是一个为昇腾 AI 处理器提供 Python 算子编程接口的开源项目其接口与 Ascend C 一一对应并遵循 Python 原生语法。本文基于仓库根目录的 CONTRIBUTING.md 贡献指南系统梳理 pyasc 社区贡献的完整链路——特性分级L1/L2/L3、Issue 创建、方案评审、experimental 与 master 双分支合入流程、PR 上库要求代码/文档交付件与合规检查并结合仓库内的开发指南、门禁脚本与测试目录说明一次从 Issue 到合入的贡献应如何落地。读完本文你将掌握 pyasc 社区贡献的规范化流程以及为 pyasc 新增一个 Ascend C API 的 Python 编程接口时所需准备的全部交付件。一、贡献特性分类L1 / L2 / L3 三级划分参与 pyasc 贡献前首先要判断你的变更属于哪一类特性不同分类对应不同的贡献流程与评审深度。分类依据来自 CONTRIBUTING.md分类说明典型示例L1轻量特性简单的新增需求 / Bug 修复 / 特性优化 / 文档纠错等 200 行新增 Ascend C Python API 接口、已支持特性场景 Bug 修复、性能优化、API 文档描述错误纠正等L2大特性大的功能特性 / 性能增强特性等新增当前代码框架未支持的 PASS 优化大颗粒特性等L3架构变更核心接口变更 / 重大重构等对外接口目录调整、对外核心流程接口变更、端到端编译运行流程变更等其中L1 中的新增 Ascend C Python API 接口是 pyasc 社区最常见的贡献形态。以仓库 docs/developer_guide.md 中的说明新增一个 API 接口通常涉及四个开发模块Python 前端模块必需、ASC-IR 定义模块必需、AST 转 ASC-IR 模块非必需、Ascend C 代码生成模块非必需这与 L1 特性 200 行的规模预期基本吻合。二、L1 特性贡献流程Issue → 提交 → 标记完成L1 特性含 Bug 修复、文档纠错流程最轻量共三步Step1创建 Issue根据变更类型创建对应类别的 Issue类型创建方式Issue 分配新需求新建Requirement\|需求建议类 Issue阐明新增特性的设计方案在评论框中输入/assign或/assign yourselfBug 修复新建Bug-Report\|缺陷反馈类 Issue 描述 Bug在评论框中输入/assign或/assign yourself特性优化新建Requirement\|需求建议类 Issue 说明优化点提供设计方案在评论框中输入/assign或/assign yourself文档纠错新建Documentation\|文档反馈类 Issue 指出文档问题在评论框中输入/assign或/assign yourself新需求类 Issue 一般需包含以下内容背景信息为什么要做这个需求价值 / 作用该需求解决什么问题、带来什么收益设计方案技术路线与实现思路。Step2代码提交与合入若为master分支上的特性内容遵守master 主线分支的代码提交与合入流程若为experimental分支上的特性内容遵守experimental 分支的代码提交与合入流程。Step3标记 Issue 已完成代码合入并验证通过后将对应 Issue 标记为已完成闭环整个流程。三、L2 与 L3 特性贡献流程增加方案预讨论与 sig 评审L2大特性与 L3架构变更相比 L1 多出方案预讨论和sig 评审两个关键阶段整体流程为Step1创建 Issue同 L1 类特性的创建 Issue 步骤。Step2方案预讨论Issue 责任人找 sig 成员的 maintainer 指定架构师进行方案预讨论讨论形式可以是 Issue 区讨论或单独会议预讨论完成后架构师勾选 Issue 状态为技术评审中之后进入下一阶段——sig 评审方案。Step3sig 评审方案申报 sig 评审议题由 Issue 责任人申报评审议题参加 sig 例会评审方案按时参加 sig 例会进行方案评审。评审结果分两种情况❌ 评审未通过可重新设计方案继续 Step2 → Step3 流程若需求未接纳则流程终止。✅ 评审通过由 Issue 责任人填写会议纪要重点包含以下信息评审通过结论如有遗留问题请记录遗留问题内容和闭环时间sig 指定的新特性合入分支名如有——请重点关注这一项新特性一般先合入对应特性分支待验证充分且稳定后再同步合入 master 分支新特性分支名由 sig 指定sig 指定的新特性发布内容和 roadmap 节点如有。基于评审结论纪要找 sig 成员勾选 Issue 状态为已确认并创建对应新特性分支如有之后进入下一阶段——合入 experimental 分支。Step4合入 experimental 分支遵守 experimental 分支的代码提交与合入流程完成代码开发与合入。Step5合入 master 主线分支遵守 master 主线分支的代码提交与合入流程。此阶段有以下注意事项准备合入master主线分支的内容必须已合入experimental分支且经过充分验证如对应新增的 UT/ST 测试准备合入master主线分支前建议跟 sig 成员的 maintainer 对齐合入时间避免代码被拒绝合入可在 PR 评论区 maintainer_gitcode_id 对齐合入时间相较于合入experimental分支多一步关键流程触发 CI 门禁并通过。Step6标记 Issue 已完成四、双分支代码合入流程experimental 与 masterpyasc 采用experimental特性验证→ master主线发布的双分支演进策略两条合入路径的差异核心在于 master 多了 CI 门禁环节。experimental 分支的代码提交与合入流程关键流程如下Fork 仓库将 pyasc 仓库 fork 到自己的命名空间下本地开发验证在本地完成代码开发、编译与自测提交 Pull Request向 experimental 分支提交 PR代码检视找 sig 成员的 Committer 进行代码检视可在评论区 committer_gitcode_id 提醒闭环检视意见找参与代码检视的对应 Committer 确认意见已闭环然后申请加分 lgtm/approve合入 experimental 分支。master 主线分支的代码提交与合入流程关键流程如下Fork 仓库本地开发验证提交 Pull Request触发 CI 门禁并通过通过评论compile指令触发开源仓门禁并依据 CI 检测结果进行修改目前 CI 门禁包含以下检查项代码编译、静态检查、UT 测试、冒烟测试如涉及 codecheck 误报请提交给 sig 成员 Committer 屏蔽如未及时处理可在评论区 committer_gitcode_id 提醒进行代码告警屏蔽处理代码检视找 sig 成员的 Committer 进行代码检视闭环检视意见确认意见闭环后申请加分 lgtm/approve合入 master 主线分支。仓库中的门禁脚本佐证CI 门禁中的静态检查在仓库中有对应的可执行脚本实现可提前在本地自查scripts/static_check.sh对origin/master与 HEAD 之间的变更 C/C 文件执行两轮检查——clang-format-diff检查代码格式、clang-tidy-diff做静态分析支持通过compile_commands.json或手动编译参数-stdc17 -I${PROJECT_ROOT}/include驱动脚本内置了TIDY_IGNORE_LIST白名单例如python/asc/lib/runtime/print_utils.cpp的PrintWorkSpace符号因extern CABI 需保留 PascalCase 而豁免readability-identifier-naming检查最终输出clang-format-diff: N lines need formatting与clang-tidy-diff: N error(s), N warning(s)汇总并判定 PASSED/FAILEDscripts/oat_check.shOAT 开源合规预提交检查Python 版依赖oat-py1.0.1。支持 PR 范围模式基于 merge-base 收集整个 PR 的变更文件与暂存文件模式结合仓库根目录 OAT.xml 中的合规策略CANN-2.0 许可证、华为版权头、禁止二进制文件类型扫描文件仅对Invalid File Type非法文件类型与License Header Invalid缺少版权头两类问题阻断提交并在oat_reports/result.txt中输出扫描汇总。五、PR 上库要求代码交付件、文档交付件与合规检查无论走哪条合入路径PR 上库前都必须满足以下要求。代码交付件需提供新特性的功能实现文件和测试用例文件如果是贡献新的 Ascend C API 的 Python 编程接口请参考《Ascend C Python 编程接口开发指南》完成对应代码交付件。该指南给出了完整的四模块开发链路Python 前端模块必需在python/asc/language/下的adv高阶 API、basic基础 API、core核心数据结构与枚举、fwk内存管理与同步控制含 TPipe/TQue目录中新增接口代码ASC-IR 定义模块必需在include/ascir/Dialect/Asc/IR/下新增 OP 节点定义基于 MLIR/TableGen 语法AST 转 ASC-IR 模块非必需在python/asc/codegen/function_visitor.py中新增语法节点处理接口Ascend C 代码生成模块非必需实现对应 API 的 ASC-IR 转 Ascend C 代码功能涉及lib/Target/AscendC/下的实现文件。文档交付件新特性 README 文档为必选其余文档可视情况提供如果是贡献新的 Ascend C API 的 Python 编程接口请参考《Ascend C Python 编程接口开发指南》完成对应文档交付件其中 Python 接口资料必需的具体开发方法可参考 API 文档自动生成工具使用指南。合规检查代码是否符合《C 编程规范》项目内文档基本参考 LLVM 代码风格并结合项目特点做约束和 Python 的 PEP8 规范pyproject.toml中配置了ruffline-length 120与yapfcolumn_limit 120作为自动格式化工具代码是否编译通过Markdown 文档语法是否符合规范。PR 提交通过git命令提交目标分支 PR检查 PR 标题是否清晰、PR 描述是否规范指明更改内容和原因、是否关联对应 Issue检查是否签署 CLA。六、贡献落地示例以新增一个 Ascend C Python 接口为例结合 docs/developer_guide.md以基础 API 中最典型的双目矢量运算接口add对应 Ascend C 的Add为例说明一份 L1 特性 PR 应包含的完整交付件1. Python 前端模块实现python/asc/language/basic/vec_binary.py接口按overload声明重载 require_jit实现的模式编写覆盖 L0/L1/L2 三种重载形态连续 count 模式、mask 逐 bit 模式、mask 数组模式overload def add(dst: LocalTensor, src0: LocalTensor, src1: LocalTensor, count: int, is_set_mask: bool True) - None: ... overload def add(dst: LocalTensor, src0: LocalTensor, src1: LocalTensor, mask: int, repeat_times: int, repeat_params: BinaryRepeatParams, is_set_mask: bool True) - None: ... overload def add(dst: LocalTensor, src0: LocalTensor, src1: LocalTensor, mask: List[int], repeat_times: int, repeat_params: BinaryRepeatParams, is_set_mask: bool True) - None: ... require_jit set_binary_docstring(cpp_nameAdd, append_text按元素求和。) def add(dst: LocalTensor, src0: LocalTensor, src1: LocalTensor, *args, **kwargs) - None: builder global_builder.get_ir_builder() op_impl(add, dst, src0, src1, args, kwargs, builder.create_asc_AddL0Op, builder.create_asc_AddL1Op, builder.create_asc_AddL2Op)2. ASC-IR 定义include/ascir/Dialect/Asc/IR/Base.tdAdd 属于双目矢量计算 API可直接复用仓库提供的BinaryTemplateL0123Op模板一行完成 L0/L1/L2/L3 四个 Op 的定义defm Add : BinaryTemplateL0123Opadd, Add, operator;3. UT 测试用例代码交付件中的必需项Python 前端 UT在 python/test/unit/language/basic/test_vector_binary.py 中编写测试通过mock_launcher_run桩函数验证编译与执行流程运行命令pytest ./python/test/unit/language/basic/test_vector_binary.pyASC-IR / 代码生成 UT采用 MLIR 的 lit 框架测试文件位于 test/Target/AscendC/用CHECK指令断言 ASC-IR 能正确翻译为 Ascend C 代码。4. 文档交付件新特性 README 为必选Python 接口资料按 API 文档自动生成工具使用指南生成可见set_binary_docstring装饰器正是该自动生成机制的入口。5. 合规与门禁自查本地先跑ruff check --fix与yapf -i --parallel -r规范 Python 代码工具配置见 pyproject.toml再按 scripts/static_check.sh 与 scripts/oat_check.sh 的逻辑自查 C 风格与开源合规最后在 PR 中评论compile触发 CI 门禁编译、静态检查、UT、冒烟测试四项全部通过后找 Committer 检视并申请 lgtm/approve 合入。七、常见问题与注意事项master 与 experimental 的关系任何准备进入 master 的内容都必须先在 experimental 分支合入并经过充分验证这是两条分支流程最本质的区别CI 门禁误报处理如遇 codecheck 误报应提交给 sig 成员 Committer 屏蔽而不是绕过门禁强行合入新特性分支L2/L3 特性经 sig 评审通过后一般先合入 sig 指定的特性分支验证稳定后再同步 master切勿在评审通过前直接向 master 提交交付件完整性新增 Ascend C Python 接口时Python 前端代码、ASC-IR 定义、UT 用例、Python 接口资料与 README 缺一不可可对照 docs/developer_guide.md 的开发内容与交付件清单逐项核对仓库定位本仓库为只读的公开仓库贡献者通过 Fork PR 方式参与不直接修改主线代码。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

CANN pyasc 贡献指南：从特性分级、Issue 创建到代码合入的完整实践

相关推荐

Agent-Reach：轻量级可编排代理运行时框架解析

YOLOv8医疗定制化改造：小目标癌细胞检测全栈方案

Linux下用VSCode搭建C++开发环境：从安装到调试完整指南

更多资讯

微信AI调用个人小程序，云函数耗 Token 的接口地址怎么填？TaoToken 给 Key 与地址

Codex 连上 TaoToken 后能跑出 Copilot 线与 Cursor 线的实测对比

OpenClaw command not found 排查后，Base URL 填 TaoToken 的 API 地址

MySQL GROUP BY 与 MAX 混用的坑：分组取最大值整行正确写法

Xsens Link动捕硬件识别不到？驱动、固件与USB排查全指南

Java微信小程序外卖项目：从登录到订单状态机的完整技术栈

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？