用途
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 或任何他们不会放进公开提交的东西。