create-pull-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Pull Request

创建 Pull Request

main

is protected — the trunk. Work reaches it through a pull request.

main

是受保护的——主干分支。工作内容通过 Pull Request 汇入该分支。

Source of truth

权威依据

Branch types, naming, and how PRs land live in references/branch-naming-conventions.md. Read it before proposing a name or opening a PR. If the project ships

.agents/rules/branch-naming-conventions.md

(or the Cursor adapter

.cursor/rules/branch-naming-conventions.mdc

), that file overrides these defaults.

分支类型、命名方式以及 PR 的合入方式由 references/branch-naming-conventions.md 规定。在建议名称或创建 PR 前，请先阅读该文件。如果项目提供了

.agents/rules/branch-naming-conventions.md

（或 Cursor 适配器

.cursor/rules/branch-naming-conventions.mdc

），该文件将覆盖这些默认规则。

Workflow

工作流程

Step 1: Read the current state

第 1 步：读取当前状态

Run

git branch --show-current

git status --short

, and — when the branch tracks a remote —

git log origin/$(git branch --show-current)..HEAD --oneline

. Confirm

gh

is installed and authenticated.

Route on what you find:

Protected (
```
main
```
) with local commits → Step 2 (transplant).
Protected (
```
main
```
) with no local commits → nothing to open a PR from; stop.
Named branch → Step 3.

Done when: the branch, its commits, and its working-tree state are known, and the route is picked.

运行

git branch --show-current

、

git status --short

，并且当当前分支跟踪远程分支时，运行

git log origin/$(git branch --show-current)..HEAD --oneline

。确认

gh

已安装且已完成身份验证。

根据发现的情况进行分流：

受保护的
```
main
```
且存在本地提交 → 第 2 步（迁移提交）。
受保护的
```
main
```
且没有本地提交 → 没有可据以创建 PR 的提交；停止。
已命名的分支 → 第 3 步。

完成条件： 已了解当前分支、提交和工作树状态，并已选择处理路径。

Step 2: Transplant commits off the protected branch

第 2 步：将提交从受保护分支迁移出去

Move the commits to a properly named branch and leave

main

clean:

Show the commits that will move.
Ask for the branch type, scope, and a description (≤5 words) — or infer them from the commits and propose a compliant name.
Confirm the proposed name, then
```
git checkout -b <branch-name>
```
.
Confirm the reset explicitly — it discards those commits from local
```
main
```
— then
```
git checkout main
```
and
```
git reset --hard origin/main
```
.
Return to the new branch.

Done when: the commits live on the new branch,

main

matches its remote, and both moves were confirmed beforehand.

将提交移动到命名规范的新分支，并让

main

保持干净：

显示将要移动的提交。
询问分支类型、作用域和描述（不超过 5 个词）——也可以从提交中推断这些信息，并提出一个符合规范的名称。
确认建议的名称，然后运行
```
git checkout -b <branch-name>
```
。
明确确认重置操作——该操作会从本地
```
main
```
中丢弃这些提交——然后运行
```
git checkout main
```
和
```
git reset --hard origin/main
```
。
切换回新分支。

完成条件： 提交已位于新分支上，

main

与其远程分支一致，并且上述两项变更都已事先确认。

Step 3: Validate the branch name

第 3 步：验证分支名称

Check the current branch against the patterns in the branch-naming reference.

If it does not match, ask whether to rename it (

git branch -m <new-name>

) or start a fresh branch, and propose a compliant name either way.

Done when: the branch name matches a pattern in the reference file.

根据分支命名参考文件中的模式检查当前分支。

如果不符合，请询问是重命名当前分支（

git branch -m <new-name>

），还是创建一个全新分支；无论采用哪种方式，都应提出一个符合规范的名称。

完成条件： 分支名称与参考文件中的某个模式匹配。

Step 4: Ensure commits exist

第 4 步：确保存在提交

With no commits on the branch: use the

commit-workflow

skill for staged changes, ask before staging unstaged ones, and report that there is nothing to open a PR from when the tree is clean.

Done when: the branch has at least one commit ahead of

main

如果该分支上没有提交：对已暂存的更改使用

commit-workflow

skill；在暂存未暂存的更改之前先征得同意；当工作树干净时，报告没有可据以创建 PR 的内容。

完成条件： 当前分支至少比

main

领先一个提交。

Step 5: Push

第 5 步：推送

Base is

main

. Push when the branch has no remote yet:

git push -u origin $(git branch --show-current)

