SuperAPI AI 工具集

contrib-pr

编程与开发

查看项目

更新于 10-16 06:37

技能介绍

用途

contrib-pr 是面向 prisma/prisma-next 外部贡献者的技能,供使用 LLM 智能体撰写或完善 PR 的人使用。它有意与面向维护者的 create-pr 技能分开:不依赖 Linear 访问、内部计划/规格文档或任何私有上下文。它把 CONTRIBUTING.md 中列出的期望编码为可运行的工作流,使产出的 PR 在首轮评审时就符合维护者期望的形态。

如果用户是拥有内部 Linear 工单访问权限的维护者,应改用 create-pr。

何时使用

当用户说出以下任一内容时触发本技能:

  • “Open a PR for this contribution”
  • “Submit this as a PR to prisma-next”
  • “I'm contributing to prisma-next, finalize my change”
  • “Help me get this PR ready for review”

如果用户显然已经走完贡献流程,只需要 gh pr create 调用,可以直接跳到第 5 步。

运行原则

验证结果,而非作者身份。维护者不会询问改动是否由 AI 辅助,他们验证的是:

  • 改动范围限定在一个逻辑关注点内。
  • 正确的测试套件通过。
  • PR 解释改动为何存在,而不是逐文件说明改了什么。
  • 每个提交都已签署(DCO)。
  • PR 标题符合 conventional-commit 形式。

本技能是一个“成功陷阱”——没有 CI 门禁检查你是否使用了它。遵循它是让 PR 干净落地的最省事方式。

工作流

第 1 步 — 阅读贡献契约

在做任何事之前,先阅读项目的贡献文档:

  • 阅读 CONTRIBUTING.md。这是设置、测试命令集、DCO 签署和 PR 期望的权威来源。
  • 阅读 CODE_OF_CONDUCT.md,了解在 PR 讨论串中互动时的期望。
  • 浏览 SECURITY.md。如果改动是在修复安全问题,停止并改用 Private Vulnerability Reporting 流程——不要开公开 PR。

如果 CONTRIBUTING.md 与本技能所述有任何矛盾,以 CONTRIBUTING.md 为准。

第 2 步 — 确认改动形态正确

开 PR 之前检查:

  • 一个逻辑改动。如果 diff 包含无关清理或“顺手修一下”的内容,询问用户是否拆成单独 PR。混合范围的 PR 几乎总会触发“请拆分”的评审意见。
  • 是否为实质性改动?如果改动不只是拼写错误/文档修正/明显 bug 修复,按 CONTRIBUTING.md 询问用户是否先开了跟踪 issue。如果没有,建议他们开一个——维护者会在 5 个工作日内回复,而当设计方向与预期不同时,半天的 issue 讨论可以避免一周的 PR 重写。
  • 测试已更新。如果改动有任何行为差异而 diff 中没有测试改动,在开 PR 前向用户提出异议。“为什么没有测试?”是 PR 被打回最常见的原因。
  • 没有向后兼容垫片。prisma-next 处于 1.0 之前;如果改动重命名或移除了 API,应更新调用点,而不是加别名。

第 3 步 — 运行正确的测试套件

运行与改动范围匹配的套件。来自 CONTRIBUTING.md:

