Back to Details

finish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Branch Finishing and PR Preparation

分支收尾与PR准备

Iron Law

铁则

NEVER MERGE WITHOUT ALL CHECKS PASSING
NEVER MERGE WITHOUT ALL CHECKS PASSING

Steps

步骤

1. Verify

1. 验证

Confirm the branch is ready for review.
  • Run the full test suite — all tests must pass
  • Run typecheck and lint — zero errors
  • Verify all acceptance criteria from the story/PRD are met
  • Check for leftover debug code, TODOs, or commented-out blocks
  • Ensure no untracked files that should be committed
确认分支已准备好接受评审。
  • 运行完整测试套件——所有测试必须通过
  • 运行类型检查与代码扫描——零错误
  • 验证需求文档/用户故事中的所有验收标准均已满足
  • 检查是否遗留调试代码、TODO注释或已注释的代码块
  • 确保没有应提交的未跟踪文件

2. Rebase

2. 变基

Bring the branch up to date with the target branch.
bash
git fetch origin
git rebase origin/main
  • Resolve any conflicts carefully — do not blindly accept incoming or current
  • After rebase, re-run all quality checks (tests, typecheck, lint)
  • If rebase conflicts are extensive, consider whether the branch diverged too far
将分支与目标分支同步至最新状态。
bash
git fetch origin
git rebase origin/main
  • 仔细解决冲突——不要盲目接受 incoming 或当前分支的更改
  • 变基后，重新运行所有质量检查（测试、类型检查、代码扫描）
  • 如果变基冲突过多，考虑分支是否偏离目标分支过远

3. Clean History

3. 清理提交历史

Ensure commits tell a clear story.
  • Each commit should be atomic — one logical change per commit
  • Commit messages should explain WHY, not just WHAT
  • Squash fixup commits (typo fixes, lint fixes) into their parent commit
  • Reorder commits so dependencies come before dependents
  • Every commit in the history should pass quality checks independently
确保提交历史清晰易懂。
  • 每个提交应具备原子性——每次提交对应一个逻辑变更
  • 提交信息应说明原因，而非仅描述内容
  • 将修复类提交（如拼写错误、代码扫描修复）合并到其父提交中
  • 调整提交顺序，确保依赖项提交在被依赖项之前
  • 历史中的每个提交都应能独立通过质量检查

4. Write PR Description

4. 撰写PR描述

Create a clear, reviewable pull request description.
  • Title: Concise summary of what the PR does (under 72 characters)
  • Summary: 2-3 sentences explaining the change and its motivation
  • Changes: Bulleted list of what was added, modified, or removed
  • Testing: How the changes were tested, what to verify
  • Screenshots: If UI changes, include before/after
  • Related issues: Link to the story, issue, or PRD that motivated this work
创建清晰、便于评审的拉取请求描述。
  • 标题：简洁总结PR内容（不超过72字符）
  • 概述：2-3句话解释变更内容及其动机
  • 变更点：列出新增、修改或移除的内容（使用项目符号）
  • 测试情况：说明变更的测试方式及需要验证的点
  • 截图：若涉及UI变更，提供前后对比截图
  • 相关关联：链接至驱动本次开发的用户故事、问题或需求文档

5. Self-Review

5. 自审

Review your own diff before requesting review from others.
  • Read every changed line as if someone else wrote it
  • Check for security issues (hardcoded secrets, injection vectors)
  • Check for performance issues (N+1 queries, unbounded loops)
  • Verify error handling is adequate
  • Confirm naming is clear and consistent
在请求他人评审前，先自行检查代码差异。
  • 以旁观者视角阅读每一行变更代码
  • 检查安全问题（硬编码密钥、注入风险）
  • 检查性能问题（N+1查询、无边界循环）
  • 验证错误处理是否完善
  • 确认命名清晰且一致

6. Push and Create PR

6. 推送并创建PR

Push the branch and open the pull request.
bash
git push origin <branch-name>
gh pr create --title "<title>" --body "<description>"
  • Set appropriate reviewers
  • Add relevant labels
  • Link to the related issue or story
  • Do not merge your own PR unless explicitly permitted
推送分支并创建拉取请求。
bash
git push origin <branch-name>
gh pr create --title "<title>" --body "<description>"
  • 设置合适的评审人
  • 添加相关标签
  • 关联相关问题或用户故事
  • 除非明确允许，否则不要合并自己的PR

Red Flags — If You Catch Yourself Thinking:

警示信号——如果你有以下想法：

ThoughtReality
"Tests mostly pass, one flaky test is fine"ALL tests must pass. Fix the flaky test or skip it with documentation.
"The commit history is messy but the code is right"Messy history makes review harder and bisect useless. Clean it up.
"I'll write the PR description later"The PR description IS the review guide. Write it now while context is fresh.
"This is a small change, no need for self-review"Small changes cause big bugs. Review every line.
想法实际情况
"测试大部分通过，一个不稳定的测试没关系"所有测试必须通过。修复不稳定测试或添加文档后再跳过。
"提交历史很乱，但代码是对的"混乱的提交历史会增加评审难度，也会使bisect命令失效。请清理历史。
"我之后再写PR描述"PR描述就是评审指南。趁上下文清晰时立即撰写。
"这是小改动，不需要自审"小改动也会引发大问题。请检查每一行代码。

Rules

规则

  • All quality checks must pass before pushing
  • Every commit must be atomic and independently valid
  • PR description is required — never create a PR without one
  • Self-review before requesting external review
  • Never force-push to a shared branch without coordinating with collaborators
  • 推送前必须通过所有质量检查
  • 每个提交必须具备原子性且独立有效
  • 必须撰写PR描述——禁止创建无描述的PR
  • 请求外部评审前先进行自审
  • 未与协作者沟通前，切勿强制推送到共享分支