Pull Request Description Standards

拉取请求（Pull Request）描述规范

PR Title Conventions

PR标题规范

The PR title is the first thing reviewers see. It must communicate the change clearly and concisely.

PR标题是评审者首先看到的内容，必须清晰、简洁地传达变更内容。

Format

格式

<type>: <concise description of what changed>

<类型>: <变更内容的简洁描述>

Type Prefixes

类型前缀

Prefix	Use When
`feat:`	Adding new functionality
`fix:`	Correcting a bug
`refactor:`	Restructuring without behavior change
`docs:`	Documentation only
`test:`	Adding or updating tests
`chore:`	Dependencies, tooling, config
`perf:`	Performance improvement
`style:`	Formatting, whitespace, naming
`ci:`	CI/CD pipeline changes
`revert:`	Reverting a previous change

前缀	使用场景
`feat:`	添加新功能
`fix:`	修复Bug
`refactor:`	重构代码（无行为变更）
`docs:`	仅修改文档
`test:`	添加或更新测试
`chore:`	依赖、工具、配置变更
`perf:`	性能优化
`style:`	格式、空白字符、命名规范调整
`ci:`	CI/CD流水线变更
`revert:`	回滚之前的变更

Title Rules

标题规则

Keep under 72 characters
Use imperative mood: "Add search endpoint" not "Added search endpoint" or "Adds search endpoint"
Do not end with a period
Be specific: "fix: resolve login redirect loop on expired sessions" not "fix: login bug"
Include ticket number if applicable: "feat: add user search (PROJ-1234)"

长度控制在72字符以内
使用祈使语气：例如用"Add search endpoint"而非"Added search endpoint"或"Adds search endpoint"
结尾不要加句号
描述要具体：例如用"fix: resolve login redirect loop on expired sessions"而非"fix: login bug"
如有适用，包含工单编号：例如"feat: add user search (PROJ-1234)"

Good vs Bad Titles

标题示例对比

Bad:  "Updates"
Good: "feat: add full-text search to user directory"

Bad:  "Fix bug"
Good: "fix: prevent duplicate charge on payment retry"

Bad:  "Refactoring the auth module and also fixing some tests and updating docs"
Good: "refactor: extract token validation into dedicated service"

Bad:  "Updates"
Good: "feat: add full-text search to user directory"

Bad:  "Fix bug"
Good: "fix: prevent duplicate charge on payment retry"

Bad:  "Refactoring the auth module and also fixing some tests and updating docs"
Good: "refactor: extract token validation into dedicated service"

PR Description Template

PR描述模板

Every PR should follow a structured description. Use this template as a starting point and adapt to your team's needs.

每个PR都应遵循结构化描述。以下模板可作为起点，根据团队需求调整。

Standard Template

标准模板

markdown

undefined

markdown

undefined

Summary

摘要

A 1-3 sentence overview of what this PR does and why. This should be understandable by someone who has not read the code.

用1-3句话概述本PR的作用及原因。即使未阅读代码的人也能理解。

Motivation

动机

Why is this change needed? Link to the issue, bug report, or product requirement that motivated this work.

Closes #123

为什么需要此次变更？关联驱动本次工作的问题、Bug报告或产品需求。

Closes #123

Changes

变更内容

A bulleted list of the specific changes made:

Added
```
SearchService
```
class with full-text query support
Created
```
/api/users/search
```
endpoint with pagination
Added search index migration for the users table
Updated API documentation with new endpoint

列出具体的变更点：

新增支持全文查询的
```
SearchService
```
类
创建带分页功能的
```
/api/users/search
```
接口
为用户表添加搜索索引迁移
更新API文档以包含新接口

Test Plan

测试方案

How was this change tested? Be specific.

Unit tests for
```
SearchService
```
covering empty queries, partial matches, and pagination
Integration test for the search endpoint with test database
Manual testing: verified search returns expected results in staging
Load tested with 10k users in the index

如何验证此次变更？请具体说明。

为
```
SearchService
```
编写单元测试，覆盖空查询、部分匹配和分页场景
为搜索接口编写集成测试，使用测试数据库
手动测试：在预发布环境验证搜索返回预期结果
对索引中的10k用户进行负载测试

Screenshots / Recordings

截图/录屏

If the change has a visual component, include before/after screenshots or a screen recording. For API changes, include example request/response pairs.

Before: (screenshot or N/A)

After: (screenshot or N/A)

如果变更涉及视觉内容，包含变更前后的截图或录屏。对于API变更，包含示例请求/响应。

变更前： (截图或填N/A)

变更后： (截图或填N/A)

Notes for Reviewers

给评审者的说明