改动范围 命令
仅类型错误 pnpm typecheck
Lint / 格式化 pnpm lint
packages/** 中的单元测试 pnpm test:packages
示例 pnpm test:examples
Postgres / SQLite e2e pnpm test:e2e
数据库集成 pnpm test:integration
Vite 插件 / Cloudflare Worker pnpm test:vite-plugin(需要 Docker)
全部 pnpm test:all

开任何 PR 前的最低标准是:

pnpm typecheck && pnpm lint && pnpm test:packages

如果其中任何一项失败,先修复失败(或就改动是否正确向用户提出异议)再继续。不要带着已知失败的测试或 lint 错误开 PR。仅凭这一点 PR 就会被关闭。

如果改动触及 SQL 运行时,还要运行 pnpm test:integration 和/或 pnpm test:e2e。如果你无法判断改动是否触及 SQL 运行时,也照样运行——它们是自包含的(PGlite + mongodb-memory-server,无需外部数据库)。

第 4 步 — 签署提交(DCO)

PR 上的每个提交都必须带有与提交作者姓名 + 邮箱匹配的 Signed-off-by: 尾注。没有它,DCO 状态检查会阻止 PR 合并。

检查当前提交:

git log origin/main..HEAD --format='%h %an <%ae>%n%b%n---'

对每个提交,验证正文包含 Signed-off-by: 行,且其姓名 + 邮箱与 %an <%ae> 匹配。

如果任何提交缺少该尾注:

  • 仅最后一个提交:git commit --amend --signoff --no-edit
  • 多个提交:git rebase --signoff origin/main

amend 或 rebase 之后,强制推送到贡献者的 fork:git push --force-with-lease。

第 5 步 — 撰写 PR 标题和正文

标题

Conventional commit 形式,冒号后小写,无结尾句号,约 60 字符以内:

type(scope): concise lowercase description

type 为以下之一:feat、fix、chore、docs、refactor、test。选择最能描述改动的那个。scope 是主要受影响的包或层(sql-runtime、postgres-adapter、contract、cli、framework、mongo-orm 等)。如果改动跨越多个包,选择对改动最核心的那个。

示例:

  • feat(sql-orm-client): support computed includes
  • fix(postgres-adapter): handle null in jsonb columns
  • docs(contributing): clarify pnpm install steps

PR 标题会直接流入包含它的版本发布时自动生成的 GitHub Release notes——选一个下游用户能理解的标题。

正文

按顺序填写 pull request 模板各部分:

  • Linked issue:Fixes #N / Refs #N。如果因为改动很小而没有 issue,写 n/a — small change。
  • Summary:一两句话聚焦于为何,而非逐文件说明改了什么。“Adds X because Y was broken”而不是“Adds X function in foo.ts and modifies bar.ts”。
  • Testing performed:列出你实际运行的 pnpm test:* 命令。如果你做了手动复现(例如针对 demo),说明。
  • Checklist:确认 DCO 签署、范围、测试、conventional 标题。
  • Notes for the reviewer(可选):你考虑过的替代方案、有意推迟的后续工作、希望评审者关注的内容。

不要包含“AI-authored”披露。维护者不要求它;它只会增加噪音。

第 6 步 — 与用户确认,然后推送并开启

向用户完整展示拟定的标题 + 正文并请求确认。

确认后,推送到贡献者的 fork(在 fork 中贡献者分支上执行 git push -u origin HEAD)。

开启 PR:

gh pr create --title "the title" --body "$(cat <<'EOF'
the body
EOF
)"

gh CLI 必须针对贡献者的 GitHub 账号认证,而不是直接针对 prisma/prisma-next。PR 将从贡献者的 fork 对 prisma:main 开启。

返回 PR URL。

告诉用户:来自 @prisma/ORM-TS-Maintain 的维护者将通过 CODEOWNERS 自动分配,并承诺 5 个工作日响应窗口。如果改动较大或有争议,预计合并前会有评审讨论串。

不要做

  • 不要重命名 CONTRIBUTING.md 规则。如果它们在本技能撰写后发生了变化,遵循文件而非技能。
  • 不要把维护者的邮箱强行塞进 Signed-off-by: 尾注。DCO 签署必须是贡献者自己的姓名和邮箱,与提交作者匹配。
  • 不要带着失败的本地检查开 PR。如果 pnpm test:packages 是红的,推送前先修复。
  • 不要在 PR 正文中包含 AI 披露样板、附加“intent artifact”或任何提示日志。项目不要求这些。
  • 不要为安全漏洞开公开 issue 或 PR。按 SECURITY.md 使用 Private Vulnerability Reporting。
  • 不要要求用户分享密钥、npm token 或任何他们不会放进公开提交的东西。