Back to Details

create-pr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Description Guidelines

PR描述指南

The work is done. Now, create a new PR for the current changes. If you're not on a new branch yet, create one first. Then, create the PR. Treat the changes as a real deliverable. The description is the first thing anyone reading this work will see, and most readers will not read the diff line by line.
工作已完成。现在为当前变更创建一个新的PR。如果你还不在新分支上，请先创建一个分支，然后再创建PR。 将这些变更视为真实的交付成果。描述内容是任何阅读这项工作的人首先看到的东西，大多数读者不会逐行查看差异。

Audience

受众

Write for someone who:
  • Is a developer on this team
  • Already knows this repository and its existing architecture
  • Has not seen this work before
You don't need to explain the codebase, the framework, or how things generally work in this system. You do need to explain everything new that this PR introduces — concepts, entities, flows, behaviors — clearly enough that the reader understands the change without opening the diff.
Cover only what's in this PR. If it's part of a larger effort (MVP, migration, refactor), one short line of framing is enough. Don't restate the whole project.
撰写时面向以下人群：
  • 本团队的开发人员
  • 已了解此仓库及其现有架构
  • 从未见过这项工作
你无需解释代码库、框架或系统中事物的一般工作方式。但你需要清晰解释此PR引入的所有新内容——概念、实体、流程、行为——让读者无需查看差异就能理解变更。
仅涵盖此PR中的内容。如果它是更大工作（MVP、迁移、重构）的一部分，只需用一行简短的话说明背景即可。不要重述整个项目。

Title

标题

The title is a one-line summary of the change. Specific, declarative, imperative mood.
  • Good: 
    Add alert incident lifecycle and worker pipeline
  • Bad: 
    Alert work
    / 
    Various improvements
    / 
    Updates to alerts module
If the repo uses a prefix convention (
feat:
, 
fix:
, scoping like 
[backend]
), match it.
标题是变更的单行摘要。要具体、陈述性、使用祈使语气。
  • 示例：
    Add alert incident lifecycle and worker pipeline
  • 反例：
    Alert work
    / 
    Various improvements
    / 
    Updates to alerts module
如果仓库使用前缀约定（如
feat:
、
fix:
，或
[backend]
这类范围标识），请遵循该约定。

What the description must convey

描述必须传达的内容

Every PR description, regardless of size, has to answer:
  1. What this PR does — the actual change, in plain language
  2. Why it exists — the problem, motivation, or unblock (skip only if the title makes it self-evident)
Beyond those two, include whatever else the reader needs to actually understand the change:
  • New domain concepts introduced (entities, events, jobs, statuses, etc.): what they are, when they're created, who produces and consumes them
  • Non-obvious decisions: trade-offs, why an alternative was rejected, schema or concurrency choices that aren't visible from the diff
  • Deliberate scope cuts and known follow-ups
  • Anything a reviewer would otherwise have to reverse-engineer from the code
  • How the change was tested or validated, when relevant
If something is only interesting at the code level — naming, file moves, mechanical refactors — leave it in the diff.
无论PR大小，每个PR描述都必须回答：
  1. 此PR做了什么——用平实语言描述实际变更
  2. 为什么需要它——问题、动机或要解决的阻塞（仅当标题已不言自明时可省略）
除了这两点，还需包含读者真正理解变更所需的其他信息：
  • 引入的新领域概念（实体、事件、任务、状态等）：它们是什么、何时创建、谁生成和使用它们
  • 非显而易见的决策：权衡、为何拒绝替代方案、从差异中看不到的 schema 或并发选择
  • 刻意缩减的范围和已知的后续工作
  • 评审者原本需要从代码中逆向推导的任何内容
  • 相关的变更测试或验证方式
如果某些内容仅在代码层面有意义——命名、文件移动、机械重构——留到差异中说明即可。

Structure

结构

