30 Seconds of Code 实战指南：写出高质量 Pull Request 的 5 个技巧-平芜编程栈

教程
文档

【免费下载链接】30-seconds-of-code

Coding articles to level up your development skills

项目地址：https://gitcode.com/gh_mirrors/30/30-seconds-of-code

写出一手好代码只是工作的一半。本文基于 30 Seconds of Code 开源仓库中的 Git 文章合集（content/collections/git/index.yaml）所收录的《5 tips for better Pull Requests》一文，系统讲解「小 PR、好描述、rebase、自查、回应评审」五大实战要点，并结合仓库中对应的 Git 命令速查文章，给出可复制、可运行的命令与完整流程，帮助你写出更容易被评审、更快合入的 Pull Request。

引言：评审体验也是代码质量的一部分

在开源协作中，Pull Request（PR）是代码进入主分支前的最后一道关卡。它不仅是代码变更的载体，更是一份面向评审者的「说明书」。很多人只关注代码本身写得好不好，却忽略了 PR 的呈现方式会直接影响评审效率与最终质量。30 Seconds of Code 仓库的这篇指南（content/snippets/git/s/5-tips-for-better-pull-requests.md）把这个问题浓缩为五个可操作的要点：小 PR、好描述、rebase 到最新、自查、及时回应评审。下面逐一展开，并附上仓库中对应的 Git 命令详解作为延伸。

1. 小 PR：越小越容易被认真评审

The pull requests that get reviewed more thoroughly and confidently and are most often prioritized by developers with limited time are the smallest ones.

时间有限的评审者，往往会优先处理、也更认真细致地审查体积最小的 PR。原文档给出的核心建议是：

按关注点拆分 PR：把「重构」和「新功能实现」这类不同关注点拆到不同的 PR 中，避免一个 PR 混杂多种目的；
保持提交（commit）原子化：每个 commit 只做一件事，便于逐条理解；
提交信息要清晰：让每次变更的目的一眼可读。

拆分一个过大的 commit 的具体做法

如果你在功能分支上已经把多件事塞进了一个 commit，可以利用 Git 的交互式 rebase把提交拆开。仓库中的 split-commit.md 给出了完整的操作流程：

# 1. 启动交互式 rebase，进入待办列表编辑 git rebase -i HEAD~2

# 2. 把要拆分的提交标记为 `edit` edit 3050fc0de Fix network bug pick 7b1e3f2a2 Update README # 3. 保存并关闭编辑器，rebase 会在该提交处暂停

暂停后，把该提交的改动全部从暂存区取回，再按文件分组重新提交：

# 4. 取消暂存该提交的所有改动 git reset HEAD^ # Unstaged changes after reset: # M src/sever/network.js # M src/public/index.html # M package.json # 5. 按逻辑分多次提交 git add src/server/network.js git commit -m 'Fix network bug' git add src/public/index.html git commit -m 'Update documentation' git add package.json git commit -m 'Update dependencies' # 6. 继续完成 rebase git rebase --continue # Successfully rebased and updated refs/heads/network-bug. # 7. 确认提交历史已变得干净清晰 git log --oneline --decorate -4 # 1f3e4d5 (HEAD -> network-bug) Fix network bug # 9a8b7c6 Update documentation # 6d5c4b3 Update dependencies # 7b1e3f2 Update README

注意：交互式 rebase 会重写提交历史，在共享分支上操作务必谨慎（split-commit.md 同样强调了这一点）。

交互式 rebase 的常用动作

拆分 commit 只是交互式 rebase 的一种用法，它还能用于重排、合并、修改提交信息。仓库的 interactive-rebase.md 总结了最常用的动作指令：

p/pick：原样保留该提交；
r/reword：保留提交但修改提交信息；
e/edit：保留提交但暂停以便修改内容；
s/squash：将该提交合并到上一个提交；
d/drop：删除该提交；
f/fixup：类似squash，但丢弃被合并提交的信息；
x/exec：运行一条 shell 命令；
b/break：暂停待修改，之后用git rebase --continue继续。

一个典型的待办列表示例如下：

p c191f90c7 Initial commit # 保留 pick 3050fc0de Fix network bug # 保留 r 7b1e3f2a2 Update README # 修改提交信息 d 3e4f5d6a7 Commit sensitive data # 删除该提交 edit 9a8b7c6d5 Add new feature # 暂停以便修改 f 6d5c4b3a2 Add new feature # 作为 fixup 合并 s 4b3c2d1a0 Update README # 合并到上一个提交

2. 好描述：让评审者读懂你的意图

Always take the time to describe your code and any related tasks in your pull request.

原文档要求你在 PR 中花时间描述代码与相关任务，具体包括：

说明你在实现什么功能或修复什么 Bug；
如适用，附上复现步骤和图片；
记录实现过程中的关键决策、采用的方法；
说明局限性、发现的问题以及评审者理解代码时可能需要的其他要点。

用 Co-authored-by 为协作型提交补充背景

如果你的 PR 是多人协作的产物，可以在提交信息中追加Co-authored-by尾注来标注共同作者。仓库的 github-co-authors.md 给出了写法：

$ git commit -m "Refactor usability tests. > > Co-authored-by: name <name@example.com> Co-authored-by: another-name <another-name@example.com>"

三个注意事项：

必须使用共同作者 GitHub 账号绑定的邮箱，才能正确归属；
如果对方邮箱设置为私密，可使用 GitHub 提供的no-reply邮箱；
在Co-authored-by尾注之前留一行（最好是两行）空行。

3. Rebase 到 master：始终基于最新代码

Always rebase your pull requests onto themasterbranch of the repository.

