## 分支命名规范

命名分支时应使用前缀+简短描述的形式，例如：`[类型]/[变更内容]`

推荐使用的前缀：

-   `add/` = 新增功能
-   `try/` = 实验性功能（暂定添加）
-   `update/` = 更新现有功能
-   `remove/` = 移除现有功能
-   `fix/` = 修复现存问题

例如：`add/gallery-block` 表示您正在开发新增画廊区块功能

## 保持分支同步

当多人同时参与项目开发时，拉取请求很容易过时。"过时"的拉取请求是指与主干开发进度脱节的分支，在合并前需要重新同步。

同步方式有两种：合并与变基。在Gutenberg项目中推荐使用变基操作。变基会将您的修改重写为基于开发主线的增量提交，从而确保提交历史的整洁与线性。在处理拉取请求期间，您可以随时执行变基操作。**请尽早开启拉取请求**并持续保持提交历史的变基状态。

开发主线即 `trunk` 分支。当拉取请求分支因冲突无法合并至主干时（长期存续的拉取请求常出现此情况），您需要在变基过程中手动解决本地副本的冲突。具体操作请参阅《如何对拉取请求执行变基》中的[「执行变基」章节](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase)。

本地解决冲突后，可通过 `git push --force-with-lease` 更新拉取请求。使用 `--force-with-lease` 参数至关重要，它能有效避免意外覆盖他人代码。

同步流程可总结为：获取仓库更新 → 基于trunk执行变基 → 推送至远程仓库。具体命令如下：

```sh
git fetch
git rebase trunk
git push --force-with-lease origin 您的分支名称
```

## 维护派生仓库同步

参与拉取请求需先派生Gutenberg仓库作为独立工作副本。随着新代码不断并入主仓库，您的派生仓库容易失去同步。这里您的工作仓库称为 `fork`，主Gutenberg仓库称为 `upstream`。在创建新分支 (`git checkout -b my-new-branch`) 进行功能开发前，请务必先更新派生仓库。

需配置 upstream 远程仓库以保持同步：

```sh
git remote add upstream https://github.com/WordPress/gutenberg.git
git remote -v
origin	git@github.com:您的账户/gutenberg.git (fetch)
origin	git@github.com:您的账户/gutenberg.git (push)
upstream	https://github.com/WordPress/gutenberg.git (fetch)
upstream	https://github.com/WordPress/gutenberg.git (push)
```

同步派生仓库需先获取上游更新并合并至本地：

```sh
git fetch upstream
git checkout trunk
git merge upstream/trunk
```

本地更新完成后，推送至GitHub完成派生仓库更新：

```sh
git push
```

上述命令将更新您的 `trunk` 分支与上游同步。如需更新其他分支，将 `trunk` 替换为对应分支名即可。

## 扩展应用

### 提交追溯

当需要定位引入特定修改的提交时，忽略仅含样式或格式修改的提交会提升效率。

新版 `git` 支持在历史记录中跳过指定提交：

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

Gutenberg仓库通过 `.git-blame-ignore-revs` 文件记录所有样式与格式修订。使用该文件可一次性忽略所有相关提交：

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

# Git 工作流程

本文档旨在帮助您开始使用 Git 与 Gutenberg 进行协作。Git 是一款强大的源代码管理工具；若要深入学习 Git，请查阅基于 CC BY-NC-SA 3.0 许可证免费在线提供的 [Pro Git 书籍](https://git-scm.com/book/zh/v2)。

如果您不熟悉 Git 的使用，值得探索和实践。请尝试 [Git 教程](https://git-scm.com/docs/gittutorial) 以及 [Git 用户手册](https://git-scm.com/docs/user-manual) 来帮助入门。

Gutenberg 项目遵循标准的拉取请求流程进行贡献。有关拉取请求的更多详细信息，请参阅 GitHub 的[相关文档](https://docs.github.com/zh/github/collaborating-with-issues-and-pull-requests)。

## 概述

贡献者的流程概述如下：

-   复刻（Fork）Gutenberg 代码库。
-   克隆复刻后的代码库。
-   创建新分支。
-   进行代码更改。
-   确认测试通过。
-   在新创建的分支中提交代码更改。
-   将分支推送到复刻的代码库。
-   向 Gutenberg 代码库提交拉取请求。

有关 Gutenberg 项目如何使用 GitHub 的更多信息，请参阅[代码库管理文档](/docs/contributors/repository-management.md)。

## Git 工作流程详解

代码和文档的工作流程是相同的，因为两者都在 GitHub 中进行管理。您可以观看[贡献文档的视频详解](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/)以及相应的[贡献给 Gutenberg 的教程](https://mkaz.blog/wordpress/contribute-developer-documentation-to-gutenberg/)。

以下是 Git 工作流程的视觉概览：

![Git 工作流程视觉概览](https://developer.wordpress.org/files/2020/09/git-workflow.png)

**步骤 1**：前往 GitHub 上的 Gutenberg 代码库，点击 Fork。这将在您的账户下创建主 Gutenberg 代码库的副本。

![GitHub 上复刻按钮的截图](https://developer.wordpress.org/files/2020/09/gutenberg-fork.png)

**步骤 2**：在本地克隆您复刻的代码库。其地址为：`https://github.com/您的用户名/gutenberg`。克隆操作会将所有文件复制到您的计算机上。打开终端并运行：

```bash
git clone https://github.com/您的用户名/gutenberg
```

这将创建一个名为 `gutenberg` 的目录，其中包含项目的所有文件。由于需要下载 Gutenberg 项目的完整历史记录，此过程可能需要几分钟。

**步骤 3**：为您的更改创建一个分支（分支命名规则见下文）。在此示例中，分支名称为完整字符串：`update/my-branch`

```bash
git switch -c update/my-branch
```

**步骤 4**：进行代码更改。全面构建、确认并测试您的更改。请参阅[编码指南](/docs/contributors/code/coding-guidelines.md)和[测试概述](/docs/contributors/code/testing-overview.md)以获取指导。

**步骤 5**：使用[良好的提交信息](https://make.wordpress.org/core/handbook/best-practices/commit-messages/)提交您的更改。这会将您的更改提交到本地的代码库副本中。

```bash
git commit -m "您的良好提交信息" 路径/到/文件
```

**步骤 6**：将您的更改推送到 GitHub。更改将被推送到您在 GitHub 上复刻的代码库中。

```bash
git push -u origin update/my-branch
```

**步骤 7**：前往您在 GitHub 上复刻的代码库——它将自动检测到更改，并为您提供创建拉取请求的链接。

![显示拉取请求链接的截图](https://developer.wordpress.org/files/2020/09/pull-request-create.png)

**步骤 8**：创建拉取请求。这将在 WordPress Gutenberg 代码库上创建请求，以集成来自您复刻代码库的更改。

**步骤 9**：关注拉取请求上的新动态。如果要求进行任何额外的更改或更新，请在本地进行更改并按照步骤 4-6 推送它们。

请勿为更新创建新的拉取请求；通过将更改推送到您的代码库，它将更新同一个 PR。从这个意义上说，PR 是 WordPress Gutenberg 代码库指向您副本的指针。因此，当您更新副本时，PR 也会相应更新。

就是这样！一旦获得批准并合并，您的更改将被纳入主代码库。🎉