企业官网建设流程全解析

Gutenberg 项目 Git 工作流完全指南：从 Fork 到 Pull Request 合并的贡献实战

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg

本篇指南面向想要为 Gutenberg（WordPress 块编辑器项目）贡献代码或文档的开发者，系统讲解该项目官方推荐的 Git 协作流程：从 Fork 仓库、克隆本地、创建分支、提交推送，到提交 Pull Request 并持续保持分支与 fork 最新的完整链路，同时深入介绍 Gutenberg 特有的分支命名规范、rebase 优先策略以及利用.git-blame-ignore-revs文件做高效代码考古（git blame）的实用技巧。读完本文，你将能独立完成一次符合 Gutenberg 社区规范的代码贡献，并理解每一步背后的协作原理。

概览：Gutenberg 的标准贡献流程

Gutenberg 项目采用标准的 GitHub Pull Request 流程进行协作（参见仓库管理文档，了解项目如何使用 GitHub 管理 issues、标签、里程碑与评审）。对贡献者而言，完整流程可以概括为以下步骤：

• Fork Gutenberg 仓库到自己的 GitHub 账号。
• Clone 已 fork 的仓库到本地。
• 创建新分支。
• 修改代码。
• 确认测试通过。
• 在新分支内提交代码变更。
• 将分支推送到 fork 仓库。
• 向 Gutenberg 仓库提交 Pull Request。

代码与文档的贡献流程完全相同，因为两者都由 GitHub 统一管理。建议在动手前先阅读代码贡献入门指南完成本地环境搭建（Node.js v24 + npm v11、Git、可选的 Docker/wp-env 与 GitHub CLI），并参考编码规范与测试总览了解代码风格与质量要求。

完整工作流逐步拆解

Step 1：Fork 仓库

打开 Gutenberg 仓库页面，点击右上角的Fork按钮，GitHub 会在你的账号下创建一份主仓库的副本。这是你个人拥有、可以自由推拉的"工作副本"，后续所有改动都不会直接影响主仓库。

Step 2：Clone fork 仓库到本地

在终端中执行：

git clone https://github.com/YOUR-USER-NAME/gutenberg

该命令会在当前目录下生成一个名为gutenberg的文件夹，包含项目全部文件。由于要下载 Gutenberg 的完整提交历史，克隆可能需要几分钟。

Step 3：创建功能分支

为你的改动创建独立分支（分支命名规范见下文）：

git switch -c update/my-branch

以update/my-branch为例，git switch -c（等价于较老版本的git checkout -b）会创建并切换到新分支。永远不要直接在默认主干分支上做改动——独立分支既能隔离不同功能，也能让后续 rebase 与 PR 更新更干净。

Step 4：修改代码并充分验证

在本地产出代码改动，并按照编码规范与测试总览进行构建与测试。Gutenberg 同时包含 PHP 与 JavaScript 代码，二者都要求测试与 lint：

• 单元测试与代码 lint 可一键执行：npm test；
• 仅执行 lint：npm run lint；
• 部分 JavaScript 问题可自动修复：npm run lint:js:fix；
• 开发模式下npm run dev会随源码变更持续构建，便于边改边验。

Step 5：使用规范的提交信息提交

提交到本地仓库时，请遵循 WordPress 核心手册中的提交信息最佳实践（清晰描述"做了什么、为什么做"）：

git commit -m "Your Good Commit Message" path/to/FILE

也可以不加文件路径直接提交当前暂存的全部改动。git commit只影响你的本地副本，不会触及远端。

Step 6：推送到你的 fork

将分支推送到 GitHub 上的 fork 仓库：

git push -u origin update/my-branch

-u参数会把本地分支与远端分支建立跟踪关系，此后在该分支上直接执行git push即可。

Step 7：创建 Pull Request

推送完成后，打开你 fork 的仓库页面，GitHub 会自动检测到新推送的分支并展示"Compare & pull request"链接。点击后填写 PR 标题与描述，即可向 WordPress 的 Gutenberg 仓库发起合并请求。

Step 8：理解 PR 的本质：一个指向你仓库的指针

请务必理解这一点：Pull Request 本质上是指向你在 fork 仓库中那条分支的一个指针，而不是一份独立的代码副本。因此：

• 后续只需继续往同一条分支推送新提交，PR 会自动同步更新；
• 不要为更新再新建一个 PR——那会产生多个互相孤立的请求。

Step 9：跟进评审，持续迭代

PR 提交后要持续关注新的评审活动。如果评审者要求补充或修改，就在本地按 Step 4～6 修改并推送，PR 会随之自动更新，无需重复创建。一旦 PR 获得批准并合并，你的改动就正式进入主仓库。

分支命名规范

分支名应采用[type]/[change]的形式：一个类型前缀加一段简短描述。Gutenberg 官方建议的前缀如下：

例如分支名add/gallery-block表示你正在为项目新增一个 Gallery 图库区块。

保持分支最新：rebase 优先策略

多人并行开发时，PR 很容易"过期（stale）"。所谓 stale PR，是指它的分支已经落后于主线开发，合并前必须更新。

更新有两种方式：merge（合并）与rebase（变基）。Gutenberg 的官方推荐是rebase：把你的改动"重写"到主线开发历史之上，从而保证提交历史始终干净、线性。PR 存续期间可以按需反复执行 rebase，项目鼓励尽早打开 PR 分享工作，并在推进过程中持续 rebase 保持同步。

项目的主线分支名为trunk。如果 PR 分支因冲突无法直接合并进trunk（长周期 PR 常见），就需要在本地手动解决冲突，然后推送更新。更新 PR 时使用：

