155 lines
7.4 KiB
Markdown
155 lines
7.4 KiB
Markdown
## 分支命名规范
|
||
|
||
命名分支时应使用前缀+简短描述的形式，例如：`[类型]/[变更内容]`
|
||
|
||
推荐使用的前缀：
|
||
|
||
- `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 工作流程的视觉概览：
|
||
|
||
|
||
|
||
**步骤 1**：前往 GitHub 上的 Gutenberg 代码库，点击 Fork。这将在您的账户下创建主 Gutenberg 代码库的副本。
|
||
|
||
|
||
|
||
**步骤 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 上复刻的代码库——它将自动检测到更改，并为您提供创建拉取请求的链接。
|
||
|
||
|
||
|
||
**步骤 8**：创建拉取请求。这将在 WordPress Gutenberg 代码库上创建请求，以集成来自您复刻代码库的更改。
|
||
|
||
**步骤 9**：关注拉取请求上的新动态。如果要求进行任何额外的更改或更新，请在本地进行更改并按照步骤 4-6 推送它们。
|
||
|
||
请勿为更新创建新的拉取请求；通过将更改推送到您的代码库，它将更新同一个 PR。从这个意义上说，PR 是 WordPress Gutenberg 代码库指向您副本的指针。因此，当您更新副本时，PR 也会相应更新。
|
||
|
||
就是这样！一旦获得批准并合并，您的更改将被纳入主代码库。🎉 |