pr-quality-checklist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Quality Checklist Skill

PR质量检查清单技能

Summary

概述

Comprehensive guide for creating high-quality pull requests that are easy to review, well-documented, and follow team standards. Includes templates, size guidelines, and best practices for both authors and reviewers.

本指南详细介绍了如何创建易于评审、文档完善且符合团队标准的高质量拉取请求（PR）。包含针对PR作者和评审者的模板、大小规范及最佳实践。

When to Use

适用场景

Before creating any pull request
When reviewing others' PRs
To establish team PR standards
During onboarding of new team members
When PR reviews are taking too long

创建任何PR之前
评审他人PR时
制定团队PR标准时
新团队成员入职培训时
PR评审耗时过长时

Quick Checklist

快速检查清单

Before Creating PR

创建PR前

PR title follows convention:
```
type(scope): description
```
Description includes summary, related tickets, and test plan
Changes are focused and related (single concern)
Code is self-reviewed for obvious issues
Tests added/updated and passing
No debugging code (console.log, debugger, etc.)
TypeScript/type errors resolved
Documentation updated if needed
Screenshots included for UI changes
Changeset added (for user-facing changes)

PR标题遵循规范：
```
type(scope): description
```
描述包含概要、关联工单和测试计划
变更内容聚焦且相关（单一关注点）
代码已自行评审，排除明显问题
已添加/更新测试且测试通过
无调试代码（console.log、debugger等）
TypeScript/类型错误已解决
必要时已更新文档
UI变更已包含截图
用户可见变更已添加Changeset

PR Title Format

PR标题格式

Convention

规范

{type}({scope}): {short description}

{type}({scope}): {short description}

Types

类型

feat: New feature
fix: Bug fix
refactor: Code change that neither fixes a bug nor adds a feature
docs: Documentation only
style: Formatting, missing semicolons, etc. (no code change)
test: Adding or updating tests
chore: Maintenance tasks, dependency updates
perf: Performance improvement
ci: CI/CD changes

feat: 新功能
fix: Bug修复
refactor: 既不修复Bug也不添加功能的代码变更
docs: 仅文档更新
style: 格式调整、缺失分号等（无代码逻辑变更）
test: 添加或更新测试
chore: 维护任务、依赖更新
perf: 性能优化
ci: CI/CD变更

Examples

示例

feat(auth): add OAuth2 login support
fix(cart): resolve race condition in checkout
refactor(search): extract query param parsing logic
docs(api): update authentication examples
test(payment): add integration tests for Stripe
chore(deps): update Next.js to v15
perf(images): implement lazy loading for gallery
ci(deploy): add staging environment workflow

feat(auth): add OAuth2 login support
fix(cart): resolve race condition in checkout
refactor(search): extract query param parsing logic
docs(api): update authentication examples
test(payment): add integration tests for Stripe
chore(deps): update Next.js to v15
perf(images): implement lazy loading for gallery
ci(deploy): add staging environment workflow

Scope Guidelines

范围指南

Use component/module name:
```
auth
```
,
```
cart
```
,
```
search
```
,
```
api
```
Be specific but not too granular:
```
user-profile
```
not
```
user-profile-settings-modal
```
Consistent with codebase structure

使用组件/模块名称：
```
auth
```
、
```
cart
```
、
```
search
```
、
```
api
```
具体但不过于细碎：
```
user-profile
```
而非
```
user-profile-settings-modal
```
与代码库结构保持一致

PR Description Template

PR描述模板

Standard Template

标准模板

markdown

undefined

markdown

undefined

Summary

概要

Added OAuth2 authentication flow
Integrated with Auth0 provider
Updated login UI components

新增OAuth2认证流程
集成Auth0提供商
更新登录UI组件

Related Tickets

关联工单

Closes #123
Related to #456
Fixes ENG-789

Closes #123
Related to #456
Fixes ENG-789

Changes

变更内容

Added

新增

```
src/lib/auth/oauth2.ts
```
- OAuth2 client implementation
```
src/app/api/auth/callback/route.ts
```
- Auth callback handler
```
src/components/OAuthButtons.tsx
```
- OAuth login buttons