git fetch git rebase trunk git push --force-with-lease origin your-branch-name

三步的含义：

• git fetch：拉取仓库远端的最新变更（不修改工作区）；
• git rebase trunk：将当前分支的提交重放到trunk最新提交之上，遇到冲突在此手动解决；
• git push --force-with-lease origin your-branch-name：把变基后的分支推送回 fork。

为什么必须用--force-with-lease而不是裸--force？因为 rebase 重写了提交历史，普通 push 会被拒绝；而裸--force会无条件覆盖远端分支，可能误删他人刚推上来的提交。--force-with-lease只在远端分支与本地记录的一致时才强制推送，从机制上保证你不会意外覆盖别人的工作。

保持 fork 最新：同步 upstream

PR 协作从 fork 开始，而 fork 会随着主仓库不断合入新 PR 而迅速过期。这里引入两个关键术语：你的工作仓库是origin（fork），主 Gutenberg 仓库是upstream。开启新 PR 之前，应当先同步 fork，再创建新分支。

首先添加 upstream 远程：

git remote add upstream https://github.com/WordPress/gutenberg.git git remote -v

输出应类似：

origin git@github.com:your-account/gutenberg.git (fetch) origin git@github.com:your-account/gutenberg.git (push) upstream https://github.com/WordPress/gutenberg.git (fetch) upstream https://github.com/WordPress/gutenberg.git (push)

同步 fork 分两步：先拉取 upstream 变更并合并进本地trunk，再把本地更新推回 fork。

git fetch upstream git checkout trunk git merge upstream/trunk git push

以上命令把本地trunk更新到upstream的最新状态并推送到你的 fork。若要同步其他分支，只需把trunk换成对应分支名。注意这里的git merge用于同步长期分支是合理的——trunk作为同步目标不需要保持"线性重写"。

杂项技巧：Git 考古（Git Archeology）

用 git blame 追踪改动来源

当你想定位"哪个提交引入了这项变更"时，可以借助git blame。不过历史中混有大量纯样式/格式化的提交会干扰定位。幸运的是，较新的 git 版本支持在 blame 时跳过指定提交：

git blame --ignore-rev f63053cace3c02e284f00918e1854284c85b9132 -L 66,73 packages/api-fetch/src/middlewares/media-upload.js

• --ignore-rev：让 blame 忽略单个指定提交；
• -L 66,73：只检查指定文件第 66～73 行的归属。

用 .git-blame-ignore-revs 一次性忽略全部格式化提交

Gutenberg 仓库根目录维护着一个.git-blame-ignore-revs文件，集中登记所有样式与格式化相关提交，可用它一次忽略全部：

git blame --ignore-revs-file .git-blame-ignore-revs -L 66,73 packages/api-fetch/src/middlewares/media-upload.js

查看该文件可发现，它登记的都是这类"纯格式化"提交，例如：

• 4857ad58c1241b3d63d21a6880c989b85746c3dc—— Set line width to 80（统一行宽）
• f63053cace3c02e284f00918e1854284c85b9132—— ESLint updates
• 33d84b036592a5bf31af05b7710f3b2b14163dc4/c56e8a1910ed74f405b74bbb12fe81dea974e5c3/0bee15148fe4330c20cf372cb46a33693e45cb5f—— 多次 Prettier 升级
• 9a34927870df80ac3b2da14d71f81d20ec23e2b6—— ESLint 启用react/jsx-boolean-value
• 5d4baa9ab5f57d207cc3a048003216a8574574d9—— ESLint 启用react/jsx-curly-brace-presence
• 7f43eafccea3691044eabf94e94b978435d25bd3—— Remove dependency import separators

需要说明两点与仓库现状相关的注意点：

1. 上述示例中的packages/api-fetch/src/middlewares/media-upload.js是文档撰写时的路径，当前仓库中该中间件已完成 TypeScript 迁移，实际路径为 packages/api-fetch/src/middlewares/media-upload.ts，其中 65～67 行正是读取上传响应头x-wp-upload-attachment-id以实现失败后清理附件的逻辑。使用时请以仓库当前文件名为准；
2. .git-blame-ignore-revs会随仓库持续更新，新贡献者如提交了纯格式化改动，应保持该文件与仓库同步，勿在本地覆盖。

与仓库协作体系的衔接

本指南是 Gutenberg 贡献文档体系的一部分，以下文件与本主题直接相关，建议串联阅读：

• 仓库管理文档：详细说明 issues 的标签/里程碑/分诊、PR 的代码评审与设计评审、合并与关闭流程。其中合并 PR 的前提条件之一即"已 rebase 到trunk分支最新版本"（与本指南的 rebase 策略一致），最终合并决定由@wordpress/gutenberg-core团队做出；
• 代码贡献入门指南：本地环境搭建（Node.js、Git、wp-env、GitHub CLI）、构建插件、运行本地 WordPress 与 e2e 测试；
• 如何让你的 PR 获得评审：当 PR 迟迟无人评审时的跟进技巧；
• required-changes-from-trunk：当某个合入的改动要求所有在途 PR 更新时的处理方式；
• 编码规范与测试总览：Step 4 中"确认测试通过"的具体执行标准。

结语

Gutenberg 的 Git 工作流并不复杂，关键在于三条纪律：永远在独立分支上工作、用规范前缀命名分支、通过 rebase 保持分支与 fork 同步。其中git push --force-with-lease与.git-blame-ignore-revs是两个容易被忽略但极具价值的细节——前者保护团队协作安全，后者大幅提升代码考古效率。遵循这套流程，你的贡献就能顺利通过评审并合并进这个服务于 WordPress 及更广泛生态的块编辑器项目。

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg