版本控制策略

本页面介绍我们对 react-native 以及 @react-native 作用域下软件包的版本控制策略。

stable 渠道遵循下述 0.x.y 发布策略，并且每个版本都会经过全面测试——包括手动测试和自动化测试——以确保质量不会下降。我们还会发布 nightly 渠道，以鼓励大家尽早反馈实验性功能。

稳定版发布版本

React Native 会按固定节奏发布稳定版。

我们遵循 0.x.y 版本方案：

稳定版会定期发布，最新版本会在 NPM 上标记为 latest。

同一次版本号下的一系列发布称为一个 次版本系列（例如 0.76.x 是 0.76.0、0.76.1、0.76.2 等的次版本系列）。

你可以在发布概览中详细了解我们对稳定性的承诺。

破坏性变更对所有人来说都很不方便，我们正努力将其尽量减少到最低限度。我们在每个稳定版中发布的所有破坏性变更都会在以下位置突出说明：

对于每一项破坏性变更，我们承诺解释其背后的原因，尽可能提供替代 API，并将对最终用户的影响降到最低。

我们将以下情况视为 React Native 的破坏性变更：

不兼容的 API 变更（即某个 API 被修改或移除，导致你的代码由于该变更而无法再编译/运行）。例如：
- 任何需要你修改代码才能编译通过的 JS/Java/Kotlin/Obj-c/C++ API 变更。
- @react-native/codegen 中不向后兼容的变更。
显著的行为/运行时变更。例如：
- 某个 prop 的布局逻辑发生了剧烈变化。
开发体验上的重大变更。例如：
- 某个调试功能被完全移除。
我们任何传递依赖的重大版本升级。例如：
- 将 React 从 18.x 升级到 19.x
- 将 Android 的 Target SDK 从 34 升级到 35）。
我们支持的平台版本降低。例如：
- 将 Android 的最小 SDK 从 21 升级到 23
- 将 iOS 的最低版本升级到 15.1。

我们不认为以下变更属于破坏性变更：

修改以 unstable_ 前缀开头的 API：这些 API 暴露的是实验性功能，我们对它们最终形态没有把握。通过以 unstable_ 前缀发布它们，我们可以更快迭代，更早得到稳定的 API。
对私有或内部 API 的更改：这些 API 通常以前缀 internal_、private_ 开头，或者位于 internal/ 或 private/ 文件夹/包中。尽管由于工具限制，其中一些 API 可能具有公开可见性，但我们不把它们视为公共 API，因此会在不提前通知的情况下修改它们。
- 同样，如果你访问像 __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED 或 __reactInternalInstance$uk43rzhitjg 这样的内部属性名，也没有任何保证。后果自负。
- 标注为 @FrameworkAPI 的类也被视为内部 API
对工具/开发 API 的更改：React Native 的一些公共 API 是预留给框架和其他工具集成使用的。例如，部分 Metro API 或 React Native DevTools API 预期仅供其他框架或工具使用。对这些 API 的更改会直接与受影响的工具讨论，不视为破坏性变更（我们不会在发布博文中广泛通知）。
开发警告：由于警告不会影响运行时行为，我们可能会在任意版本之间新增警告或修改现有警告。

如果我们预计某项变更会在社区中造成广泛问题，我们仍会尽最大努力为整个生态提供渐进式迁移路径。

随着我们持续开发和演进 React Native，我们会编写新的 API，有时也需要弃用现有 API。这些 API 将经历一个弃用周期。

一旦某个 API 被弃用，它将在后续的多个稳定版中仍然可用。

例如：如果某个 API 在 React Native 0.76.x 中被弃用，它仍会在 0.77.x 中可用，并且不会早于 React Native 0.78.x 被移除。

有时，如果我们认为生态系统需要更多时间来完成迁移，我们会决定让某个已弃用的 API 保留更长时间。对于这些 API，我们通常会提供警告，帮助用户完成迁移。