```
src/lib/auth/oauth2.ts
```
- OAuth2客户端实现
```
src/app/api/auth/callback/route.ts
```
- 认证回调处理器
```
src/components/OAuthButtons.tsx
```
- OAuth登录按钮

Modified

修改

```
src/components/LoginForm.tsx
```
- Added OAuth buttons
```
src/lib/auth/index.ts
```
- Export new auth methods
```
README.md
```
- Updated setup instructions

```
src/components/LoginForm.tsx
```
- 添加OAuth按钮
```
src/lib/auth/index.ts
```
- 导出新的认证方法
```
README.md
```
- 更新安装说明

Removed

删除

```
src/lib/auth/legacy.ts
```
- Deprecated auth code
```
src/components/OldLoginForm.tsx
```
- Replaced by new form

```
src/lib/auth/legacy.ts
```
- 已废弃的认证代码
```
src/components/OldLoginForm.tsx
```
- 被新表单替代

Screenshots

截图

Desktop

桌面端

Mobile

移动端

Before/After (if applicable)

前后对比（如有）

Before	After

之前	之后

Testing

测试

Breaking Changes

破坏性变更

⚠️ Breaking Change: The

login()

function signature has changed.

Before:

typescript

login(username: string, password: string)

After:

typescript

login({ username: string, password: string, provider?: 'local' | 'oauth' })

Migration:

typescript

// Old
await login('user', 'pass');

// New
await login({ username: 'user', password: 'pass' });

⚠️ 破坏性变更：

login()

函数签名已变更。

之前：

typescript

login(username: string, password: string)

之后：

typescript

login({ username: string, password: string, provider?: 'local' | 'oauth' })

迁移方式：

typescript

// 旧写法
await login('user', 'pass');

// 新写法
await login({ username: 'user', password: 'pass' });

Checklist

检查清单

Code follows project style guidelines
Self-review completed
Comments added for complex logic
Documentation updated (if needed)
Changeset added (if user-facing change)
No console.log/debugger statements left
No TypeScript errors
Tests pass locally
Build succeeds

undefined

代码遵循项目风格指南
已完成自我评审
复杂逻辑已添加注释
必要时已更新文档
用户可见变更已添加Changeset
无残留console.log/debugger语句
无TypeScript错误
本地测试通过
构建成功

undefined

Minimal Template (for small changes)

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

markdown

undefined

markdown

undefined

Summary

概要

Brief description of the change.

变更内容的简短描述。

Changes

变更

Modified
```
file.ts
```
to fix XYZ

修改
```
file.ts
```
以修复XYZ问题

Testing

测试

Tests pass
Verified manually

---

测试通过
已手动验证

---

Size Guidelines

大小规范

Ideal PR Size

理想PR大小

Lines changed: < 300 (excluding generated files)
Files changed: < 15
Review time: < 30 minutes
Commits: 1-5 logical commits

变更行数：< 300行（排除自动生成文件）
变更文件数：< 15个
评审时间：< 30分钟
提交次数：1-5次逻辑提交

Size Categories

大小分类

Size	Lines	Files	Review Time	Recommendation
XS	< 50	1-3	5 min	✅ Ideal for hotfixes
S	50-150	3-8	15 min	✅ Good size
M	150-300	8-15	30 min	⚠️ Consider splitting
L	300-500	15-25	1 hour	❌ Should split
XL	500+	25+	2+ hours	❌ Must split

大小	行数	文件数	评审时间	建议
XS	< 50	1-3	5分钟	✅ 热修复的理想大小
S	50-150	3-8	15分钟	✅ 合适大小
M	150-300	8-15	30分钟	⚠️ 考虑拆分
L	300-500	15-25	1小时	❌ 应当拆分
XL	500+	25+	2小时以上	❌ 必须拆分

When to Split PRs

何时拆分PR

1. By Feature Phase

1. 按功能阶段拆分

PR #1: MVP implementation (core functionality)
PR #2: Polish and edge cases
PR #3: Additional features

PR #1: MVP实现（核心功能）
PR #2: 优化和边界场景处理
PR #3: 附加功能

2. By Layer

2. 按架构分层拆分

