add Releases section and Release Levels doc (#4829)

Author: Simek

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.

docs/releases.md renamed to 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.

website/contributing/versioning-policy.md renamed to 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
 

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',

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',

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