to-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Describe a Pull Request

描述 Pull Request

Create or update the pull request for the current task with a concise description that helps a reviewer understand why the change exists and the shape of the implementation.

为当前任务创建或更新 Pull Request，并提供简洁描述，帮助审查者了解变更存在的原因以及实现的整体结构。

Workflow

工作流

Read the description template:

Read({SKILLBASE}/references/pr_description_template.md)

Identify or create the pull request:
- Check the current branch for a PR with
```
gh pr view --json url,number,title,state,baseRefName,headRefName 2>/dev/null
```
  .
- If no PR exists, inspect
```
git status --short --branch
```
  and the commits on the current branch.
- Commit task-related changes when needed, push the branch with an upstream, and create a PR for it. Follow the repository's git safety protocol.
- Ask the user to select a PR only when the current branch has no relevant work and there is no safe current-branch PR to create.
Gather only the context needed to explain the change:
- Read the ticket and any relevant task artifacts.
- Read the complete PR diff and enough surrounding code to understand behavior and ownership.
- Use
```
gh pr view
```
  to collect PR metadata and changed files.
- Read
```
{SKILLBASE}/references/show-me.md
```
  for the visual-outline conventions used in the PR body.
Write the PR description using the template:
- Keep Why the change to exactly one sentence.
- Keep Special things to note to 1-3 bullets. Prioritize reviewer warnings, migrations, compatibility constraints, deliberate omissions, or surprising decisions. Write
```
- None.
```
  when there are no special considerations.
- Make Change outline a compact,
```
/show-me
```
  -inspired structural view rather than prose or a file-by-file changelog.
- Include only the views that help explain this PR:
  - SQL table and endpoint contract changes, plus pseudocode for business logic.
  - key data structure / type changes
  - A shallow file tree showing changed responsibilities.
  - React component tree changes, including important hooks, state, and package boundaries.
  - Call-tree, call-stack, control-flow, or data-flow changes.
- Prefer
```
diff
```
  blocks when showing changes to an existing shape. Show the complete target shape when most of it is new or diff notation would obscure ownership or order.
- Keep each view focused on what a reviewer needs. Omit categories that did not change.
- End with Things to be aware of, the last section, for what lies outside "what changed": decisions you made alone, surprises, what's not in the PR, and follow-ups, each marked as a ticket, a todo for the maintainer, or nothing needed. Keep its four lines, writing
```
None.
```
  after an empty one, so the reader knows it was considered. Special things to note stays about the change itself.
- Link a ticket the PR finishes with
```
Closes #n
```
  , but a ticket still waiting for the maintainer to try it (QA) with
```
Refs #n
```
  , so the merge doesn't close it first.
- optionaL: if you are aware of a ticket id/url, or related plan/document urls, or other relevant links, include them in the header, otherwise omit the header
Save and publish the description:
- Save it to
```
.scratch/pr-{number}/description.md
```
  :
```
.scratch/
```
  is gitignored, and GitHub holds the published description, so saving or rewriting it leaves nothing to commit.
- Update the PR with
```
gh pr edit {number} --body-file {output-path}
```
  .
- Confirm the update succeeded.
Report completion:
- Read
```
{SKILLBASE}/references/describe_pr_final_answer.md
```
  .
- Respond using that final answer template with the PR URL, the saved description path, and a concise list of changed files.
- Give each changed file two review links, built from the PR's head commit as it stands after your push (
```
gh pr view {number} --json url,headRefOid,files
```
  ), so an updated PR links its new head. Take
```
{owner}/{repo}
```
  from the PR
```
url
```
  :
  - Final version:
```
https://github.com/{owner}/{repo}/blob/{headRefOid}/{path}
```
    , where GitHub renders Markdown.
  - Diff:
```
{pr_url}/files#diff-{hash}
```
    , where
```
{hash}
```
    is the SHA-256 of the path (
```
printf %s '{path}' | shasum -a 256
```
    , or
```
sha256sum
```
    on Linux).
- When many files changed, link the key ones and list the rest by path.

Always read and follow

{SKILLBASE}/references/pr_description_template.md

. Do not expand the PR body beyond that template.

Write as one human talking to another: avoid jargon and slang, and use simple, coherent, concise language.

Name an issue or pull request by its title, never by its number alone:

#12 Add login

, not

#12

. This holds in the title, the body and anything you tell the user.

阅读描述模板：

Read({SKILLBASE}/references/pr_description_template.md)

识别或创建 Pull Request：
- 使用
```
gh pr view --json url,number,title,state,baseRefName,headRefName 2>/dev/null
```
  检查当前分支上是否已有 PR。
