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

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

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto

在 CANN / PyPTO（Parallel Tensor/Tile Operation 编程范式）开源仓库中，向cann/pypto提交高质量的 Pull Request（PR）需要经过 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 提交拆解为七个维度：

1. 环境预检— 确认本地仓库、remote 与 fork 链关系；
2. Git 认证— 确保 push 凭据可用；
3. 代码准备— 同步 upstream、补充测试、修复 code-check 告警；
4. Commit 规范— 校验 message 格式；
5. PR 规范— 校验标题、Body 与关联 Issue；
6. Cross-Fork 参数— 校验 MCP 创建 PR 时的参数格式；
7. 用户确认— 提交前向用户展示完整执行计划并获取明确确认。

配套的参考文件同样位于.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.git

• upstream remote 已添加：若不存在，执行：

  git remote add upstream https://gitcode.com/cann/pypto.git

• fork 链关系已验证：通过 GitCode MCP 调用gitcode_get_repository(owner="<username>", repo="pypto")，确认返回结果中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/CD
libsecret	系统加密	持久	Linux 桌面

容器环境推荐 7 天超时的缓存 helper：

git config --global credential.helper 'cache --timeout=604800' # 首次 push 输入用户名和 Token，后续自动使用缓存

最终验证以git push --dry-run origin <branch>通过为准。一个易踩的坑是 GitCode不支持 Bearer token 认证，只支持 HTTP Basic Auth（详见 troubleshooting.md），可用GIT_CURL_VERBOSE=1 git push origin <branch> 2>&1 | grep -i authorization确认请求头是Authorization: Basic <base64>而非Bearer。认证配置成功前禁止执行任何 push 操作。

四、代码准备：同步 upstream、测试用例与 code-check

4.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/tests（C++ UT/ST）与 python/tests（Python 用例）两套体系下，例如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 中"代码功能逻辑紧密关联的函数/目录，拆分后影响可维护性"；规则 25（G.FNM.03）允许@pypto.frontend.jit修饰的大融合算子入口保留平铺参数；规则 26（G.LOG.03）允许 Example 脚本使用print直接向用户展示结果。
• 误报：例如规则 7（G.CMT.05-CPP）——PyPTO 是开源代码仓而非正式交付客户代码，允许保留 TODO/TBD 注释；规则 24 中"当前类内部或 Package 内部变量"被视为明显误报。

此外，多条规则的屏蔽范围被限定为examples/tests相关代码（如规则 21、22、27~31），因为这些测试代码需要覆盖原生 Python 向 PIL（PyPTO Intermediate Language）翻译的各种边界行为（lambda 赋值、dict[key] 取值、复杂推导式、未指定异常类型抛出、捕获后直接重抛等），以验证翻译结果符合预期。新增屏蔽规则或修改规则文件本身，需要 maintainer 评审通过后才可合入。

五、Commit 规范：tag(scope): Summary的严格约束

清单对每个 commit 的要求，与官方规范 docs/zh/contribute/pull-request.md 完全对齐：

tag(scope): Summary

Tag 合法类型（pr-spec.md 明确chore不在允许列表）：

Tag	用途
feat	新功能
fix	Bug 修复
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 type	Added support for FP16	过去时态
Fix memory leak in graph optimization	Fixes memory leak in optimizer.	祈使句尾不加句号
Update tensor creation API documentation	updated API documentation	未首字母大写
feat(skills): Add PR creator skill	feat(skills): 为 PyPTO 项目添加 PR 创建技能	必须使用英文
fix(ops): Fix precision issue in softmax	feat: add feature	缺少 scope

整体要求：每个 commit 只做一件事；整个 commit message 不超过 10 行；多 commit 场景推荐提交顺序为fixup→refactor→feat→test。PyPTO 采用 squash merge，因此不要求冗长的 commit message 正文，但 PR Body 中应包含每个 commit 的简短摘要。

六、PR 规范：标题、Body 与关联 Issue

6.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.md）：

feat(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,#5678

6.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.md）：

  head="feat/add-pr-guide" # 错误：缺少 fork owner head="<username>/feat/add-pr-guide" # 错误：用了 / 而非 : head="<username>:feat/add-pr-guide" # 正确

• MCP 参数名全小写，例如owner、repo、pull_number、title、body。
• owner/repo指向上游仓库cann/pypto，而不是用户 fork：

gitcode_create_pull_request( owner="cann", repo="pypto", title="tag(scope): Summary", head="<username>:<branch_name>", base="master", body="..." )

创建前应先判断是"创建"还是"更新"：调用gitcode_list_pull_requests(owner="cann", repo="pypto")筛选state == "opened"且source_branch匹配当前分支的 PR，存在则询问用户更新现有 PR 或新建。更新时使用：

gitcode_update_pull_request( owner="cann", repo="pypto", pull_number=<pr_number>, title="新标题", body="新描述" )

MCP 返回 400 时，错误信息可能被吞掉，可用 curl 直接请求https://api.gitcode.com/api/v5/repos/cann/pypto/pulls获取详细错误（见 troubleshooting.md 中的完整脚本）。

八、用户确认：执行前必须展示计划表

清单最后一条是流程的硬性约束：在获得用户明确确认之前，禁止执行任何 git 操作（包括创建分支、commit、push、创建/更新 PR）。确认环节需向用户展示完整的执行计划表，通常包含：

确认项	内容
本地仓库路径	$PYPTO_REPO
Fork 仓库	<username>/pypto
分支名	<branch_name>
Commit 信息	tag(scope): Summary
Push 目标	origin →<branch_name>
PR 目标	cann/pypto→master
PR 标题与 Body	预览内容

这条约束同样被写入pypto-pr-creator技能的"强制约束"段落，配合"禁止打印GITCODE_TOKEN（包括屏幕、日志、调试信息）""远程操作必须通过 GitCode MCP 完成"等规则，确保整个提交流程可审计、可回退。

九、PR 创建后的收尾检查

PR 创建成功后，清单之外还有两项关键收尾（来自pypto-pr-creator技能阶段 6）：

1. PR 链接验证：确认链接指向https://gitcode.com/cann/pypto/merge_requests/<pr_id>，而不是<username>/pypto/...。如果 PR 被创建到了自己的 fork 下，说明owner/repo参数传错了。
2. CLA 检查：通过gitcode_get_pull_request读取 PR labels，若含cla/no则 CLA 未通过。修复路径包括：核对 commit 作者邮箱与 GitCode 账户主邮箱一致（git log -1 --format='Author: %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 秒的最终自检：

#	检查项	通过标准
1	origin 指向	指向<username>/pypto，非cann/pypto
2	upstream	git fetch upstream master后HEAD..upstream/master为空
3	认证	git push --dry-run origin <branch>通过
4	Commit 格式	tag(scope): Summary，tag 合法、英文、首字母大写、无句号、10–200 字符、≤10 行
5	单一职责	每个 commit 只做一件事，PR 无无关变更
6	测试与 code-check	feat/fix 配套测试；告警已修复或按规则屏蔽
7	PR 参数	head="<username>:<branch>"、参数全小写、owner/repo = cann/pypto
8	用户确认	已展示完整执行计划表并获明确确认
9	收尾	PR 链接指向cann/pypto/merge_requests/<pr_id>，CLA 通过

只要以上各项全部勾选，你的 PR 就能顺利通过 pre-receive hook、code-check 与 CLA 三道关卡，进入approve+lgtm的合入流程。

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto