# 向后兼容性

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

-   破坏范围应尽可能限制在 API 的小部分区域内。
-   应通过开发者说明文档向第三方开发者尽可能清晰地记录破坏性变更。

## 生产环境公共 API 的界定标准

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

-   **生产环境包**：这些包作为 WordPress 脚本发布（例如：wp-components、wp-editor...）。
-   **开发环境包**：这些包由开发者工具组成，可供第三方开发者用于检查、测试、格式化和构建其主题和插件（例如：@wordpress/scrips、@wordpress/env...）。通常，这些包在第三方项目中作为 npm 依赖项使用。

向后兼容性保证仅适用于生产环境包，因为更新是通过 WordPress 升级进行的。

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

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

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

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

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

### 如何保持区块的向后兼容性

-   当编辑器加载时，区块的现有用法不应被破坏或标记为无效。
-   应保证现有区块的样式。
-   标记更改应尽可能限制在最小范围内，但如果区块需要更改其保存的标记，导致先前版本无效，则应添加该区块的[**废弃版本**](/docs/reference-guides/block-api/block-deprecation.md)。

## 类名和 DOM 更新

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

对这些内容的更改应谨慎进行，因为它们可能影响第三方代码的样式和行为（即使它们本不应依赖这些内容）。如果可能，保留旧的类名和 DOM 节点。如果无法保留，请记录更改并撰写开发者说明。

## 废弃

随着项目的发展，现有 API 的缺陷会被发现，或者需要更新以支持新功能。在这种情况下，我们尽量保证现有 API 不被破坏，并构建新的替代 API。

为了鼓励第三方开发者采用新的 API，我们可以使用[**废弃**](/packages/deprecated/README.md)辅助工具来显示一条消息，说明废弃情况并在使用旧 API 时提供替代方案。

明确说明功能何时被废弃。使用辅助方法的 `since` 和 `plugin` 选项。

示例：

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

## 开发者说明

开发者说明是在 WordPress 发布之前[发布在 make/core 网站上的文章](https://make.wordpress.org/core/tag/dev-notes/)，用于向第三方开发者通报开发者 API 的重要变更，这些变更可能包括：

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

### 开发者说明工作流程

-   在处理拉取请求时，如果发现需要开发者说明，请为 PR 添加 **Needs Dev Note** 标签。
-   如果可能，在 PR 中添加评论，说明为什么需要开发者说明。
-   当即将发布的 WordPress 版本的第一个测试版发布时，检查发布中包含的已合并 PR 列表，这些 PR 标记有 **Needs Dev Note** 标签。
-   对于每一个这样的 PR，撰写开发者说明，并与 WordPress 发布负责人协调发布开发者说明。
-   一旦 PR 的开发者说明发布，从 PR 中移除 **Needs Dev Note** 标签。