Back to Details

pr-creation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Creation

PR 创建

Overview

概述

Create pull requests with complete documentation and proper linking.
Core principle: A PR should tell the complete story of the change.
Announce at start: "I'm creating a PR with complete documentation."
创建包含完整文档和正确关联的PR。
核心原则：一个PR应完整说明本次变更的来龙去脉。
开始时告知：“我正在创建一份包含完整文档的PR。”

Before Creating PR

创建PR前的准备

Verify these prerequisites:
  • All tests pass locally
  • Build succeeds locally
  • Code review complete (
    comprehensive-review
    )
  • All findings addressed (
    apply-all-findings
    )
  • Commits are clean and atomic (
    clean-commits
    )
  • Branch is up to date with target
确认以下前提条件已满足：
  • 所有本地测试通过
  • 本地构建成功
  • 代码评审完成（
    comprehensive-review
    ）
  • 所有评审意见已处理（
    apply-all-findings
    ）
  • 提交记录清晰且原子化（
    clean-commits
    ）
  • 分支已与目标分支同步

Ensure Branch is Current

确保分支为最新状态

bash
undefined
bash
undefined

Fetch latest

获取最新代码

git fetch origin
git fetch origin

Rebase on target (usually main)

基于目标分支（通常为main）变基

git rebase origin/main
git rebase origin/main

Or merge if preferred

或者使用合并（若偏好此方式）

git merge origin/main
git merge origin/main

Resolve any conflicts

解决任何冲突

Push updated branch

推送更新后的分支

git push --force-with-lease # Safe force push after rebase
undefined
git push --force-with-lease # 变基后安全的强制推送
undefined

PR Documentation Structure

PR文档结构

Title

标题

