这是一份持续更新的文档，旨在说明我们如何协作管理 Gutenberg 仓库。如果您想提出修改建议，请开启一个 issue 进行讨论或提交针对该文档的 pull request。

本文档涵盖以下内容：

Issues

健康的 issue 列表是指其中的 issue 既相关又可执行。相关是指它们与项目当前的优先级有关。可执行是指清楚需要采取哪些行动来解决该 issue。

任何不相关或不可执行的 issue 都应被关闭，因为它们会阻碍项目的进展。将 issue 列表想象成一张桌子：上面的杂物越多，利用空间完成工作就越困难。

Labels

所有 issues 都应有一个或多个标签。

工作流标签以“Needs”开头，可根据需要应用。理想情况下，每个工作流标签都会有一个跟进的团队，例如 Needs Accessibility Feedback 由无障碍团队负责，Needs Testing 由测试团队负责等。

高优先级和 最高优先级（OMGWTFBBQ）的 issues 应该有负责人和/或处于活跃的里程碑中。

求助请求或“如何使用”类问题应首先发布在相关的支持论坛中。如果某件事可能是 bug 但不确定，支持团队或论坛志愿者可以帮助排查案例，以获取有效 bug 报告所需的所有正确信息。

以下是一些您可能经常看到的标签：

查看标签目录以获取所有标签的列表。

Milestones

我们将 issues 放入里程碑中以更好地分类。Issues 添加到以 WordPress 开头的里程碑中，而 pull requests 添加到以 (Gutenberg) 结尾的里程碑中。

以下是一些您可能看到的里程碑：

分诊 Issues

为了保持 issue 列表的健康，需要定期对其进行分诊。分诊（Triage）是审查现有 issues 以确保它们相关、可执行且拥有所需全部信息的实践。

任何人都可以协助分诊，尽管您需要具有 Gutenberg 仓库的贡献者权限才能修改 issue 的标签或编辑其标题。

详情请参阅分诊贡献者指南。

Pull requests

Gutenberg 对所有代码和文档更改遵循功能分支 pull request 工作流。从高层次来看，流程如下：

  1. 在本地检出新的功能分支。
  2. 进行修改，并进行彻底测试。
  3. 如果您对更改感到满意，则提交更改并推送分支。
  4. 打开您的 pull request。
  5. 如果您是拥有适当访问权限的常规贡献者，请适当地标注和命名您的 pull request（见下文）。

关于拉取请求的标签和命名，以下是使编译变更日志更高效和有序的准则。这些准则对于常规贡献者尤其重要。不要让掌握以下要点成为分享工作的障碍——出错是在意料之中的，而且很容易修复！

  • 在处理实验性屏幕和功能时，请应用 [Type] Experimental 标签，而不是 Feature、Enhancement 等。
  • 在为技术包（scripts, create-block, 添加 react hooks 等）开发新功能时，请应用 [Type] New API 标签，而不是 Feature、Enhancement 等。
  • 在修复项目中使用的内部工具的 bug 或进行增强时，请应用 [Type] Build Tooling，而不是 Bugs、Enhancement 等。
  • 在拉取请求标题中，不要描述为修复 issue 所做的代码更改，而是考虑引用实际正在修复的 bug。例如：与其说“检查组件中的可空对象”，不如说“修复点击复制块按钮时编辑器崩溃的问题”更可取。

除了此流程外，还有几个重要的点需要提及：

  • 非平凡的拉取请求之前应有一个相关的 issue，定义要解决的问题，并在实际编写代码之前允许讨论最合适的解决方案。
  • 为了使合并代码更容易，每个拉取请求应仅包含一个概念上的更改。保持贡献原子化可使拉取请求讨论集中在一个主题上，并使逐个批准更改成为可能。
  • 单独的拉取请求可以解决其关联 issue 中的不同项或待办事项，如果 issue 是非平凡的，单个拉取请求无需覆盖整个 issue。

代码审查