Any additional context that will help reviewers:

I chose cursor-based pagination over offset because [reason]
The migration is backward-compatible and can be rolled back
This depends on PR #456 being merged first

提供有助于评审者理解的额外上下文：

我选择基于游标而非偏移量的分页，原因是[具体理由]
此迁移支持向后兼容，可回滚
本PR依赖PR #456合并后才能生效

Checklist

检查清单

Tests pass locally
Code follows project style guidelines
Documentation updated if needed
No secrets or credentials included
Migration is reversible (if applicable)
Breaking changes documented (if applicable)

undefined

本地测试通过
代码符合项目风格指南
必要时已更新文档
未包含密钥或凭证
迁移可回滚（如适用）
已记录破坏性变更（如适用）

undefined

Minimal Template (for Small Changes)

极简模板（适用于小型变更）

markdown

undefined

markdown

undefined

Summary

摘要

Fix null pointer exception when user profile has no avatar set.

Closes #789

修复用户资料未设置头像时的空指针异常。

Closes #789

Changes

变更内容

Added null check in
```
UserProfile.getAvatarUrl()
```
Added test case for users without avatars

在
```
UserProfile.getAvatarUrl()
```
中添加空值检查
为无头像用户添加测试用例

Test Plan

测试方案

Unit test added for the null avatar case
Existing tests pass

undefined

已为空头像场景添加单元测试
现有测试全部通过

undefined

Linking Issues

关联问题

Automatic Issue Closing

自动关闭问题

Use GitHub keywords in the PR description body to automatically close issues when the PR merges:

markdown

Closes #123
Fixes #456
Resolves #789

Place these in the Motivation or Summary section
Use one keyword per issue, each on its own line for multiple issues
These keywords are case-insensitive

在PR描述正文中使用GitHub关键字，PR合并时可自动关闭问题：

markdown

Closes #123
Fixes #456
Resolves #789

将这些关键字放在动机或摘要部分
多个问题时，每个关键字单独占一行
关键字不区分大小写

Cross-Repository References

跨仓库引用

markdown

Closes org/other-repo#123

markdown

Closes org/other-repo#123

Linking Without Closing

仅关联不关闭

When a PR is related to but does not fully resolve an issue:

markdown

Related to #123
Part of #456
See also #789

当PR与问题相关但未完全解决时：

markdown

Related to #123
Part of #456
See also #789

Draft PRs vs Ready-for-Review

草稿PR与待评审PR

When to Open a Draft PR

何时创建草稿PR

Open a draft PR when:

You want early feedback on your approach before finishing
The work is in progress but you want CI to run
You are working on a stacked PR that depends on another PR
You want to share progress with the team without requesting formal review
You need to collaborate with another developer on the branch

在以下场景创建草稿PR：

完成前想提前获取关于实现思路的反馈
工作进行中但希望触发CI运行
正在处理依赖其他PR的堆叠PR
想与团队分享进度但不请求正式评审
需要与其他开发者协作开发该分支

Draft PR Etiquette

草稿PR规范

Prefix the title with
```
[WIP]
```
or
```
[Draft]
```
in addition to using GitHub's draft status
State what is done and what remains in the description:

markdown

undefined

除了设置GitHub的草稿状态，还需在标题前添加
```
[WIP]
```
或
```
[Draft]
```
前缀
在描述中说明已完成和待完成的内容：

markdown

undefined

Status

状态

What I Need Feedback On

需反馈的点

Is the schema design appropriate for the query patterns we expect?
Should we use a separate table for search metadata?


3. Convert to ready-for-review only when all work is complete
4. Do not request specific reviewers on draft PRs unless you need targeted feedback

该schema设计是否符合我们预期的查询模式？
是否应为搜索元数据单独建表？


3. 仅当所有工作完成后，再转为待评审状态
4. 除非需要针对性反馈，否则不要为草稿PR指定特定评审者

Converting to Ready

转为待评审状态前的检查

Before converting a draft PR to ready-for-review:

All commits are clean and well-organized
Description is complete with all template sections filled
CI passes
Self-review completed (see checklist below)
WIP or Draft prefix removed from title

将草稿PR转为待评审前，请确认：

所有提交清晰且组织有序
描述已完整填写所有模板部分
CI运行通过
已完成自审（见下方检查清单）
标题中的WIP或Draft前缀已移除

PR Size Guidelines

PR大小指南

Target Size

目标大小

Metric	Target	Maximum
Lines changed	50-200	400
Files changed	1-8	15
Commits	1-5	10
Review time	15-30 min	60 min