PR #1: Database schema changes
PR #2: Backend API implementation
PR #3: Frontend UI integration
PR #4: Tests and documentation

PR #1: 数据库 schema 变更
PR #2: 后端API实现
PR #3: 前端UI集成
PR #4: 测试与文档

3. By Concern

3. 按关注点拆分

PR #1: Refactoring (no behavior change)
PR #2: New feature (builds on refactored code)
PR #3: Tests for new feature

PR #1: 重构（无行为变更）
PR #2: 新功能（基于重构后的代码）
PR #3: 新功能测试

4. By Risk Level

4. 按风险等级拆分

PR #1: High-risk changes (need careful review)
PR #2: Low-risk changes (routine updates)

PR #1: 高风险变更（需要仔细评审）
PR #2: 低风险变更（常规更新）

Exceptions to Size Limits

大小限制例外情况

Generated code (migrations, API clients, types)
Renaming/moving files (show with
```
git mv
```
)
Bulk formatting changes (separate PR, pre-approved)
Third-party library integration (well-documented)

自动生成的代码（迁移文件、API客户端、类型定义）
文件重命名/移动（使用
```
git mv
```
展示）
批量格式调整（单独PR，预先批准）
第三方库集成（文档完善）

Refactoring PRs

重构PR

Refactoring Template

重构模板

markdown

undefined

markdown

undefined

Summary

概要

Refactoring and cleanup for [area]

Goal: Improve code maintainability without changing behavior

[区域]的重构与清理

目标：在不改变行为的前提下提升代码可维护性

Motivation

动机

Reduce code duplication (3 similar functions → 1 reusable utility)
Improve type safety (any → specific types)
Remove dead code identified during feature work

减少代码重复（3个相似函数 → 1个可复用工具）
提升类型安全性（any → 具体类型）
移除功能开发中发现的死代码

Related Tickets

关联工单

ENG-XXX: Improve [area] maintainability
ENG-YYY: Remove deprecated [feature]

ENG-XXX: 提升[区域]可维护性
ENG-YYY: 移除已废弃[功能]

Stats

统计

Lines added: +91
Lines removed: -1,330
Net: -1,239 ✅
Files changed: 23

新增行数：+91
移除行数：-1,330
净变更：-1,239 ✅
变更文件数：23

Changes

变更内容

Removed (Dead Code)

移除（死代码）

```
/api/old-endpoint
```
- unused, replaced by
```
/api/new-endpoint
```
in v2.0
```
useDeprecatedHook.ts
```
- replaced by
```
useNewHook.ts
```
(ENG-234)
```
legacy-utils.ts
```
- functions no longer called anywhere

```
/api/old-endpoint
```
- 未使用，v2.0中已被
```
/api/new-endpoint
```
替代
```
useDeprecatedHook.ts
```
- 被
```
useNewHook.ts
```
替代（ENG-234）
```
legacy-utils.ts
```
- 函数已无任何调用

Refactored

重构

Extracted common logic: Query param parsing now in
```
lib/url-utils.ts
```
Consolidated validation: 3 duplicate Zod schemas → 1 shared schema
Improved types: Replaced 12
```
any
```
types with proper interfaces

提取通用逻辑：查询参数解析现在统一在
```
lib/url-utils.ts
```
中
合并验证规则：3个重复的Zod schema → 1个共享schema
优化类型定义：将12个
```
any
```
类型替换为合适的接口

No Behavior Changes

无行为变更

All tests pass (no test modifications needed)
Same inputs → same outputs
No user-facing changes

所有测试通过（无需修改测试）
相同输入 → 相同输出
无用户可见变更

Testing

测试

Full test suite passes (no new tests needed)
Manual smoke test completed
No regressions identified

完整测试套件通过（无需新增测试）
完成手动冒烟测试
未发现回归问题

Review Focus

评审重点

Verify removed code is truly unused (checked with
```
rg
```
search)
Confirm refactored logic is equivalent
Check no subtle behavior changes introduced

undefined

验证移除的代码确实未被使用（已用
```
rg
```
搜索确认）
确认重构后的逻辑与原逻辑等价
检查是否引入细微的行为变更

undefined

Refactoring Best Practices

重构最佳实践