Format: 
[Type] Brief description (#issue)
feat: Add user authentication (#123)
fix: Resolve session timeout loop (#456)
refactor: Extract validation middleware (#789)
docs: Update API documentation (#101)
chore: Update dependencies (#202)
格式：
[类型] 简要描述（#议题编号）
feat: 添加用户认证功能 (#123)
fix: 修复会话超时循环问题 (#456)
refactor: 提取验证中间件 (#789)
docs: 更新API文档 (#101)
chore: 更新依赖包 (#202)

Body Template

正文模板

markdown
undefined
markdown
undefined

Summary

总结

[2-3 sentences describing what this PR does and why]
[用2-3句话说明本PR的内容及原因]

Changes

变更内容

  • [Bullet point of key change 1]
  • [Bullet point of key change 2]
  • [Bullet point of key change 3]
  • [关键变更点1]
  • [关键变更点2]
  • [关键变更点3]

Related Issues

关联议题

Closes #[ISSUE_NUMBER]
<!-- If multiple issues -->
Relates to #[OTHER_ISSUE] Depends on #[DEPENDENCY_PR]
Closes #[议题编号]
<!-- 若有多个议题 -->
Relates to #[其他议题编号] Depends on #[依赖的PR编号]

Verification

验证

Automated Tests

自动化测试

  • Unit tests pass
  • Integration tests pass
  • E2E tests pass (if applicable)
  • 单元测试通过
  • 集成测试通过
  • E2E测试通过（如适用）

Manual Verification

手动验证

  • [Criterion 1 from acceptance criteria]
  • [Criterion 2 from acceptance criteria]
  • [Criterion 3 from acceptance criteria]
  • [验收标准中的准则1]
  • [验收标准中的准则2]
  • [验收标准中的准则3]

Screenshots (if UI changes)

截图（若有UI变更）

BeforeAfter
beforeafter
变更前变更后
beforeafter

Checklist

检查清单

  • Tests added/updated
  • Documentation updated
  • Types are complete (no 
    any
    )
  • Code follows style guide
  • Self-review completed
  • 已添加/更新测试
  • 已更新文档
  • 类型定义完整（无
    any
    类型）
  • 代码符合风格指南
  • 已完成自评审

Notes for Reviewers

评审人员注意事项

[Any special considerations, areas to focus on, or context]
undefined
[任何需要特别注意的事项、重点关注区域或上下文信息]
undefined

Creating the PR

创建PR

Using GitHub CLI

使用GitHub CLI

bash
undefined
bash
undefined

Create PR with full body

创建包含完整正文的PR

gh pr create
--title "feat: Add user authentication (#123)"
--body "$(cat <<'EOF'
gh pr create
--title "feat: Add user authentication (#123)"
--body "$(cat <<'EOF'

Summary

Summary

Implements user authentication with JWT tokens and session management. Adds login, logout, and protected route middleware.
Implements user authentication with JWT tokens and session management. Adds login, logout, and protected route middleware.

Changes

Changes

  • Add authentication service with JWT signing
  • Add login and logout endpoints
  • Add authentication middleware for protected routes
  • Add session management with Redis
  • Add authentication service with JWT signing
  • Add login and logout endpoints
  • Add authentication middleware for protected routes
  • Add session management with Redis

Related Issues

Related Issues

Closes #123
Closes #123

Verification

Verification

Automated Tests

Automated Tests

  • Unit tests pass (47 new tests)
  • Integration tests pass
  • E2E tests pass
  • Unit tests pass (47 new tests)
  • Integration tests pass
  • E2E tests pass

Manual Verification

Manual Verification

  • User can log in with valid credentials
  • Invalid credentials show error message
  • Session persists across page refreshes
  • Logout clears session
  • User can log in with valid credentials
  • Invalid credentials show error message
  • Session persists across page refreshes
  • Logout clears session

Checklist

Checklist

  • Tests added/updated
  • Documentation updated
  • Types are complete
  • Code follows style guide
  • Self-review completed EOF )"
    --base main
    --head feature/issue-123-user-authentication
undefined
  • Tests added/updated
  • Documentation updated
  • Types are complete
  • Code follows style guide
  • Self-review completed EOF )"
    --base main
    --head feature/issue-123-user-authentication
undefined

Adding Labels

添加标签

bash
undefined
bash
undefined

Add labels after creation

创建后添加标签

gh pr edit [PR_NUMBER] --add-label "feature,needs-review"
gh pr edit [PR_NUMBER] --add-label "feature,needs-review"

Or during creation

或者在创建时添加

gh pr create ... --label "feature" --label "needs-review"
undefined
gh pr create ... --label "feature" --label "needs-review"
undefined

Adding Reviewers

添加评审人员

bash
undefined
bash
undefined

Request reviewers

请求评审人员

gh pr edit [PR_NUMBER] --add-reviewer username1,username2
gh pr edit [PR_NUMBER] --add-reviewer username1,username2

Or during creation

或者在创建时指定

gh pr create ... --reviewer username1
undefined
gh pr create ... --reviewer username1
undefined

Linking Issues

关联议题

Automatic Linking

自动关联

Use keywords in PR body:
markdown
Closes #123        # Closes issue when PR merges
Fixes #123         # Same as closes
Resolves #123      # Same as closes
Relates to #456    # Links but doesn't close
Depends on #789    # Links to dependency
在PR正文中使用关键词：
markdown
Closes #123        # PR合并时自动关闭议题
Fixes #123         # 与Closes功能相同
Resolves #123      # 与Closes功能相同
Relates to #456    # 仅关联但不关闭议题
Depends on #789    # 关联依赖的PR

Multiple Issues

多个议题

markdown
undefined
markdown
undefined

Related Issues

关联议题

Closes #123, closes #124 Relates to #200
<!-- Or one per line -->
Closes #123 Closes #124 Relates to #200
undefined
Closes #123, closes #124 Relates to #200
<!-- 或者每行一个 -->
Closes #123 Closes #124 Relates to #200
undefined

Verification Summary

验证总结

Include verification results from 
acceptance-criteria-verification
:
markdown
undefined
包含来自
acceptance-criteria-verification
的验证结果：
markdown
undefined

Verification

验证

Test Results

测试结果

SuiteStatusCoverage
Unit47/47 passing98%
Integration12/12 passingN/A
E2E5/5 passingN/A
测试套件状态覆盖率
单元测试47/47 通过98%
集成测试12/12 通过N/A
E2E测试5/5 通过N/A

Acceptance Criteria

验收标准

#CriterionStatus
1User can log inPASS
2Invalid credentials show errorPASS
3Session persistsPASS
4Logout clears sessionPASS
Full verification report: [Link to issue comment]
undefined
编号准则状态
1用户可登录PASS
2无效凭证显示错误提示PASS
3会话可持久化PASS
4登出可清除会话PASS
完整验证报告：[关联到议题评论的链接]
undefined

Special Cases

特殊情况

Draft PRs

草稿PR

For work-in-progress or early feedback:
bash
gh pr create --draft \
  --title "WIP: Add user authentication (#123)" \
  --body "..."
Convert to ready when complete:
bash
gh pr ready [PR_NUMBER]
适用于正在进行中的工作或需要早期反馈的场景：
bash
gh pr create --draft \
  --title "WIP: Add user authentication (#123)" \
  --body "..."
完成后转换为正式PR：
bash
gh pr ready [PR_NUMBER]

Breaking Changes

破坏性变更

Highlight breaking changes prominently:
markdown
undefined
突出显示破坏性变更：
markdown
undefined

Breaking Changes

破坏性变更

:warning: This PR contains breaking changes:
  • AuthService.login()
    now returns 
    Promise<Session>
    instead of 
    Promise<User>
  • The 
    session
    cookie name changed from 
    sid
    to 
    session_id
  • Removed deprecated 
    authenticate()
    function
:warning: 本PR包含破坏性变更：
  • AuthService.login()
    现在返回
    Promise<Session>
    而非
    Promise<User>
  • session
    Cookie名称从
    sid
    改为
    session_id
  • 已移除已废弃的
    authenticate()
    函数

Migration Guide

迁移指南

  1. Update all calls to 
    login()
    to handle new return type
  2. Update cookie configuration if hardcoded
  3. Replace 
    authenticate()
    with 
    validateSession()
undefined
  1. 更新所有
    login()
    调用以处理新的返回类型
  2. 若Cookie配置为硬编码，需更新配置
  3. 用
    validateSession()
    替换
    authenticate()
undefined

Large PRs

大型PR

If PR is large, help reviewers:
markdown
undefined
如果PR内容较大，为评审人员提供指引：
markdown
undefined

Review Guide

评审指南

This PR is large. Suggested review order:
  1. Start with 
    src/services/auth.ts
    (core logic)
  2. Then 
    src/middleware/authenticate.ts
    (integration)
  3. Then 
    src/routes/auth.ts
    (API surface)
  4. Finally tests in 
    tests/auth/
本PR内容较大，建议评审顺序：
  1. 先查看
    src/services/auth.ts
    （核心逻辑）
  2. 然后查看
    src/middleware/authenticate.ts
    （集成部分）
  3. 接着查看
    src/routes/auth.ts
    （API接口）
  4. 最后查看
    tests/auth/
    中的测试代码

Files by Category

文件分类

Core Changes:
  • src/services/auth.ts
  • src/models/session.ts
Integration:
  • src/middleware/authenticate.ts
API:
  • src/routes/auth.ts
Tests:
  • tests/auth/*.test.ts
undefined
核心变更：
  • src/services/auth.ts
  • src/models/session.ts
集成部分：
  • src/middleware/authenticate.ts
API接口：
  • src/routes/auth.ts
测试代码：
  • tests/auth/*.test.ts
undefined

After Creation

创建后的操作

Monitor Status

监控状态

bash
undefined
bash
undefined

Check PR status

查看PR状态

gh pr view [PR_NUMBER]
gh pr view [PR_NUMBER]

Check CI status

查看CI状态

gh pr checks [PR_NUMBER]
undefined
gh pr checks [PR_NUMBER]
undefined

Respond to Feedback

回应反馈

When reviewers comment:
  1. Address all feedback
  2. Push fixes
  3. Re-request review if significant changes
  4. Mark conversations as resolved
当评审人员提出意见时：
  1. 处理所有反馈内容
  2. 推送修复后的代码
  3. 若有重大变更，重新请求评审
  4. 将已处理的对话标记为已解决

Checklist

检查清单

Before creating PR:
  • All tests pass locally
  • Build succeeds
  • Branch is current with target
  • Commits are clean
PR content:
  • Clear, descriptive title
  • Summary explains what and why
  • Changes listed
  • Issue linked (Closes #X)
  • Verification results included
  • Checklist completed
  • Labels applied
  • Reviewers assigned (if required)
创建PR前：
  • 所有本地测试通过
  • 构建成功
  • 分支已与目标分支同步
  • 提交记录清晰
PR内容：
  • 清晰、描述性的标题
  • 总结部分说明变更内容及原因
  • 列出所有关键变更
  • 已关联议题（Closes #X）
  • 包含验证结果
  • 完成检查清单
  • 已添加标签
  • 已指定评审人员（若需要）

Integration

集成

This skill is called by:
  • issue-driven-development
    - Step 12
This skill follows:
  • comprehensive-review
    - Review complete
  • apply-all-findings
    - Findings addressed
  • clean-commits
    - Commits ready
This skill precedes:
  • ci-monitoring
    - Monitor CI results
本技能由以下流程调用：
  • issue-driven-development
    - 第12步
本技能需在完成以下流程后执行：
  • comprehensive-review
    - 评审已完成
  • apply-all-findings
    - 评审意见已处理
  • clean-commits
    - 提交记录已准备就绪
本技能执行后将进入：
  • ci-monitoring
    - 监控CI结果