Don't follow a fixed template. The right structure depends entirely on what this PR contains.
Decide the structure by asking: what does the reader need to know, and in what order? Then group that information into coherent sections with headers that describe their actual content. A small bug fix might be three sentences with no headers at all. A PR introducing a new subsystem might have five sections. Both are correct when they match the change.
Order matters: start with whatever orients the reader fastest (usually a summary), put context next, push edge cases, caveats, and follow-ups toward the end.
不要遵循固定模板。合适的结构完全取决于此PR包含的内容。
通过问自己来确定结构：读者需要知道什么，以及按什么顺序？ 然后将这些信息分组为连贯的部分，并用描述其实际内容的标题。一个小的bug修复可能只有三句话，没有标题。引入新子系统的PR可能有五个部分。只要与变更匹配，两种方式都是正确的。
顺序很重要：从最能快速引导读者的内容开始（通常是摘要），接下来是上下文，将边缘情况、注意事项和后续工作放在最后。

Linking

链接

If related issues or PRs exist, link them. Use GitHub's keyword syntax (
Closes #123
, 
Refs #456
) where appropriate.
如果存在相关问题或PR，请链接它们。适当时使用GitHub的关键词语法（如
Closes #123
、
Refs #456
）。

Style

风格

The description should read like a senior engineer wrote it for a colleague — direct, specific, no filler. The following phrasings mark text as AI-generated and must be avoided:
  • Marketing adjectives: "comprehensive," "robust," "seamless," "powerful," "elegant," "sophisticated," "production-ready," "first-class"
  • Hedging verbs: "aims to," "seeks to," "strives to" — just say what it does
  • Filler verbs: "leverages" / "utilizes" → "uses". "ensures that X" → just state X. "facilitates" → describe the actual mechanism
  • Throat-clearing openers: "It's worth noting that," "Importantly,", "In essence,", "It should be mentioned that"
  • Closing summaries: "In summary," "Overall," "Ultimately," — stop when you're done
  • Vague abstractions: "provides functionality for X" → say what it does. "handles the logic of Y" → say how
  • Artificial parallelism: "fast, clean, and reliable" — pick the one that matters
  • "Not just X but Y" construction
  • "In order to" → "to"
  • Restating the prompt or the section header in the first sentence of a section
Write declaratively. "Adds X. X is created when Y happens." Not "This PR aims to introduce X, which would help with Y."
Use prose where bullets would fragment a thought. Use bullets where prose would become a wall. Don't enumerate every file changed.
Use lowercase headings unless the repo's existing PRs use a different convention.
描述应读起来像是资深工程师写给同事的——直接、具体、没有冗余内容。以下表述带有AI生成的痕迹，必须避免：
  • 营销类形容词："comprehensive"、"robust"、"seamless"、"powerful"、"elegant"、"sophisticated"、"production-ready"、"first-class"
  • 模糊动词："aims to"、"seeks to"、"strives to"——直接说明做了什么
  • 冗余动词："leverages" / "utilizes" → "uses"；"ensures that X" → 直接陈述X；"facilitates" → 描述实际机制
  • 冗余开头："It's worth noting that,"、"Importantly,"、"In essence,"、"It should be mentioned that"
  • 冗余总结："In summary,"、"Overall,"、"Ultimately,"——说完就停止
  • 模糊抽象："provides functionality for X" → 说明具体做了什么；"handles the logic of Y" → 说明具体方式
  • 刻意排比："fast, clean, and reliable"——只选重要的那个
  • "Not just X but Y"结构
  • "In order to" → "to"
  • 在段落第一句重述提示或章节标题
使用陈述语气。比如"添加了X。当Y发生时创建X。"而不是"此PR旨在引入X，这将有助于解决Y。"
当项目符号会打断思路时使用散文，当散文会变成文字墙时使用项目符号。不要枚举每个更改的文件。
除非仓库现有PR使用不同约定，否则标题使用小写。

Output

输出

Return the title and description as raw markdown in separate code blocks I can paste into GitHub directly. No preamble, no commentary after the blocks.
If this PR includes noticeable UI work — new views, new sections, visual changes — remind me at the end to attach screenshots or a short screen recording to the PR for reviewer context.
将标题和描述作为原始markdown返回在单独的代码块中，我可以直接粘贴到GitHub中。不要有前言，代码块后不要有评论。
如果此PR包含显著的UI工作——新视图、新章节、视觉变更——请在最后提醒我将截图或简短屏幕录制附加到PR中，以便评审者了解上下文。