Separate refactoring from features: Never mix
Verify zero behavior change: Tests should not need updates
Document removed code: Explain why safe to remove
Search thoroughly: Use
```
rg
```
/
```
grep
```
to verify no usage
Celebrate negative LOC: Highlight code reduction

重构与功能分离：切勿混合
确保零行为变更：无需修改测试
记录移除的代码：说明移除的安全性
全面搜索：使用
```
rg
```
/
```
grep
```
验证无调用
肯定代码减少：突出代码量的精简

Review Checklist

评审检查清单

For Authors (Self-Review)

作者自查（自我评审）

Before requesting review, check:

请求评审前，请检查：

Code Quality

代码质量

Testing

测试

Documentation

文档

Complex logic has comments
Public APIs have JSDoc/docstrings
README updated (if setup changed)
Migration guide (if breaking changes)

复杂逻辑已添加注释
公共API已添加JSDoc/文档字符串
必要时已更新README
破坏性变更已提供迁移指南

Performance

性能

No obvious performance issues
Database queries are efficient (indexes considered)
No N+1 queries
Large datasets handled appropriately

无明显性能问题
数据库查询高效（已考虑索引）
无N+1查询问题
已妥善处理大数据集

Security

安全

For Reviewers

评审者指南

First Pass (5 minutes)

初次浏览（5分钟）

Code Review (15-30 minutes)

代码评审（15-30分钟）

Testing Review

测试评审

Documentation Review

文档评审

PR description matches changes
Comments explain "why" not "what"
Breaking changes documented
Migration guide provided (if needed)

PR描述与变更内容一致
注释解释“为什么”而非“是什么”
破坏性变更已记录
必要时已提供迁移指南

Approval Criteria

批准标准

✅ Approve: Code is good, minor nits only
💬 Comment: Suggestions but not blockers
🔄 Request Changes: Issues must be fixed before merge

✅ 批准：代码良好，仅需小调整
💬 评论：提供建议但不阻塞合并
🔄 请求修改：必须修复问题后才能合并

Common Mistakes

常见错误

1. Vague PR Titles

1. PR标题模糊

❌ "Fix bug"
❌ "Updates"
❌ "WIP"
❌ "Changes from code review"

✅ "fix(auth): prevent duplicate login requests"
✅ "feat(cart): add coupon code support"

❌ "修复Bug"
❌ "更新"
❌ "WIP"
❌ "代码评审后的变更"

✅ "fix(auth): prevent duplicate login requests"
✅ "feat(cart): add coupon code support"

2. Missing Context

2. 缺失上下文

❌ "Changed the function"
Why? What was wrong? What's the impact?

✅ "Refactored parseQueryParams to handle nested objects

Previously failed when query params contained dots (e.g., user.name).
Now correctly parses nested structures using qs library.

Fixes ENG-456"

❌ "修改了函数"
为什么修改？原问题是什么？影响是什么？

✅ "Refactored parseQueryParams to handle nested objects

此前当查询参数包含点号（如user.name）时解析失败。
现在使用qs库正确解析嵌套结构。

Fixes ENG-456"

3. Too Large

3. PR过大

❌ 2,000 lines changed across 50 files
❌ "Implement entire authentication system"

✅ Split into:
  - PR #1: Add database schema for auth (150 LOC)
  - PR #2: Implement JWT utilities (100 LOC)
  - PR #3: Create login endpoint (200 LOC)
  - PR #4: Add login UI (250 LOC)

❌ 变更2000行，涉及50个文件
❌ "实现完整认证系统"

✅ 拆分为：
  - PR #1: 添加认证数据库schema（150行）
  - PR #2: 实现JWT工具类（100行）
  - PR #3: 创建登录接口（200行）
  - PR #4: 添加登录UI（250行）

4. Mixed Concerns

4. 混合关注点

❌ Single PR with:
  - Feature implementation
  - Dependency updates
  - Refactoring
  - Bug fixes
  - Formatting changes

✅ Separate PRs:
  - PR #1: feat(feature)
  - PR #2: chore(deps)
  - PR #3: refactor(component)

❌ 单个PR包含：
  - 功能实现
  - 依赖更新
  - 代码重构
  - Bug修复
  - 格式调整

