Back to Details

write-pr-description

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write PR Description

编写PR描述

You are a senior software engineer writing a pull request description for this repository. Follow the conventions in this skill exactly.
你是一名资深软件工程师，正在为该仓库编写Pull Request（PR）描述。 请严格遵循此技能中的规范。

Step 1 — Collect context

步骤1 — 收集上下文

Run these commands in order.
Get the current branch name:
bash
git --no-pager rev-parse --abbrev-ref HEAD
Get the list of changed files:
bash
git --no-pager diff --name-only master
Get the full diff:
bash
git --no-pager diff --no-prefix --unified=100000 --minimal origin/master...HEAD
Get the commit log for this branch:
bash
git --no-pager log --oneline origin/master..HEAD
Read all output before proceeding. If the diff for a specific file is needed:
bash
git --no-pager diff --no-prefix --unified=100000 --minimal origin/master...HEAD -- <file>
If the user has not provided the Jira ticket key, ask for it before writing the description.
按顺序执行以下命令。
获取当前分支名称：
bash
git --no-pager rev-parse --abbrev-ref HEAD
获取已更改文件列表：
bash
git --no-pager diff --name-only master
获取完整差异：
bash
git --no-pager diff --no-prefix --unified=100000 --minimal origin/master...HEAD
获取该分支的提交日志：
bash
git --no-pager log --oneline origin/master..HEAD
继续前请阅读所有输出。如果需要特定文件的差异：
bash
git --no-pager diff --no-prefix --unified=100000 --minimal origin/master...HEAD -- <file>
如果用户未提供Jira工单编号，请在编写描述前向用户索要。

Step 2 — Write the PR description

步骤2 — 编写PR描述

Produce a single markdown document using the structure below. Follow every rule in each section.
使用以下结构生成单个Markdown文档。严格遵守每个部分的规则。

Title

标题

Format: 
## TICKET-KEY: <title>
Rules:
  • Start with the Jira ticket key (e.g. 
    APPPOCTOOL-85:
    ).
  • Copy the title verbatim from the Jira user story title. Only use the purpose of changes when explicitly told so.
  • Sentence case; no trailing period.
  • Keep under ~80 characters.
Good: 
## APPPOCTOOL-85: Generalize Kafka consumer tenant filter to support custom event types
Avoid:
  • No ticket key or vague title
  • Ticket key only with no description
  • Passive voice or overly long titles
格式：
## TICKET-KEY: <title>
规则：
  • 以Jira工单编号开头（例如：
    APPPOCTOOL-85:
    ）。
  • 直接复制Jira用户故事的标题。仅在明确要求时才使用变更目的作为标题。
  • 使用句首大写格式；末尾不加句号。
  • 长度控制在约80字符以内。
示例： 
## APPPOCTOOL-85: Generalize Kafka consumer tenant filter to support custom event types
避免：
  • 无工单编号或模糊标题
  • 仅工单编号无描述
  • 被动语态或过长标题

Purpose

目的

One or two sentences answering:
  1. Why are these changes needed?
  2. A user story reference: 
    US: [TICKET-KEY](url)
Do not describe how the change is implemented here — that belongs in Approach.
用1-2句话回答：
  1. 为什么需要这些变更？
  2. 用户故事引用：
    US: [TICKET-KEY](url)
请勿在此处描述变更的实现方式——这属于方案部分的内容。

Approach

方案

Two parts, always in this order:
Summary (2–3 sentences): A high-level technical narrative. The reader should understand the main idea without reading any code.
Implementation details (bullet list): Each bullet covers one concrete, self-contained change.
Rules for implementation details:
  • One bullet per logical change — a new class, a changed contract, a new config property, etc.
  • Up to 2 sentences per bullet. First sentence: what was done. Optional second: why, or a notable consequence.
  • No test changes — omit added/updated tests unless the PR is exclusively about testing.
  • No documentation changes — omit README or Javadoc updates unless the PR is exclusively about documentation.
  • Use backticks for class names, method names, property keys, and values.
  • Start each bullet with a past-tense verb: Introduced, Changed, Added, Replaced, Removed.
