From 89cb47edd976d9c280fee9acff9c4d3ff843e1dc Mon Sep 17 00:00:00 2001 From: Simek Date: Wed, 1 Oct 2025 18:25:04 +0200 Subject: [PATCH] add Releases section and Release Levels doc --- docs/releases/release-levels.md | 51 +++++++++++++++++++ docs/{ => releases}/releases.md | 12 ++--- .../releases}/versioning-policy.md | 2 +- website/sidebars.ts | 6 ++- website/sidebarsContributing.ts | 1 - website/static/_redirects | 3 +- 6 files changed, 65 insertions(+), 10 deletions(-) create mode 100644 docs/releases/release-levels.md rename docs/{ => releases}/releases.md (91%) rename {website/contributing => docs/releases}/versioning-policy.md (99%) diff --git a/docs/releases/release-levels.md b/docs/releases/release-levels.md new file mode 100644 index 00000000000..cf1a5120825 --- /dev/null +++ b/docs/releases/release-levels.md @@ -0,0 +1,51 @@ +--- +id: release-levels +title: Release Levels +--- + +React Native provides the community with the ability to adopt individual new features as soon as their design and implementation are nearly complete, even before they are included in a stable release. This approach is known as **release levels**. + +You can configure the release level of React Native so that your React Native instance will initialize with Feature Flags set to either `EXPERIMENTAL`, `CANARY`, or `STABLE` modes. + +:::note +This approach is similar to [Canary and Experimental releases in React](https://react.dev/blog/2023/05/03/react-canaries), but with a key difference: regardless of the release level, the same version of React JS and React Native code is used. +React Native is also not using `@canary` or `@experimental` NPM tags, as release levels are available for both stable and nightly releases of React Native. +::: + +Moreover, setting the release level to `EXPERIMENTAL` or `CANARY` will **not** result in consuming `react@nightly` or `react@canary` due to how react-native is consuming the React version ([you can read more about it here](https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Renderer/README.md#react--react-native-versions)). + +## When to Use Each Release Level + +- **`STABLE`**: + - Use for all production apps and libraries that do not need early access to unreleased features. + - This is the default level for stable and nightly releases. +- **`CANARY`:** + - Use if you are a framework author, advanced app developer, or need to test or adopt new features before they are released in stable. + - Not recommended for production or user-facing applications. +- **`EXPERIMENTAL`:** + - Use only for testing and providing feedback for new features in the early stages of development + - Not recommended for production or user-facing applications. + +## How to initialize React Native using Canary & Experimental + +### Android + +The `DefaultNewArchitectureEntryPoint` class now has a `releaseLevel` property (default: `STABLE`). +The feature flag system uses this property to select the appropriate set of feature flags for the chosen release level. + +```kotlin title="Example usage" +DefaultNewArchitectureEntryPoint.releaseLevel = ReleaseLevel.CANARY +DefaultNewArchitectureEntryPoint.load() +``` + +The build system generates different feature flag override classes for each release level, ensuring the correct features are enabled for each stage. + +### iOS + +The `RCTReactNativeFactory` class now has an initializer that accepts a `releaseLevel` parameter. The feature flag setup uses this parameter to select the correct feature flag overrides. + +```objc title="Example usage" +[[RCTReactNativeFactory alloc] initWithDelegate:delegate releaseLevel:Canary]; +``` + +The system ensures that only one release level is active per app instance, and will crash if multiple factories are created with different release levels. diff --git a/docs/releases.md b/docs/releases/releases.md similarity index 91% rename from docs/releases.md rename to docs/releases/releases.md index c7d465d7f7d..c6a9bb52c6e 100644 --- a/docs/releases.md +++ b/docs/releases/releases.md @@ -1,6 +1,6 @@ --- id: releases -title: Releases +title: Releases Overview --- import ReleasesTable from '@site/src/components/releases/ReleasesTable'; @@ -13,13 +13,13 @@ Below is the schedule and current status of recent and upcoming React Native rel The different support level presented in the table are defined as such: -- Future +- **Future** - After a new version branch gets cut, creating new Release Candidates to allow the community to test the upcoming version is very important. New RC releases are done at a high pace, as soon as viable. -- Active +- **Active** - Stable releases in active support receive frequent updates. Latest stable has the highest priority, and at the start of its stable cycle (right after .0 is released) multiple patches will be done as soon as possible to stabilize the version and ensure a good upgrade experience to the community. -- End of Cycle +- **End of Cycle** - A version in this support bracket will receive less patches, unless some important regressions need to be addressed. Once a next version becomes the new latest stable, before the version in EoC moves over into Unsupported one last patch released will be produced with the latest receive pick requests. -- Unsupported +- **Unsupported** - When a version is in the unsupported stage, no new released are to be expected. Only very important regressions might create exceptions to this rule; it is recommended that codebases using an unsupported version upgrade as soon as possible. ## Commitment to Stability @@ -30,4 +30,4 @@ For those releases we’ll be publishing regular updates and bug fixes. You can read more about our support policy on [the react-native-releases working group](https://github.com/reactwg/react-native-releases/blob/main/docs/support.md). -More information on our versioning, and what we consider a breaking change is available in our [versioning policy](/contributing/versioning-policy) page. +More information on our versioning, and what we consider a breaking change is available in our [versioning policy](./releases/versioning-policy) page. diff --git a/website/contributing/versioning-policy.md b/docs/releases/versioning-policy.md similarity index 99% rename from website/contributing/versioning-policy.md rename to docs/releases/versioning-policy.md index 0a74805437c..1b37c94bdc2 100644 --- a/website/contributing/versioning-policy.md +++ b/docs/releases/versioning-policy.md @@ -26,7 +26,7 @@ Stable releases are shipped regularly, with the latest tagged as `latest` on NPM A series of releases under the same minor number is called a **minor series** (e.g. 0.76.x is the minor series for 0.76.0, 0.76.1, 0.76.2, etc.). -You can read more about our **commitment to stability** in [the releases page](/docs/next/releases). +You can read more about our **commitment to stability** in [the releases page](./). ### Breaking changes diff --git a/website/sidebars.ts b/website/sidebars.ts index dd8be8dbb40..9288c5018ea 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -11,7 +11,6 @@ export default { 'using-a-listview', 'troubleshooting', 'platform-specific-code', - 'releases', 'more-resources', ], 'Environment setup': [ @@ -64,6 +63,11 @@ export default { items: ['accessibility'], }, ], + Releases: [ + 'releases/releases', + 'releases/release-levels', + 'releases/versioning-policy', + ], Debugging: [ 'debugging', 'react-native-devtools', diff --git a/website/sidebarsContributing.ts b/website/sidebarsContributing.ts index f454f372354..cc31b6b452f 100644 --- a/website/sidebarsContributing.ts +++ b/website/sidebarsContributing.ts @@ -9,7 +9,6 @@ export default { collapsible: false, items: [ 'overview', - 'versioning-policy', 'how-to-report-a-bug', 'how-to-contribute-code', 'how-to-build-from-source', diff --git a/website/static/_redirects b/website/static/_redirects index c52ac3b66fb..65b2ea39555 100644 --- a/website/static/_redirects +++ b/website/static/_redirects @@ -18,7 +18,8 @@ /contributing/how-to-contribute /contributing/overview /contributing/how-to-file-an-issue /contributing/how-to-report-a-bug -/releases/release-candidate-minor /releases/release-branch-cut-and-rc0 +/contributing/versioning-policy /docs/next/releases/versioning-policy +/releases/release-candidate-minor /docs/next/releases/versioning-policy # Redirect New Architecture docs of all versions # Note: We had to delete the older versions to get redirects to work