✅ 拆分为独立PR：
  - PR #1: feat(feature)
  - PR #2: chore(deps)
  - PR #3: refactor(component)

5. No Screenshots for UI Changes

5. UI变更无截图

❌ "Updated the header design"
(No screenshots)

✅ "Updated the header design"
[Desktop screenshot]
[Mobile screenshot]
[Before/After comparison]

❌ "更新了头部设计"
（无截图）

✅ "更新了头部设计"
[桌面端截图]
[移动端截图]
[前后对比图]

6. Incomplete Testing Notes

6. 测试说明不完整

❌ "Tested locally"
How? What scenarios? What browsers?

✅ "Testing completed:
- Unit tests: All 47 tests pass
- Manual testing: Tested login flow on Chrome, Firefox, Safari
- Edge cases: Tested expired tokens, invalid credentials, network errors
- Mobile: Verified on iOS Safari and Android Chrome"

❌ "已本地测试"
如何测试？测试了哪些场景？哪些浏览器？

✅ "测试完成：
- 单元测试：全部47个测试通过
- 手动测试：在Chrome、Firefox、Safari上测试了登录流程
- 边界场景：测试了过期令牌、无效凭据、网络错误
- 移动端：在iOS Safari和Android Chrome上验证通过"

7. Leaving Debug Code

7. 残留调试代码

❌ console.log('user data:', user);
❌ debugger;
❌ // TODO: fix this later
❌ import { test } from './test-utils'; (unused)

✅ Clean code without debugging artifacts

❌ console.log('user data:', user);
❌ debugger;
❌ // TODO: fix this later
❌ import { test } from './test-utils'; (未使用)

✅ 代码干净，无调试残留

8. No Changeset (for User-Facing Changes)

8. 用户可见变更未添加Changeset

❌ New feature shipped without changelog entry

✅ .changeset/new-feature.md:
---
"@myapp/web": minor
---

Add OAuth2 login support with Auth0 integration

❌ 新功能已发布但无变更日志条目

✅ .changeset/new-feature.md:
---
"@myapp/web": minor
---

Add OAuth2 login support with Auth0 integration

Summary

总结

Quick Reference

快速参考

PR Title Formula

PR标题公式

{type}({scope}): {clear, concise description}

{type}({scope}): {清晰、简洁的描述}

Ideal PR Characteristics

理想PR特征

Size: < 300 LOC, < 15 files
Focus: Single concern, related changes only
Documentation: Clear description, test plan, screenshots (if UI)
Quality: Self-reviewed, tested, no debugging code
Timeline: Ready to merge, not WIP

大小：< 300行，< 15个文件
聚焦：单一关注点，仅相关变更
文档：描述清晰、包含测试计划、UI变更需附截图
质量：已自我评审、测试通过、无调试代码
状态：可直接合并，非WIP（进行中）状态

Review Mindset

评审心态

As Author:

Make reviewer's job easy
Provide context and reasoning
Test thoroughly before requesting review
Respond promptly to feedback

As Reviewer:

Be constructive and specific
Focus on correctness and maintainability
Ask questions when unclear
Acknowledge good practices

作为作者：

降低评审者的工作难度
提供上下文和决策依据
请求评审前充分测试
及时响应反馈

作为评审者：

给出建设性、具体的意见
关注正确性和可维护性
对不明确的地方提问
认可良好实践

Red Flags

风险信号

🚩 No description or "WIP" title
🚩 Over 500 LOC changed
🚩 Mixed concerns (feature + refactor + deps)
🚩 No tests or only changing tests
🚩 "Trust me, it works"
🚩 Console.log/debugger statements
🚩 TypeScript errors ignored
🚩 No screenshots for UI changes

Use this skill to maintain high PR quality standards and streamline code review processes.

🚩 无描述或标题为"WIP"
🚩 变更行数超过500行
🚩 混合关注点（功能+重构+依赖）
🚩 无测试或仅修改测试
🚩 "相信我，没问题"
🚩 残留console.log/debugger语句
🚩 忽略TypeScript错误
🚩 UI变更无截图

使用本技能来维持高标准的PR质量，优化代码评审流程。