分为两部分，务必按此顺序：
概述（2-3句话）： 高层次的技术说明。读者无需查看代码即可理解核心思路。
实现细节（项目符号列表）： 每个项目符号对应一个具体、独立的变更。
实现细节规则：
  • 每个逻辑变更对应一个项目符号——例如新增类、修改契约、新增配置属性等。
  • 每个项目符号最多2句话。第一句：做了什么。可选第二句：原因或显著影响。
  • 不包含测试变更——除非PR专门针对测试，否则省略新增/更新的测试内容。
  • 不包含文档变更——除非PR专门针对文档，否则省略README或Javadoc的更新内容。
  • 类名、方法名、属性键和值使用反引号包裹。
  • 每个项目符号以过去式动词开头：Introduced（新增）、Changed（修改）、Added（添加）、Replaced（替换）、Removed（移除）。

Pre-Review Checklist

预审查清单

Always include the full checklist. Tick items that apply; leave the rest unchecked. Do not delete any item.
markdown
- [ ] **Self-reviewed Code** — Reviewed code for issues, unnecessary parts, and overall quality.
- [ ] **Change Notes** — NEWS.md updated with clear description and issue key.
- [ ] **Testing** — Confirmed changes were tested locally or on dev environment.
- [ ] **Dependent module build verification** — Ran manually when library changes impact downstream modules.
  > Actions → Verify Dependent Modules → Run workflow → select branch → Run.
- [ ] **Breaking Changes (if any)** — Handled if changes affect integration with other services.
- [ ] **New Properties / Environment Variables** — Updated README.md if new configs were added.
- [ ] **Environment Recreation Test (if needed)** — Verified that environment can be recreated successfully.
Tick Self-reviewed Code, Change Notes, and Testing by default (replace 
[ ]
with 
[x]
). Tick Dependent module build verification only if a shared library changes its public API. Tick Breaking Changes only if an interface, configuration key, or serialized format changes incompatibly. Tick New Properties / Environment Variables only if new config keys are added. Tick Environment Recreation Test only if infrastructure or startup configuration changes.
务必包含完整清单。勾选适用项；其余项保持未勾选状态。请勿删除任何条目。
markdown
- [ ] **Self-reviewed Code**（自审代码）——检查代码是否存在问题、冗余部分及整体质量。
- [ ] **Change Notes**（变更说明）——已更新NEWS.md，包含清晰描述和工单编号。
- [ ] **Testing**（测试）——确认变更已在本地或开发环境完成测试。
- [ ] **Dependent module build verification**（依赖模块构建验证）——当库变更影响下游模块时，已手动执行验证。
  > 操作路径：Actions → Verify Dependent Modules → Run workflow → 选择分支 → Run。
- [ ] **Breaking Changes (if any)**（破坏性变更（如有））——若变更影响与其他服务的集成，已妥善处理。
- [ ] **New Properties / Environment Variables**（新属性/环境变量）——若新增配置项，已更新README.md。
- [ ] **Environment Recreation Test (if needed)**（环境重建测试（如需））——确认环境可成功重建。
默认勾选Self-reviewed Code、Change Notes和Testing（将
[ ]
替换为
[x]
）。 仅当共享库修改了公共API时，勾选Dependent module build verification。 仅当接口、配置键或序列化格式发生不兼容变更时，勾选Breaking Changes。 仅当新增配置键时，勾选New Properties / Environment Variables。 仅当基础设施或启动配置变更时，勾选Environment Recreation Test。

Step 3 — Output

步骤3 — 输出

Print the complete PR description as a single markdown code block, ready to paste into GitHub.
For the full canonical guide with detailed examples, see ../../docs/pr/pr-description.md.
将完整的PR描述打印为单个Markdown代码块，可直接粘贴至GitHub。
如需包含详细示例的完整规范指南，请查看../../docs/pr/pr-description.md。