除了自动化测试外，每个拉取请求都要经过手动代码审查。代码审查的目标最好被视为：

  • 正确 — 更改是否做了它应该做的事？
  • 安全 — 恶意方是否会找到利用此更改的方法？
  • 可读 — 几个月后，未来的你还能理解这个更改吗？
  • 优雅 — 更改是否在整体风格和架构中显得美观协调？
  • 利他 — 此更改如何有助于整体大局？

作为审查者，您的反馈应专注于想法而非人。力求理解，保持尊重，并专注于建设性的对话。

作为贡献者，您的责任是从建议中学习，并根据反馈迭代您的拉取请求（如有必要）。力求协作并为整体大局做出最好的贡献。

我们鼓励所有愿意尝试的人都参与代码审查。如果你审查了一个拉取请求并对变更充满信心，请批准它。如果你觉得还没有完全准备好合并，请在评论中指出在最终批准之前还需要其他人再次检查。这有助于过滤掉明显的错误并简化核心成员的审查工作。跟随后续的审查也有助于提高你未来的审查信心。

如果你还不习惯进行完整的审查，可以尝试对 PR 发表评论。关于功能或变更背后原因的提问也很有帮助。你也可以仅针对你理解的代码部分发表评论，而不必进行完整的审查。

如果你在获取审查方面遇到困难，请参阅：如何让你的拉取请求获得审查？

设计审查

如果你的拉取请求影响了设计/UI，你需要添加适当的标签以通知设计团队。要请求设计审查，请将 Needs Design Feedback 标签添加到你的 PR 中。如果有任何 PR 需要更新设计/UI，请使用 Figma Library Update 标签。

作为指南，以下变更应接受审查：

  • 基于先前设计的变更，以确认该设计随变更仍然有效。
  • 任何改变视觉呈现的内容。
  • 如果你只想就某个想法或探索性方案寻求设计反馈。

合并拉取请求

通常，当拉取请求满足以下条件时可以合并：

  • 被认为是对代码库有价值的变更。
  • 符合所有相关的代码审查标准。
  • 必要时已覆盖足够的测试。
  • 已针对所有潜在的边缘情况进行了验证。
  • 已正确添加了 Changelog 条目。
  • 由原始作者以外的人员进行了审查。
  • 已变基（Rebased）到最新的 trunk 分支。

最终的拉取请求合并决定由 @wordpress/gutenberg-core 团队做出。

GitHub 上 WordPress 组织的所有成员都有权审查和合并拉取请求。如果你已经审查了 PR 并对代码有信心，请批准该拉取请求并发表评论提及 @wordpress/gutenberg-core 或参与过该 PR 的特定核心成员。一旦他们确认没有异议，你就可以自由地将 PR 合并到 trunk 中。

大多数拉取请求会被自动分配一个发布里程碑，但请务必确保你合并的拉取请求已被分配。这样做可以创建代码何时落地的历史记录，并使所有项目贡献者（即使是非技术人员）都能访问这些信息。

关闭拉取请求

有时，无论投入多少额外努力，拉取请求可能都无法合并（例如超出范围）。在这些情况下，最好礼貌地与贡献者沟通，说明关闭拉取请求的原因，这将鼓励未来更具成效的贡献。

请确保做到：

  1. 感谢贡献者的时间和精力。
  2. 充分解释关闭拉取请求决策背后的理由。
  3. 尽可能多地链接支持文档。

如果你想遵循一个模板：

感谢 ____ 在这份拉取请求上花费的时间。

我关闭这个拉取请求是因为 ____。为了进一步澄清，____。

更多详细信息，请参阅 ____ 和 ____。

团队

项目中使用了两个 GitHub 团队。

  • Gutenberg Core：由积极参与项目的成员组成的团队：定期参加会议、参与分类会话、定期进行审查、开发功能和修复错误以及执行插件和 npm 版本发布。

  • Gutenberg：由对项目至少有 2–3 次有意义贡献的成员组成的团队。

如果你符合这一标准（即有几次有意义的贡献被接受进入仓库），并希望加入 Gutenberg 团队，欢迎在 #core-editor Slack 频道中提出请求。

项目看板

我们使用 GitHub projects 来跟踪那些目前无法立即采取行动但我们希望保留以供将来参考的细节。