antfu-create-pr
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCreate Pull Request
创建 Pull Request
Open a PR that a reviewer can understand from the body alone. Explain the changed behavior and why, not the list of changed files. Keep the body proportional to the change: a one-line fix gets a few sentences, a cross-module feature gets tables and diagrams.
创建一个仅凭正文就能让审查者理解的 PR。说明变更后的行为及其原因,而不是罗列发生变更的文件。正文长度应与变更规模相称:单行修复只需几句话,跨模块功能则可使用表格和图示。
Workflow
工作流
- Inspect the repo: , current branch, remotes, default branch,
git status, and.github/PULL_REQUEST_TEMPLATE*/AGENTS.mdfor PR rules.CONTRIBUTING.md - Compute the merge base against the target branch and record the exact range the PR publishes. If the branch is stacked on another unmerged branch, target that branch and describe only this PR's own changes.
base...head - Read the full diff. Separate runtime code from generated files, lockfiles, and snapshots. Trace changed code to its entry points, callers, and external boundaries so architecture claims are backed by file paths or symbols.
- Classify the PR (feature, fix, refactor, chore, docs) and decide which optional body sections earn their place. See pr-body.
- Run the checks that match the changed surfaces (focused tests, typecheck, lint). Record the exact commands and results.
- If the diff changes user-visible UI, capture before/after evidence. See visual-evidence.
- Write the body to a temporary file. Push the branch. Create the PR with (add
gh pr create --title ... --body-file ...for each screenshot). Use--attachwhen checks are still running or the work is not review-ready.--draft - Open the created PR and verify title, base, head, rendered tables, diagrams, and images.
- Address review comments: fix each confirmed issue, run focused checks, push, reply with evidence, and resolve the thread.
- 检查仓库:、当前分支、远程仓库、默认分支、
git status,以及.github/PULL_REQUEST_TEMPLATE*/AGENTS.md中的 PR 规则。CONTRIBUTING.md - 基于目标分支计算 merge base,并记录 PR 将发布的准确 范围。如果当前分支基于另一个尚未合并的分支,则以该分支为目标,并且只描述当前 PR 自身的变更。
base...head - 阅读完整 diff。将运行时代码与生成文件、lockfile 和 snapshot 分离。追踪变更代码的入口点、调用方和外部边界,确保架构方面的结论有文件路径或符号作为依据。
- 对 PR 进行分类(feature、fix、refactor、chore、docs),并判断哪些可选正文章节确有必要。参见 pr-body。
- 根据变更涉及的层面运行相应检查(聚焦测试、typecheck、lint)。记录执行过的准确命令及其结果。
- 如果 diff 涉及用户可见的 UI 变更,请收集变更前后的证据。参见 visual-evidence。
- 将正文写入临时文件。推送分支,并使用 创建 PR(每张截图都添加
gh pr create --title ... --body-file ...)。当检查仍在运行或工作尚未达到可审查状态时,使用--attach。--draft - 打开创建的 PR,检查标题、base、head、渲染后的表格、图示和图片。
- 处理审查意见:修复每个已确认的问题,运行聚焦检查,推送变更,附上证据进行回复,并解决对应的会话线程。
Title
标题
Use Conventional Commits, matching how the repo already writes commit messages:
text
feat(scope): add retry to upload client
fix(scope): avoid double submit on enter
refactor: extract diff parsing from cli
chore(deps): update vite to v8
docs: clarify worktree setup- Lowercase, imperative, no trailing period, under ~70 characters.
- Scope is the package, module, or feature name the repo already uses. Omit it when the change is repo-wide.
- Squash-merge repos turn the title into the commit message; write it as the commit you want in history.
使用 Conventional Commits,并遵循仓库现有的提交信息风格:
text
feat(scope): add retry to upload client
fix(scope): avoid double submit on enter
refactor: extract diff parsing from cli
chore(deps): update vite to v8
docs: clarify worktree setup- 全部使用小写字母,采用祈使语气,末尾不加句号,长度控制在约 70 个字符以内。
- Scope 使用仓库已有的包、模块或功能名称。对于全仓库范围的变更,可以省略。
- 在采用 Squash Merge 的仓库中,标题会变成提交信息;应按照你希望在历史记录中保留的提交来编写。
Body
正文
Required in every PR:
- : the problem or capability first, then what changed and why this approach. Mention if the PR is stacked and on what.
## Summary - Linked issues: /
closes #123/fixes #123so GitHub links and auto-closes.refs #123 - : exact commands run and their results, plus anything left unverified.
## Verification
Optional, only when it helps the reviewer:
- : table of module, before, after, reason. Use for changes across several modules or ownership boundaries. Never a raw file list.
## Change map - : a Mermaid flow, sequence, or state diagram when ordering, async work, or state transitions changed. For a fix, pair a
## Architecture and behaviorandBeforediagram at the same abstraction level.After - : table of invariant, failure mode, protection, evidence. Use when there are real failure modes, migrations, or external effects.
## Boundaries and risks - : before/after image table for UI changes.
## Visual changes - : migrations, feature flags, known gaps. State whether a gap blocks merge.
## Rollout and follow-up
If the repo has a PR template, keep its headings and fill them; add sections above only where the template leaves room.
每个 PR 都必须包含:
- :先说明问题或新增能力,然后说明变更内容以及为何采用此方案。如果 PR 基于其他分支,请注明具体基于哪个分支。
## 摘要 - 关联 issue:/
closes #123/fixes #123,以便 GitHub 自动建立链接并关闭 issue。refs #123 - :执行过的准确命令及其结果,以及尚未验证的内容。
## 验证
仅在有助于审查者时添加以下可选内容:
- :使用表格展示模块、变更前状态、变更后状态和变更原因。适用于涉及多个模块或所有权边界的变更。不要直接罗列文件。
## 变更映射 - :当执行顺序、异步工作或状态转换发生变化时,使用 Mermaid 流程图、时序图或状态图。对于修复,应在相同抽象层级上成对提供变更前和变更后的图示。
## 架构与行为 - :使用表格展示不变量、故障模式、防护措施和证据。适用于存在实际故障模式、数据迁移或外部影响的情况。
## 边界与风险 - :对于 UI 变更,使用变更前后的图片对照表。
## 视觉变更 - :记录数据迁移、feature flag、已知缺口。明确说明是否有缺口会阻止合并。
## 发布与后续事项
如果仓库提供了 PR 模板,请保留模板中的标题并填写相应内容;仅在模板留有空间时添加上述章节。
Rules
规则
- Say what is verified, what is assumed, and what is not verified. Do not write "safe", "fixed", or "backward compatible" without pointing at the evidence.
- Green CI proves only the checks CI runs. Focused tests prove only the behavior they cover.
- Do not describe inherited changes from a parent branch as this PR's changes.
- Use plain hyphens; never em dashes (U+2014) or en dashes (U+2013).
- No filler ("This PR aims to...", "comprehensive", "robust"). Start sentences with the fact.
- Do not paste tokens, secrets, user records, or full payloads into the body.
- Do not commit screenshots or other PR-only artifacts to the repo; attach them with .
gh --attach - If the PR was written with the help of an agent, say so in one line at the end of the body.
- 明确说明哪些内容已经验证、基于哪些假设,以及哪些内容尚未验证。不要在没有证据指向的情况下写“safe”、“fixed”或“backward compatible”。
- CI 通过只能证明 CI 中实际运行的检查通过了。聚焦测试只能证明其覆盖的行为。
- 不要把从父分支继承的变更描述为当前 PR 的变更。
- 使用普通连字符;绝不使用 em dash(U+2014)或 en dash(U+2013)。
- 不要使用填充性表述(“This PR aims to...”、“comprehensive”、“robust”)。每句话都应直接陈述事实。
- 不要在正文中粘贴 token、secret、用户记录或完整的 payload。
- 不要将截图或其他仅供 PR 使用的素材提交到仓库;应使用 附加它们。
gh --attach - 如果 PR 是在 Agent 的帮助下撰写的,请在正文末尾用一行说明。