指标	目标值	最大值
变更行数	50-200	400
变更文件数	1-8	15
提交次数	1-5	10
评审时间	15-30分钟	60分钟

Why Small PRs Matter

小PR的重要性

Faster review turnaround (hours not days)
Higher quality reviews (reviewers stay focused)
Easier to revert if something breaks
Less merge conflict risk
Better git history for debugging

评审周转更快（以小时而非天计算）
评审质量更高（评审者更专注）
出现问题时更容易回滚
合并冲突风险更低
更便于调试的Git历史

Breaking Down Large Changes

拆分大型变更

When a change exceeds size guidelines, split it into a sequence of PRs:

Infrastructure first -- Schema changes, new interfaces, configuration
Core logic -- Business logic implementation
Integration -- Wiring components together, endpoint creation
Polish -- Error handling improvements, logging, documentation

Each PR should be independently mergeable and should not break existing functionality.

当变更超出大小指南时，将其拆分为一系列PR：

先做基础设施——Schema变更、新接口、配置
核心逻辑——业务逻辑实现
集成——组件对接、接口创建
优化——错误处理改进、日志、文档

每个PR应可独立合并，且不能破坏现有功能。

Acceptable Large PRs

可接受的大型PR

Some PRs are legitimately large:

Generated code (migrations, protobuf output, lock files)
Bulk rename or reformatting (use a separate commit or PR)
Dependency upgrades with lock file changes
Initial project scaffolding

Mark these clearly in the description: "Note: This PR is large because it includes generated migration files. The actual hand-written changes are in

src/services/

(~80 lines)."

部分PR确实需要较大规模：

生成代码（迁移文件、protobuf输出、锁文件）
批量重命名或格式化（使用单独的提交或PR）
依赖升级及锁文件变更
项目初始脚手架搭建

在描述中明确标注："注意：本PR较大是因为包含生成的迁移文件，手动编写的变更仅在

src/services/

目录（约80行）。"

Stacked PRs

堆叠PR

Stacked PRs break a large feature into a chain of dependent PRs that build on each other.

堆叠PR将大型功能拆分为一系列相互依赖的PR，逐层构建。

When to Use Stacked PRs

何时使用堆叠PR

A feature requires 500+ lines of changes
You want reviewers to focus on one logical layer at a time
Multiple developers are working on interconnected changes

功能变更需要500行以上代码
希望评审者一次专注于一个逻辑层面
多个开发者在开发相互关联的变更

Stacked PR Workflow

堆叠PR工作流

PR #1: feat: add user search database schema
  └── PR #2: feat: add search service with query logic
       └── PR #3: feat: add search API endpoint and docs

PR #1: feat: add user search database schema
  └── PR #2: feat: add search service with query logic
       └── PR #3: feat: add search API endpoint and docs

Stacked PR Rules

堆叠PR规则

Each PR in the stack must work independently if merged alone (no broken states)
Number the PRs and cross-reference them:

markdown

undefined

栈中的每个PR即使单独合并也需能正常工作（无损坏状态）
为PR编号并相互引用：

markdown

undefined

Stack

堆叠关系

This is PR 2 of 3 in the search feature stack:

#100 - Database schema (merged)
#101 - Search service (this PR)
#102 - API endpoint (draft, depends on this PR)


3. Base each PR on the previous PR's branch, not on main:

```bash

本PR是搜索功能栈中的第2个，共3个：

#100 - 数据库schema（已合并）
#101 - 搜索服务（本PR）
#102 - API接口（草稿，依赖本PR）


3. 每个PR基于前一个PR的分支，而非主分支：

```bash

PR 1

git checkout -b feature/search-schema

PR 2 (based on PR 1)

PR 2（基于PR 1）

git checkout -b feature/search-service feature/search-schema

PR 3 (based on PR 2)

PR 3（基于PR 2）

git checkout -b feature/search-endpoint feature/search-service


4. When an earlier PR is merged, rebase subsequent PRs onto main
5. Review and merge in order -- do not merge PR 3 before PR 1

git checkout -b feature/search-endpoint feature/search-service


4. 当早期PR合并后，将后续PR变基到主分支
5. 按顺序评审并合并——不要在PR 1合并前合并PR 3

Updating Stacked PRs After Review

评审后更新堆叠PR

When you need to update PR 1 based on review feedback:

bash

undefined

当需要根据评审反馈更新PR 1时：

bash

undefined

Make changes on PR 1's branch

切换到PR 1的分支并修改

git checkout feature/search-schema

... make changes, commit ...

... 进行修改、提交 ...

Rebase PR 2 onto updated PR 1

将PR 2变基到更新后的PR 1

git checkout feature/search-service git rebase feature/search-schema