- 如果不存在 PR，则检查
```
git status --short --branch
```
  以及当前分支上的提交。
- 根据需要提交与任务相关的更改，推送分支并设置上游，然后为其创建 PR。遵循仓库的 Git 安全协议。
- 仅当当前分支没有相关工作，且无法安全地基于当前分支创建 PR 时，才请用户选择 PR。
仅收集解释变更所需的上下文：
- 阅读工单及任何相关任务产物。
- 阅读完整的 PR diff 以及足够多的周边代码，以理解行为和责任归属。
- 使用
```
gh pr view
```
  收集 PR 元数据和变更文件。
- 阅读
```
{SKILLBASE}/references/show-me.md
```
  ，了解 PR 正文中可视化概览的约定。
使用模板编写 PR 描述：
- 将 Why the change 保持为恰好一句话。
- 将 Special things to note 控制在 1-3 个项目符号内。优先说明需要审查者注意的事项、迁移、兼容性限制、有意省略的内容或出人意料的决策。如果没有需要特别说明的事项，则写入
```
- None.
```
  。
- 使 Change outline 呈现为紧凑的、受
```
/show-me
```
  启发的结构化视图，而不是叙述性文字或逐文件变更日志。
- 仅包含有助于解释此 PR 的视图：
  - SQL 表和 endpoint 契约变更，以及业务逻辑的伪代码。
  - 关键的 data structure / type 变更。
  - 展示变更职责的浅层文件树。
  - React 组件树变化，包括重要的 hooks、state 和 package 边界。
  - call-tree、call-stack、control-flow 或 data-flow 变化。
- 展示现有结构的变化时，优先使用
```
diff
```
  block。如果大部分内容都是新增内容，或者 diff 表示法会掩盖归属或顺序，则展示完整的目标结构。
- 每个视图只聚焦审查者所需的内容。省略未发生变化的类别。
- 最后以 Things to be aware of 结尾，并将其作为最后一个部分，用于说明“what changed”之外的事项：你独自做出的决策、意外情况、未包含在 PR 中的内容以及后续工作。每项都标为 ticket、维护者的 todo 或无需处理。保持该部分为四行；某一行没有内容时写入
```
None.
```
  ，让读者知道已经考虑过。Special things to note 仍只讨论变更本身。
- PR 完成某个 ticket 时，使用
```
Closes #n
```
  链接；但仍在等待维护者试用（QA）的 ticket 使用
```
Refs #n
```
  ，以免合并时提前将其关闭。
- 可选：如果知道 ticket id/url、相关 plan/document url 或其他相关链接，则将其包含在 header 中；否则省略 header。
保存并发布描述：
- 将描述保存到
```
.scratch/pr-{number}/description.md
```
  ：
```
.scratch/
```
  已被 gitignore，而 GitHub 会保存已发布的描述，因此保存或重写描述不会产生需要提交的内容。
- 使用
```
gh pr edit {number} --body-file {output-path}
```
  更新 PR。
- 确认更新成功。
报告完成情况：
- 阅读
```
{SKILLBASE}/references/describe_pr_final_answer.md
```
  。
- 按照该最终答复模板回复，其中包含 PR URL、保存的描述路径以及简洁的变更文件列表。
- 为每个变更文件提供两个审查链接，基于推送后 PR 当前的 head commit 构建（
```
gh pr view {number} --json url,headRefOid,files
```
  ），从而让更新后的 PR 链接到新的 head。从 PR 的
```
url
```
  获取
```
{owner}/{repo}
```
  ：
  - 最终版本：
```
https://github.com/{owner}/{repo}/blob/{headRefOid}/{path}
```
    ，GitHub 会以 Markdown 形式渲染该页面。
  - Diff：
```
{pr_url}/files#diff-{hash}
```
    ，其中
```
{hash}
```
    是路径的 SHA-256 值（
```
printf %s '{path}' | shasum -a 256
```
    ，或在 Linux 上使用
```
sha256sum
```
    ）。
- 变更文件很多时，链接关键文件，并按路径列出其余文件。

始终阅读并遵循

{SKILLBASE}/references/pr_description_template.md

。不要超出该模板扩展 PR 正文。

像人与人交谈一样写作：避免行话和俚语，使用简单、连贯、简洁的语言。

始终使用 title 称呼 issue 或 pull request，绝不能只使用编号：在标题、正文以及告知用户的任何内容中均遵循此规则。例如：使用

#12 Add login

，而不是

#12

。