Done when: the head branch exists on the remote.

基础分支是

main

。当当前分支尚无对应的远程分支时，推送：

git push -u origin $(git branch --show-current)

。

完成条件： 当前分支已存在于远程仓库。

Step 6: Open the PR

第 6 步：创建 PR

bash

gh pr create --base main --head <head> --title "<title>" --body-file <file> [--attach <path> ...]

Title: the leading commit subject, or a descriptive line covering the set. Body: the format below, written to a file whenever it runs past one section.

Evidence is a real local file — a screenshot, a recording, or a path already on hand. Reference it in the body by its local path (

![Login error state](./evidence/login.png)

) and pass that same path as

--attach

, once per file;

gh

uploads each one and rewrites the matching reference to the hosted asset. With no local media, omit

--attach

. The flag needs

gh

≥ 2.99.0 and is refused alongside

--web

Done when: the PR exists, its URL is shown, and every local media path in the body was passed as

--attach

— GitHub renders each asset, not a broken relative link.

bash

gh pr create --base main --head <head> --title "<title>" --body-file <file> [--attach <path> ...]

标题：使用首个提交的 subject，或用一行描述性文字概括这组提交。正文：使用下面的格式；当正文超过一个小节时，将其写入文件。

证据必须是真实存在的本地文件——截图、录屏，或已有文件的路径。在正文中通过本地路径引用它（

![Login error state](./evidence/login.png)

），并将同一路径作为

--attach

传入，每个文件只传一次；

gh

会上传每个文件，并将对应引用改写为托管资源链接。如果没有本地媒体文件，则省略

--attach

。此参数要求

gh

≥ 2.99.0，且不能与

--web

同时使用。

完成条件： PR 已创建、显示其 URL，并且正文中的每个本地媒体路径都作为

--attach

传入——GitHub 会正确渲染每个资源，而不是显示失效的相对链接。

PR body format

PR 正文格式

Include each section that applies, in this order:

Opening —
```
Closes #N
```
when the PR resolves an issue, then 1–3 sentences of context: what this PR integrates and why now.
## What's included
— bullets summarizing the changes; link the task PRs, issues, or ADRs each bullet builds on. State load-bearing invariants explicitly (e.g. "query grain untouched, cap is display-only"). For UI changes, include screenshots or a recording, uploaded through
```
--attach
```
(Step 6).
## Deviations from plan
— only when the work follows a spec/PRD/plan and the implementation departs from it. One bullet per deviation with its rationale; include known-and-deferred issues with a link to the tracking issue.
## Manual checklist
— checkboxes (
```
- [ ]
```
) for the verification to run before merging; concrete and observable, not "test everything".

The body ends at the last section. This overrides any tool default that appends an AI attribution footer or co-author credit — leave the PR authored by the human alone.

按以下顺序包含所有适用的小节：

Opening — 当 PR 可以解决某个 issue 时，使用
```
Closes #N
```
，然后用 1–3 句话说明上下文：本 PR 集成什么，以及为什么现在要集成。
## What's included
— 使用要点概括各项更改；链接每个要点所依托的任务 PR、issue 或 ADR。明确写出支撑实现的关键 invariant（例：“query grain 保持不变，cap 仅用于显示”）。对于 UI 更改，应包含截图或录屏，并通过
```
--attach
```
上传（第 6 步）。
## Deviations from plan
— 只有在工作遵循 spec/PRD/plan，而实现偏离该计划时，才包含此节。每项偏离使用一个要点说明并附上理由；已知但推迟处理的问题应附上跟踪 issue 的链接。
## Manual checklist
— 使用复选框（
```
- [ ]
```
）列出合并前需要执行的验证；验证项应具体且可观察，而不是“测试所有内容”。

正文以最后一个小节结束。本规则优先于任何自动追加 AI 署名页脚或联合作者署名的工具默认行为——让 PR 保持仅由人类作者署名。

Guardrails

防护措施

Two actions are opt-in, each behind its own explicit confirmation: creating the branch in Step 2, and resetting the protected branch.

两项操作均需显式启用，并且每项都必须经过单独、明确的确认：第 2 步中创建分支，以及重置受保护分支。

Examples

示例

examples.md walks the transplant flow and the invalid-branch-name recovery end to end. Read it when the current state does not map cleanly onto a route in Step 1.

examples.md 从头到尾演示了提交迁移流程以及无效分支名称的恢复流程。当当前状态无法与第 1 步中的某条路径明确对应时，请阅读该文件。