从历史上看，WordPress 以跨版本保持向后兼容性而闻名。Gutenberg 在其生产环境公共 API 中尽可能遵循这一惯例。在极少数情况下，破坏向后兼容性是不可避免的，在这些情况下：

  • 应将影响范围尽可能限制在 API 的一小部分区域。
  • 应通过 Dev Notes（开发说明）尽可能清晰地向第三方开发者记录这些变更。

什么属于生产环境公共 API

Gutenberg 代码库由两种不同类型的包组成：

  • 生产包（production packages）：这些包作为 WordPress 脚本发布（例如：wp-components、wp-editor……）。
  • 开发包（development packages）：这些包由开发者工具组成，可供第三方开发者用于对其主题和插件进行 linting（静态检查）、测试、格式化和构建（例如：@wordpress/scripts、@wordpress/env……）。通常，这些包作为 npm 依赖项被第三方项目使用。

向后兼容性保证仅适用于生产包，因为更新是通过升级 WordPress 来完成的。

生产包使用 wp 全局变量向第三方开发者提供 API。这些 API 可以是 JavaScript 函数、变量和 React 组件。

如何为 JavaScript 函数保持向后兼容性

  • 函数的名称不应更改。
  • 函数参数的顺序不应更改。
  • 函数返回值的类型不应更改。
  • 如果对参数进行修改（新增参数、语义修改），只要确保所有以前的调用仍然可行即可。

如何为 React 组件保持向后兼容性

  • 组件的名称不应更改。
  • 不应移除组件的 props。
  • 现有的 prop 值应继续得到支持。如果组件接受一个函数作为 prop，我们可以更新组件以接受同一 prop 的新类型，但这不应破坏现有用法。
  • 允许添加新的 props。
  • 只有在确保不破坏之前的上下文契约的情况下，才能添加或移除 React Context 依赖。

如何为一个区块（Block）保持向后兼容性

  • 当编辑器加载时，该区块的现有用法不应中断或被标记为无效。
  • 应保证现有区块的样式不受影响。
  • Markup（标记语言）的变化应限制在最小范围内，但如果某个区块需要改变其保存的 markup，导致以前版本的区块失效，则应添加该区块的废弃版本（deprecated version）。

类名和 DOM 更新

React 组件树内部使用的类名和 DOM 节点不被视为公共 API 的一部分，因此可以进行修改。

对这些内容的修改应谨慎行事，因为这可能会影响第三方代码的样式和行为（尽管它们最初就不应依赖于这些内容）。如果可能，请保留旧的类名/DOM 结构。如果不保留，请记录这些变化并编写一篇 dev note。

弃用（Deprecations）

随着项目的演进，我们会发现现有 API 的缺陷，或者需要进行更新以支持新功能。发生这种情况时，我们尽量保证现有 API 不会中断，并构建新的替代 API。

为了鼓励第三方开发者采用新 API，我们可以使用deprecated 辅助函数，在旧 API 被使用时显示一条消息，解释弃用原因并提出替代方案。

更清晰地标明功能是何时被弃用的。请使用辅助方法的 since 和 plugin 选项。

示例：

deprecated( 'wp.components.ClipboardButton', {
    since: '10.3',
    plugin: 'Gutenberg',
    alternative: 'wp.compose.useCopyToClipboard',
} );

Dev notes（开发说明）

Dev notes 是在 WordPress 发布之前发布在 make/core 网站上的文章，旨在通知第三方开发者关于开发者 API 的重要变更，这些变更可能包括：

  • 新的 API。
  • 可能影响现有插件和主题的现有 API 变更。（例如：类名变更……）
  • 不可避免的向后兼容性破坏，附带理由和迁移流程。
  • 重要的弃用操作（即使没有造成破坏），附带理由和迁移流程。

Dev note 工作流程

  • 在处理拉取请求（pull request）时，如果发现需要撰写 dev note，请为该 PR 添加 Needs Dev Note 标签。
  • 如果可能，请在 PR 中添加评论，解释为何需要这篇 dev note。
  • 当即将发布的 WordPress 第一个 beta 版推出后，遍历该版本中包含的已合并 PR 列表，筛选出带有 Needs Dev Note 标签的 PR。
  • 针对每一个这样的 PR，撰写一篇 dev note，并与 WordPress 发布负责人协调以发布该 dev note。
  • 一旦某 PR 的 dev note 发布完毕，请从该 PR 上移除 Needs Dev Note 标签。