Rebase PR 3 onto updated PR 2

将PR 3变基到更新后的PR 2

git checkout feature/search-endpoint git rebase feature/search-service

Force-push all updated branches

强制推送所有更新后的分支

git push --force-with-lease origin feature/search-schema git push --force-with-lease origin feature/search-service git push --force-with-lease origin feature/search-endpoint

undefined

git push --force-with-lease origin feature/search-schema git push --force-with-lease origin feature/search-service git push --force-with-lease origin feature/search-endpoint

undefined

Self-Review Checklist

自审检查清单

Before requesting review, go through the PR yourself as if you were the reviewer.

请求评审前，以评审者的视角自行检查PR。

Code Quality

代码质量

No commented-out code left behind
No debug logging (console.log, print statements) unless intentional
No TODO comments without associated issue numbers
Variable and function names are clear and consistent
No unnecessary complexity -- could this be simpler?
No duplicated logic that should be extracted

无遗留的注释代码
无调试日志（console.log、print语句），除非是有意保留
无未关联工单编号的TODO注释
变量和函数名称清晰且一致
无不必要的复杂度——是否可以更简单？
无应提取的重复逻辑

Correctness

正确性

Edge cases handled (null, empty, boundary values)
Error cases handled with appropriate messages
No race conditions in concurrent code
Database queries are efficient (no N+1, proper indexes)
Feature flags used for incomplete or experimental features

已处理边缘情况（空值、边界值等）
错误情况已处理并给出合适的提示信息
并发代码无竞态条件
数据库查询高效（无N+1查询、已添加适当索引）
未完成或实验性功能已使用功能开关

Security

安全性

No secrets, API keys, or credentials in the code
User input is validated and sanitized
Authentication and authorization checks present where needed
SQL injection, XSS, and CSRF protections in place
Sensitive data is not logged

代码中无密钥、API密钥或凭证
用户输入已验证和清理
必要的地方已添加认证和授权检查
已防范SQL注入、XSS和CSRF攻击
敏感数据未被日志记录

Testing

测试

New code has corresponding tests
Tests cover happy path and error cases
Tests are deterministic (no flaky tests)
Test names clearly describe what they verify

新代码有对应的测试用例
测试覆盖正常路径和错误路径
测试具有确定性（无不稳定测试）
测试名称清晰描述其验证内容

Documentation

文档

Public APIs have documentation
Complex logic has explanatory comments
README updated if setup steps changed
CHANGELOG updated for user-facing changes
API documentation updated for endpoint changes

公共API已添加文档
复杂逻辑有解释性注释
若安装步骤变更，已更新README
用户可见的变更已更新CHANGELOG
接口变更已更新API文档

Diff Review

Diff评审

Reviewed the full diff on GitHub before requesting review
No unintended file changes (formatting, unrelated fixes)
Commit history is clean and logical
No merge commits from pulling main (rebase instead)

请求评审前已在GitHub上查看完整Diff
无意外的文件变更（格式调整、无关修复）
提交历史清晰且逻辑连贯
无拉取主分支产生的合并提交（使用变基替代）

Responding to Review Feedback

响应评审反馈

Etiquette

规范

Respond to every comment, even if just with "Done" or "Fixed"
If you disagree, explain your reasoning respectfully and propose alternatives
Do not resolve comments yourself unless your team convention allows it -- let the reviewer resolve their own comments
If a discussion becomes lengthy, move it to a call and summarize the outcome in the PR
Push review fixes as new commits during review, squash before merge

回复每条评论，即使只是“已完成”或“已修复”
若不同意，礼貌地解释你的理由并提出替代方案
除非团队惯例允许，否则不要自行标记评论为已解决——让评审者自行标记
若讨论变得冗长，转到会议沟通并在PR中总结结果
评审期间的修复以新提交推送，合并前再压缩提交

Handling Requested Changes

处理变更请求

markdown

undefined

markdown

undefined

Review Response

评审回复

[Comment about error handling] Fixed -- added try/catch with proper logging in abc123
[Comment about naming] Renamed
```
processData
```
to
```
validateAndStorePayment
```
in def456
[Comment about test coverage] Added edge case tests for empty input in ghi789
[Comment about architecture] I'd prefer to keep this in a single service for now -- the traffic doesn't justify the complexity of splitting. Happy to discuss further.

undefined

[关于错误处理的评论] 已修复——在abc123提交中添加了带适当日志的try/catch
[关于命名的评论] 已将
```
processData
```
重命名为
```
validateAndStorePayment
```
（def456提交）
[关于测试覆盖率的评论] 已为空输入添加边缘情况测试（ghi789提交）
[关于架构的评论] 目前我更倾向于将其保留在单个服务中——当前流量不足以支撑拆分的复杂度。欢迎进一步讨论。

