CANN PyPTO 贡献指南：从 fork 到合入的 PR 提交前检查清单实战

CANN PyPTO 贡献指南从 fork 到合入的 PR 提交前检查清单实战【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto在 CANN / PyPTOParallel Tensor/Tile Operation 编程范式开源仓库中向cann/pypto提交高质量的 Pull RequestPR需要经过 fork 验证、Git 认证、upstream 同步、Commit 规范、PR 规范、Cross-Fork 参数与用户确认等多道关卡。本文以仓库内pypto-pr-creator技能所维护的提交前检查清单为核心骨架结合仓库官方贡献文档CONTRIBUTION.md、docs/zh/contribute/pull-request.md与 docs/zh/contribute/code-check-rule.yaml 告警屏蔽规则逐项讲解每条检查项背后的工程含义与可执行命令帮助你一次通过 pre-receive hook、code-check 与 CLA 检查将改动干净利落地合入上游主仓库。一、检查清单的定位何时加载、覆盖什么本清单文件位于 .agents/skills/pypto-pr-creator/references/checklist.md是pypto-pr-creator技能在**阶段 4预检与阶段 6创建 PR 后检查**前必须加载并逐项勾选的核对表。它把一次 PR 提交拆解为七个维度环境预检— 确认本地仓库、remote 与 fork 链关系Git 认证— 确保 push 凭据可用代码准备— 同步 upstream、补充测试、修复 code-check 告警Commit 规范— 校验 message 格式PR 规范— 校验标题、Body 与关联 IssueCross-Fork 参数— 校验 MCP 创建 PR 时的参数格式用户确认— 提交前向用户展示完整执行计划并获取明确确认。配套的参考文件同样位于.agents/skills/pypto-pr-creator/references/目录下pr-spec.md 提供 PR/Commit 格式规范、git-auth.md 提供认证方式配置、troubleshooting.md 提供 push/PR 失败诊断。而仓库官方的 PR 提交规范则以 docs/zh/contribute/pull-request.md 为权威来源本清单中的格式要求与其保持一致。二、环境预检本地仓库、origin 与 fork 链清单第一阶段要求确认四件事本地仓库路径正确执行git rev-parse --is-inside-work-tree确认当前目录位于 pypto 仓库内。origin 指向用户 fork而非cann/pypto这是最容易出错的一步。origin必须指向username/pypto若误指向cann/pypto需要修复git remote set-url origin https://gitcode.com/username/pypto.gitupstream remote 已添加若不存在执行git remote add upstream https://gitcode.com/cann/pypto.gitfork 链关系已验证通过 GitCode MCP 调用gitcode_get_repository(ownerusername, repopypto)确认返回结果中parent.full_name cann/pypto。这一步保证你提交的 PR 确实来自cann/pypto的 fork而非其他无关仓库的副本。浅克隆已修复如需要先执行git rev-parse --is-shallow-repository检测是否浅克隆。若是执行git fetch --unshallow origin拉全历史否则后续 rebase 与 push 会报 shallow update not allowed。从底层看GitCode 平台对 PR 的 pre-receive hook 会同时校验提交来源链与 commit 格式fork 链不正确或浅克隆未修复都会在推送阶段被拦截因此这一阶段是后续所有操作的物理前提。三、Git 认证push 前的凭据准备git push依赖认证清单要求在 push 之前完成认证配置并验证。快速检测命令echo GITCODE_TOKEN: $([ -n $GITCODE_TOKEN ] echo 已设置 || echo 未设置) echo credential.helper: $(git config --global credential.helper 2/dev/null || echo 未配置)认证方式可参考 git-auth.md按适用场景选择方式安全性持久性推荐场景cache推荐内存存储临时可设超时容器/临时环境store明文持久个人开发机SSH Key加密持久长期开发GITCODE_TOKEN URL环境变量临时CI/CDlibsecret系统加密持久Linux 桌面容器环境推荐 7 天超时的缓存 helpergit config --global credential.helper cache --timeout604800 # 首次 push 输入用户名和 Token后续自动使用缓存最终验证以git push --dry-run origin branch通过为准。一个易踩的坑是 GitCode不支持 Bearer token 认证只支持 HTTP Basic Auth详见 troubleshooting.md可用GIT_CURL_VERBOSE1 git push origin branch 21 | grep -i authorization确认请求头是Authorization: Basic base64而非Bearer。认证配置成功前禁止执行任何 push 操作。四、代码准备同步 upstream、测试用例与 code-check4.1 与 upstream 保持同步git fetch upstream master git log --oneline HEAD..upstream/master第二行输出必须为空否则说明分支已落后于 upstream需要 rebase 后再推git fetch upstream master git rebase FETCH_HEAD仓库官方指南 docs/zh/contribute/pull-request.md 同样强调Rebase your branch to most recent version ofmasterbranch落后分支会触发远端pre-receive hook check failed。4.2 测试用例清单要求 feat/fix 类型变更必须配套添加测试用例。这与官方指南 Add test cases for feat or fix done in the pull request 一致。PyPTO 仓库的测试分布在 framework/testsC UT/ST与 python/testsPython 用例两套体系下例如python/tests/st/operation/下每个算子目录都包含对应的.py用例文件。新增接口或修复 Bug 时应在对应层级补充覆盖新行为的用例。4.3 code-check 告警修复与屏蔽规则清单要求修复 code-check 警告参考规则文件为 docs/zh/contribute/code-check-rule.yaml。该 YAML 定义了仓库允许的告警屏蔽规则每条规则包含屏蔽规则编号、语言C/Python、告警来源如超大函数[C]超大圈复杂度[Python]G.FMT.02等、屏蔽选项规范例外的场景 / 误报与屏蔽理由。实际屏蔽时需注意两类语义规范例外的场景例如规则 1、13 中代码功能逻辑紧密关联的函数/目录拆分后影响可维护性规则 25G.FNM.03允许pypto.frontend.jit修饰的大融合算子入口保留平铺参数规则 26G.LOG.03允许 Example 脚本使用print直接向用户展示结果。误报例如规则 7G.CMT.05-CPP——PyPTO 是开源代码仓而非正式交付客户代码允许保留 TODO/TBD 注释规则 24 中当前类内部或 Package 内部变量被视为明显误报。此外多条规则的屏蔽范围被限定为examples/tests相关代码如规则 21、22、27~31因为这些测试代码需要覆盖原生 Python 向 PILPyPTO Intermediate Language翻译的各种边界行为lambda 赋值、dict[key] 取值、复杂推导式、未指定异常类型抛出、捕获后直接重抛等以验证翻译结果符合预期。新增屏蔽规则或修改规则文件本身需要 maintainer 评审通过后才可合入。五、Commit 规范tag(scope): Summary的严格约束清单对每个 commit 的要求与官方规范 docs/zh/contribute/pull-request.md 完全对齐tag(scope): SummaryTag 合法类型pr-spec.md 明确chore不在允许列表Tag用途feat新功能fixBug 修复docs文档变更style代码格式refactor重构test测试相关perf性能优化Scope 规则填写受影响的模块/组件名多模块用|分隔如feat(frontend|backend): ...涉及模块过多时用all如refactor(all): ...。Summary 规则英文编写、首字母大写、不加句号、祈使语气、长度 10–200 字符。可用如下正则自检与阶段 4 预检命令一致git log -1 --format%s | grep -E ^(feat|fix|docs|style|refactor|perf|test)(.*): [A-Z].{10,200}正误对比来自 pr-spec.md✅ 正确❌ 错误原因Add support for FP16 data typeAdded support for FP16过去时态Fix memory leak in graph optimizationFixes memory leak in optimizer.祈使句尾不加句号Update tensor creation API documentationupdated API documentation未首字母大写feat(skills): Add PR creator skillfeat(skills): 为 PyPTO 项目添加 PR 创建技能必须使用英文fix(ops): Fix precision issue in softmaxfeat: add feature缺少 scope整体要求每个 commit 只做一件事整个 commit message 不超过 10 行多 commit 场景推荐提交顺序为fixup→refactor→feat→test。PyPTO 采用 squash merge因此不要求冗长的 commit message 正文但 PR Body 中应包含每个 commit 的简短摘要。六、PR 规范标题、Body 与关联 Issue6.1 PR 标题与 commit message 同格式tag(scope): Summary同样是英文、首字母大写、无句号、祈使语气。6.2 PR Body禁止为空必须清晰传达变更意图动机、背景、上下文让 reviewer 理解 why移除无关模板内容与占位符关联 Issue 放在最后一行格式Related Issues: #xxx多 commit 场景需在 Body 中列出每个 commit 摘要。官方文档给出了完整的 PR Body 示例见 docs/zh/contribute/pull-request.mdfeat(interface): Optimize the pypto.cond with concrete value The origin implementation of pypto.cond generate both if/else branch, even if the condition is always true or false, in this PR, we optimize the implementation to generate only one branch. Changes: - Optimize the pypto.cond with concrete value, which can reduce the number of branches in the program - Update the test cases to cover the new features Related Issues: #1234,#56786.3 单一职责清单要求单一职责 — 无不相关变更混入。官方指南亦强调 Send well scoped pull request that are easy to review and revert, merge multiple unrelated changes should be avoided。此外仓库 CONTRIBUTION.md 提醒若修改不是简单 Bug 修复而是新增特性、接口、配置参数或修改代码流程务必先通过 Issue 进行方案讨论避免代码被拒绝合入。仓库提供了 PR 模板文件.gitcode/PULL_REQUEST_TEMPLATE.md中文与 .gitcode/PULL_REQUEST_TEMPLATE_en.md英文提交时按模板填写业务背景、目的、方案等信息。七、Cross-Fork 参数MCP 创建 PR 的格式陷阱清单指出创建 PR 时通常通过 GitCode MCP 工具完成三个参数最容易出错head使用username:branch_name格式冒号分隔。错误示例与正确示例对比来自 troubleshooting.mdheadfeat/add-pr-guide # 错误缺少 fork owner headusername/feat/add-pr-guide # 错误用了 / 而非 : headusername:feat/add-pr-guide # 正确MCP 参数名全小写例如owner、repo、pull_number、title、body。owner/repo指向上游仓库cann/pypto而不是用户 forkgitcode_create_pull_request( ownercann, repopypto, titletag(scope): Summary, headusername:branch_name, basemaster, body... )创建前应先判断是创建还是更新调用gitcode_list_pull_requests(ownercann, repopypto)筛选state opened且source_branch匹配当前分支的 PR存在则询问用户更新现有 PR 或新建。更新时使用gitcode_update_pull_request( ownercann, repopypto, pull_numberpr_number, title新标题, body新描述 )MCP 返回 400 时错误信息可能被吞掉可用 curl 直接请求https://api.gitcode.com/api/v5/repos/cann/pypto/pulls获取详细错误见 troubleshooting.md 中的完整脚本。八、用户确认执行前必须展示计划表清单最后一条是流程的硬性约束在获得用户明确确认之前禁止执行任何 git 操作包括创建分支、commit、push、创建/更新 PR。确认环节需向用户展示完整的执行计划表通常包含确认项内容本地仓库路径$PYPTO_REPOFork 仓库username/pypto分支名branch_nameCommit 信息tag(scope): SummaryPush 目标origin →branch_namePR 目标cann/pypto→masterPR 标题与 Body预览内容这条约束同样被写入pypto-pr-creator技能的强制约束段落配合禁止打印GITCODE_TOKEN包括屏幕、日志、调试信息远程操作必须通过 GitCode MCP 完成等规则确保整个提交流程可审计、可回退。九、PR 创建后的收尾检查PR 创建成功后清单之外还有两项关键收尾来自pypto-pr-creator技能阶段 6PR 链接验证确认链接指向https://gitcode.com/cann/pypto/merge_requests/pr_id而不是username/pypto/...。如果 PR 被创建到了自己的 fork 下说明owner/repo参数传错了。CLA 检查通过gitcode_get_pull_request读取 PR labels若含cla/no则 CLA 未通过。修复路径包括核对 commit 作者邮箱与 GitCode 账户主邮箱一致git log -1 --formatAuthor: %an %ae、使用git commit --amend --author...修正作者后 force push或补充一个空 commit 重新触发 CLA 检查git commit --allow-empty -m docs: trigger CLA check git push origin branch_name仓库的 CI 合入门槛见 docs/zh/contribute/pull-request.md为在 PR 评论区发送compile触发 CI 编译编译通过且获得 committer 的approve标签与其他 contributor 的lgtm标签后方可合入code-check告警需在合入前修复或按 docs/zh/contribute/code-check-rule.yaml 中定义的规则屏蔽。另外仓库使用 pre-commit 在本地提交前执行代码风格检查C 用 clang-format v18、Python 用 ruff v0.14 的 E/W/F/I/N 规则族、行宽 120 字符、codespell 拼写检查安装方式为pip install pre-commit pre-commit install详见 CONTRIBUTION.md。十、快速自查速查表将清单浓缩为 push 前 30 秒的最终自检#检查项通过标准1origin 指向指向username/pypto非cann/pypto2upstreamgit fetch upstream master后HEAD..upstream/master为空3认证git push --dry-run origin branch通过4Commit 格式tag(scope): Summarytag 合法、英文、首字母大写、无句号、10–200 字符、≤10 行5单一职责每个 commit 只做一件事PR 无无关变更6测试与 code-checkfeat/fix 配套测试告警已修复或按规则屏蔽7PR 参数headusername:branch、参数全小写、owner/repo cann/pypto8用户确认已展示完整执行计划表并获明确确认9收尾PR 链接指向cann/pypto/merge_requests/pr_idCLA 通过只要以上各项全部勾选你的 PR 就能顺利通过 pre-receive hook、code-check 与 CLA 三道关卡进入approvelgtm的合入流程。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考