把 PR 分支始终 rebase 到仓库的master分支，可以带来两个直接收益：

始终针对最新代码做测试，并在本地尽早解决合并冲突，把问题消灭在评审之前；
评审者无需面对已经合并过的功能或修复，从而显著加快评审速度。

rebase 的标准流程

仓库的 rebase-onto-branch.md 给出了完整命令序列：

# Syntax: # git checkout <branch> # git rebase <base-branch> git checkout patch-1 git rebase master # `patch-1` 被 rebase 到 `master` 之上 git checkout patch-2 git fetch origin # 先拉取最新的远端分支 git rebase origin/master # `patch-2` 被 rebase 到最新的远端 `master` 之上

如果过程中出现合并冲突或需要停下来修改，可以随时：

用git rebase --continue解决冲突后继续；
用git rebase --abort中止并恢复到 rebase 之前的状态。

用 fixup 提交保持历史整洁

在 rebase 到 master 的同时，你可能还会根据评审意见修改代码。与其产生大量「fix」提交，不如用fixup 提交配合--autosquash自动归位。仓库的 create-fixup-commit.md 展示了用法：

# 语法：git commit --fixup <commit> git add . git commit --fixup 3050fc0de # 为 `3050fc0de` 创建了一个 fixup 提交 git rebase HEAD~5 --autosquash # 现在 fixup 提交已被自动合并进目标提交

该文还建议为高频操作配置别名（aliases.md 是仓库中关于别名的文章），例如：

git config --global alias.fix 'commit --fixup' # 之后就可以用 `git fix <commit>` 创建 fixup 提交 git add . git fix 3050fc0de

如果嫌手动查 commit hash 麻烦，还可以用fzf做交互式选择：

# 确保已安装 `fzf`（macOS 可 `brew install fzf`） git config --global alias.fixup '!git log -n 50 --pretty=format:"%h %s" --no-merges | fzf | cut -c -7 | xargs -o git commit --fixup' git fixup # 打开最近 50 个提交的列表供选择 # 选定后自动创建 fixup 提交

4. 提交前自查：先当自己的评审者

Before submitting your pull request for review, always take the time to review it yourself.

原文档强调：提交 PR 之前，先以评审者的视角审查自己的代码。这样做的好处包括：

处理「低垂果实」：错别字、简单优化、遗留代码等显而易见的问题；
按评审他人 PR 的标准检查自己的变更；
在自查中审视自己的决策，提前发现哪些决策需要向评审者解释。

自查时常用的两条 Git 命令

自查离不开对改动内容的掌握，仓库中的 view-differences.md 提供了查看改动的命令：

# 语法：git diff [--staged] git diff # 显示未暂存改动与最近一次提交之间的差异 git diff --staged # 显示已暂存改动与最近一次提交之间的差异

如果你负责的分支跨了多个提交，想快速了解「从分支起点到现在都改了什么」，可以用git shortlog生成变更摘要（见 view-changes-summary.md）：

# 语法：git shortlog <commit>..<other-commit> git shortlog 3050fc0de..HEAD # Duck Quacking (2): # Fix network bug # Update documentation git shortlog master..feature-branch # Duck Quacking (2): # Add new feature # Update documentation

两个提交引用不必是连续的，commit hash、分支名、tag 都合法，适合对比历史中的任意两个节点。输出较长时可用方向键滚动、按Q退出。

5. 及时回应评审：讨论、修进、道谢

Set some time aside to respond to reviews after submitting your pull request.

提交 PR 之后，原文档建议你预留时间回应评审：

尽快处理任何力所能及的修改；
必要时发起讨论，共同找到解决方案；
对评审意见产生的修改，使用git commit --fixup追加 fixup 提交，或新增独立提交，方便评审者定位新改动；
假设善意、保持礼貌、感谢同行——评审是协作而非审判。

如何写出「可评审」的提交信息

回应评审时的新提交，同样要遵循清晰的提交信息规范。仓库的 create-commit.md 给出了git commit的基础用法：

# 语法：git commit [-m <message>] git add . git commit -m "Fix the network bug" # 以 "Fix the network bug" 为信息创建提交 git add . git commit # 打开默认文本编辑器输入提交信息

两处值得留意的进阶选项：

git commit --no-verify -m <message>：跳过 pre-commit 与 commit-msg 钩子（通常钩子用于强制编码规范或跑测试，慎用）；
git commit --allow-empty -m <message>：创建不含任何改动的空提交，用于在历史中标记某个时间点。

一个高效的回应评审循环

综合仓库中各篇速查文章，可以串成如下工作流：

收到评审意见后，git checkout <branch>切到 PR 分支；
git fetch origin && git rebase origin/master先同步最新master（rebase-onto-branch.md）；
修改代码后git add . && git commit --fixup <原始提交>创建 fixup 提交（create-fixup-commit.md）；
提交前用git diff/git diff --staged自查改动范围（view-differences.md）；
推送前执行git rebase -i --autosquash <commit>，让 fixup 提交自动归位、保持历史整洁（interactive-rebase.md）。

小结：从「能写代码」到「能被高效合入」

高质量 Pull Request 的本质，是降低评审者的认知成本：用小的变更范围、清晰的描述、最新的基线、自审过的代码和及时的反馈，把评审者从「破译你的意图」中解放出来。这五个技巧在 30 Seconds of Code 的 Git 文章合集（content/collections/git/index.yaml）中均有对应的速查文档支撑——交互式 rebase、fixup 提交、rebase 流程、变更查看、提交规范——掌握它们，你的下一个 PR 将更容易获得认真、高效、愉快的评审体验。