undefined

Example: Well-Written PR

示例：优质PR

markdown

undefined

markdown

undefined

feat: add cursor-based pagination to user search endpoint

Summary

摘要

Replaces the offset-based pagination on

/api/users/search

with cursor-based pagination to handle our growing user base without performance degradation.

将

/api/users/search

接口的基于偏移量的分页替换为基于游标的分页，以应对不断增长的用户量，避免性能下降。

Motivation

动机

The user directory now has 2M+ records. Offset pagination causes increasingly slow queries at high page numbers because the database must scan and discard rows. Cursor-based pagination maintains constant performance regardless of position.

Closes #1234

用户目录现在已有2M+条记录。基于偏移量的分页在高页码时查询速度越来越慢，因为数据库必须扫描并丢弃大量行。基于游标的分页无论处于哪个位置都能保持稳定的性能。

Closes #1234

Changes

变更内容

Replaced
```
page
```
and
```
per_page
```
params with
```
cursor
```
and
```
limit
```
Added
```
next_cursor
```
and
```
has_more
```
to response envelope
Updated
```
UserRepository.search()
```
to use keyset pagination on
```
(created_at, id)
```
Added database index on
```
(created_at, id)
```
for the users table
Marked old
```
page
```
parameter as deprecated with warning header
Updated API docs with new pagination format

将
```
page
```
和
```
per_page
```
参数替换为
```
cursor
```
和
```
limit
```
在响应包中添加
```
next_cursor
```
和
```
has_more
```
字段
更新
```
UserRepository.search()
```
以使用基于
```
(created_at, id)
```
的键集分页
为用户表添加
```
(created_at, id)
```
的数据库索引
将旧的
```
page
```
参数标记为已废弃，并返回警告头
更新API文档以包含新的分页格式

Test Plan

测试方案

Unit tests for cursor encoding/decoding
Integration tests verifying correct page traversal over 1000 records
Verified backward compatibility: requests with
```
page
```
param still work (with deprecation warning)
Load test: p99 latency at page 10000 dropped from 2.3s to 45ms

为游标编码/解码编写单元测试
编写集成测试，验证1000条记录的正确分页遍历
验证向后兼容性：使用
```
page
```
参数的请求仍可工作（返回废弃警告）
负载测试：第10000页的p99延迟从2.3s降至45ms

Notes for Reviewers

给评审者的说明

The cursor is a base64-encoded JSON of
```
{created_at, id}
```
-- intentionally opaque to clients
Old
```
page
```
parameter will be removed in v3.0 (tracked in #1235)
Migration
```
20240115_add_users_pagination_index.sql
```
is safe to run on production without downtime

undefined

游标是
```
{created_at, id}
```
的base64编码JSON——对客户端故意设为不透明
旧的
```
page
```
参数将在v3.0版本移除（跟踪于#1235）
迁移文件
```
20240115_add_users_pagination_index.sql
```
可安全在生产环境运行，无需停机

undefined

pr-description

Original

Translation

Pull Request Description Standards

拉取请求（Pull Request）描述规范

PR Title Conventions

PR标题规范

Format

格式

Type Prefixes

类型前缀

Title Rules

标题规则

Good vs Bad Titles

标题示例对比

PR Description Template

PR描述模板

Standard Template

标准模板

Summary

摘要

Motivation

动机

Changes

变更内容

Test Plan

测试方案

Screenshots / Recordings

截图/录屏

Notes for Reviewers

给评审者的说明

Checklist

检查清单

Minimal Template (for Small Changes)

极简模板（适用于小型变更）

Summary

摘要

Changes

变更内容

Test Plan

测试方案

Linking Issues

关联问题

Automatic Issue Closing

自动关闭问题

Cross-Repository References

跨仓库引用

Linking Without Closing

仅关联不关闭

Draft PRs vs Ready-for-Review

草稿PR与待评审PR

When to Open a Draft PR

何时创建草稿PR

Draft PR Etiquette

草稿PR规范

Status

状态

What I Need Feedback On

需反馈的点

Converting to Ready

转为待评审状态前的检查

PR Size Guidelines

PR大小指南

Target Size

目标大小

Why Small PRs Matter

小PR的重要性

Breaking Down Large Changes

拆分大型变更

Acceptable Large PRs

可接受的大型PR

Stacked PRs

堆叠PR

When to Use Stacked PRs

何时使用堆叠PR

Stacked PR Workflow

堆叠PR工作流

Stacked PR Rules

堆叠PR规则

Stack