Docs: How we develop features and release Storybook

docs/addons/addon-migration-guide.mdx

@@ -8,12 +8,12 @@ sidebar:
 We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 9.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 8.x to 9.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 8.0](../../../release-8-6/docs/addons/addon-migration-guide.mdx).
 
 <Callout variant="info">
-  As we gather feedback from the community, we'll update this page. We also have a general [Storybook migration guide](../migration-guide/index.mdx) if you're looking for that.
+  As we gather feedback from the community, we'll update this page. We also have a general [Storybook migration guide](../releases/migration-guide.mdx) if you're looking for that.
 </Callout>
 
 ## Replacing dependencies
 
-Many previously-published packages have [moved to be part of Storybook's core](../migration-guide/index.mdx#package-structure-changes). If your addon depends on any of these packages, you should remove them from your `package.json` and update your addon to import from the new location. If your addon does not already depend on the `storybook` package, you should add it to your `package.json` as a dependency.
+Many previously-published packages have [moved to be part of Storybook's core](../releases/migration-guide.mdx#package-structure-changes). If your addon depends on any of these packages, you should remove them from your `package.json` and update your addon to import from the new location. If your addon does not already depend on the `storybook` package, you should add it to your `package.json` as a dependency.
 
 ```diff title="package.json"
 {

docs/api/cli-options.mdx

@@ -170,7 +170,7 @@ Options include:
 
 ### `upgrade`
 
-Upgrades your Storybook instance to the specified version (e.g., `@latest`, `@8`, `@next`). Read more in the [upgrade guide](../configure/upgrading.mdx).
+Upgrades your Storybook instance to the specified version (e.g., `@latest`, `@8`, `@next`). Read more in the [upgrade guide](../releases/upgrading.mdx).
 
 ```shell
 storybook[@version] upgrade [options]
@@ -197,7 +197,7 @@ Options include:
 
 ### `migrate`
 
-Runs the provided codemod to ensure your Storybook project is compatible with the specified version. Read more in the [migration guide](../configure/upgrading.mdx).
+Runs the provided codemod to ensure your Storybook project is compatible with the specified version. Read more in the [migration guide](../releases/upgrading.mdx).
 
 ```shell
 storybook[@version] migrate [codemod] [options]
@@ -226,7 +226,7 @@ Options include:
 
 ### `automigrate`
 
-Perform standard configuration checks to determine if your Storybook project can be automatically migrated to the specified version. Read more in the [migration guide](../configure/upgrading.mdx#automigrate-script).
+Perform standard configuration checks to determine if your Storybook project can be automatically migrated to the specified version. Read more in the [migration guide](../releases/upgrading.mdx#automigrate-script).
 
 ```shell
 storybook[@version] automigrate [fixId] [options]
@@ -252,7 +252,7 @@ Options include:
 
 ### `doctor`
 
-Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when [upgrading](../configure/upgrading.mdx#verifying-the-upgrade) Storybook versions.
+Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when [upgrading](../releases/upgrading.mdx#verifying-the-upgrade) Storybook versions.
 
 ```shell
 storybook doctor [options]

docs/api/csf/index.mdx

@@ -12,7 +12,7 @@ tab:
 Component Story Format (CSF) is the recommended way to [write stories](../../writing-stories/index.mdx). It's an [open standard](https://github.com/ComponentDriven/csf) based on ES6 modules that is portable beyond Storybook.
 
 <Callout variant="info" icon="💡">
-  If you have stories written in the older `storiesOf()` syntax, it was removed in Storybook 8.0 and is no longer maintained. We recommend migrating your stories to CSF. See the [migration guide](../../migration-guide/index.mdx#major-breaking-changes) for more information.
+  If you have stories written in the older `storiesOf()` syntax, it was removed in Storybook 8.0 and is no longer maintained. We recommend migrating your stories to CSF. See the [migration guide](../../releases/migration-guide.mdx#major-breaking-changes) for more information.
 </Callout>
 
 In CSF, stories and component metadata are defined as ES Modules. Every component story file consists of a required [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_the_default_export) and one or more [named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export).

docs/configure/integration/frameworks-feature-support.mdx

@@ -116,5 +116,5 @@ To align the Storybook ecosystem with the current state of frontend development,
 | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | [Knobs](https://github.com/storybookjs/addon-knobs)                                | The Knobs addon was officially deprecated with the release of Storybook 6.3 and is no longer actively maintained. We recommend using the [controls](../../essentials/controls.mdx) instead.                                                                                                                        |
 | Storyshots                                                                         | The Storyshots addon was officially deprecated with the release of Storybook 7.6, is no longer actively maintained and was removed in Storybook 8. See the [migration guide](../../../release-8-6/docs/writing-tests/snapshot-testing/storyshots-migration-guide.mdx) for the available alternatives.                 |
-| StoriesOf                                                                          | The `storiesOf` API was officially removed with the release of Storybook 8 and is no longer maintained. We recommend using the [CSF API](../../api/csf.mdx) instead for writing stories.<br />See the [migration guide](../../migration-guide/from-older-version.mdx#major-breaking-changes) for more information. |
+| StoriesOf                                                                          | The `storiesOf` API was officially removed with the release of Storybook 8 and is no longer maintained. We recommend using the [CSF API](../../api/csf.mdx) instead for writing stories.<br />See the [migration guide](../../releases/migration-guide-from-older-version.mdx#major-breaking-changes) for more information. |
 | Storysource                                                                        | The Storysource addon was officially removed with the release of Storybook 9 and is no longer maintained. To display your stories' source code, we recommend using the [`codePanel`](../../writing-docs/code-panel.mdx) parameter instead.                                                                         |

docs/contribute/index.mdx

@@ -2,7 +2,7 @@
 title: 'How to contribute'
 hideRendererSelector: true
 sidebar:
-  order: 11
+  order: 12
   title: Contribute
 ---
 

docs/faq.mdx

@@ -1,7 +1,7 @@
 ---
 title: 'Frequently Asked Questions'
 sidebar:
-  order: 12
+  order: 13
   title: FAQ
 ---
 
@@ -286,7 +286,7 @@ We're only covering versions 5.3 and 5.0 as they were important milestones for S
 |                  | CLI options                                     | [See current documentation](./api/cli-options.mdx)                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/cli-options)                                                                                                                                   | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/cli-options)                       |
 
 <Callout variant="info">
-  If you have stories written with the older `storiesOf` format, it was removed in Storybook 8.0 and is no longer maintained. We recommend that you migrate your stories to CSF. See the [migration guide](./migration-guide/index.mdx#major-breaking-changes) for more information. However, if you need, you can still access the old `storiesOf` [documentation](https://github.com/storybookjs/storybook/blob/release/5.3/docs/src/pages/formats/storiesof-api/index.md) for reference.
+  If you have stories written with the older `storiesOf` format, it was removed in Storybook 8.0 and is no longer maintained. We recommend that you migrate your stories to CSF. See the [migration guide](./releases/migration-guide.mdx#major-breaking-changes) for more information. However, if you need, you can still access the old `storiesOf` [documentation](https://github.com/storybookjs/storybook/blob/release/5.3/docs/src/pages/formats/storiesof-api/index.md) for reference.
 </Callout>
 
 ## What icons are available for my toolbar or my addon?

docs/releases/features.mdx

@@ -0,0 +1,34 @@
+---
+title: 'Features Lifecycle'
+sidebar:
+  order: 4
+  title: Feature Lifecycle
+---
+
+This page explains how the Storybook team classifies features using four lifecycle labels: **Experimental**, **Preview**, **Stable**, and **Deprecated**.
+
+These labels help users understand our level of commitment, the expected quality, likelihood of breaking changes, and anticipated timeline for each feature. By making this process transparent, we aim to support better adoption decisions and build trust in how Storybook evolves.
+
+### Experimental
+
+This stage marks the beginning of a feature’s development, where we’re validating ideas and shaping direction. 
+
+Experimental features are functional but still evolving, with room for iteration based on real-world use. They’re ideal for trying out in prototypes or early integrations, not yet something to build critical paths around. Each experimental feature comes with an [RFC](https://github.com/storybookjs/storybook/discussions/categories/rfc) where we share the initial idea and report progress. We strongly encourage feedback to help guide the next steps. 
+
+During this stage, we’re committed to fully exploring the concept. As such, specific implementation details may change significantly before stabilization.
+
+### Preview
+
+Preview features are nearly production-ready and generally reliable, with documentation in place and most known issues addressed. They should be fully functional for at least one supported framework, but may still be incomplete or less polished in others. These features are suitable for use in real projects, and we encourage teams to adopt them and share feedback. 
+
+While the feature is stable in direction, we may introduce minimal breaking changes in minor releases to address gaps or refine behavior. In those cases, we provide automigrations where possible to ease the transition. We aim to collect feedback and iterate for 1-2 minor releases before promoting to stable.
+
+### Stable
+
+Stable features are fully supported and safe for production use across all projects. They are well-documented, thoroughly tested in all of our core frameworks, and follow [semantic versioning](https://semver.org). Users can expect long-term support, with any breaking changes reserved for major releases.
+
+### Deprecated
+
+Deprecated features are in the process of being phased out and will be removed in an upcoming major release. Users should begin migrating to supported alternatives as soon as possible. These features no longer receive active development or bug fixes, and their functionality may degrade over time. While they may still work, they should not be used for new development. 
+
+Typically, a deprecated feature is removed within the next major release cycle (for example, if deprecated in 8.x, removal is expected in 9.0).

docs/releases/index.mdx

@@ -0,0 +1,78 @@
+---
+title: 'How we release Storybook'
+sidebar:
+  order: 11
+  title: Releases
+---
+
+Storybook packages ([`storybook`](https://www.npmjs.com/package/storybook) and everything under the [`@storybook` organization](https://www.npmjs.com/org/storybook)) follow [Semantic Versioning](https://semver.org/) (semver). We have a structured release process to ensure stability, compatibility, and a smooth upgrade path for users. This page outlines our release channels, supported versions, and the cadence of major, minor, patch, and pre releases.
+
+## Release Channels
+
+We publish releases on two channels. You can install a specific channel via npm tags:
+
+- **Stable channel** (`latest`): Installs the latest stable release.
+
+```bash
+npm create storybook@latest
+```
+
+- **Pre-release channel** (`next`): Installs the latest [pre-release](#pre-release).
+
+```bash
+npm create storybook@next
+```
+
+## Supported Versions
+
+We actively maintain the latest major version of Storybook. Within the current major, we patch only the latest minor version. Most fixes and new work go into the next minor (or sometimes major) and are not backported. Critical security fixes may be backported more broadly across the current major version, and in rare cases (such as for a short period immediately following a new major), to the previous major.
+
+For example, if the latest version is `9.2.1`:
+
+- We support `9.x.x` versions and release `9.2.x` patch versions
+- Most fixes and new work will be released as `9.3.0-alpha.x` versions
+  - If the next release is a major version, it would be `10.0.0-alpha.x`
+- We will backport critical security fixes to `9.1.x` or `9.0.x`
+- Rarely, we may backport critical fixes to `8.6.x` as necessary
+
+For compatibility with other libraries and tools in the JavaScript ecosystem, please refer to the [compatibility tracker](https://github.com/storybookjs/storybook/issues/23279).
+
+## Release Cycle
+
+#### Major Release
+
+**Cadence**: Roughly once per year
+
+**Channel**: Stable (`latest`)
+
+Major releases introduce breaking changes and significant new features. We use major releases to keep up with ecosystem changes, evolve Storybook’s architecture and APIs, and make the tool faster, leaner, and easier to use. 
+
+Once we start working on a major release, we pause minor releases but continue to ship patch releases as needed. Major releases go through a sequence of [pre-releases](#pre-release)—`alpha`, `beta`, and `rc` (release candidate)—before landing in the stable channel. We aim to include automated migrations and provide [a comprehensive migration guide](../releases/migration-guide.mdx) when manual changes are necessary.
+
+<Callout variant="info">
+  Storybook versions prior to 7 had a very different architecture. As a result, upgrading from v6 to newer versions can be more challenging. Starting in v7, we’ve focused heavily on smoother migrations. Upgrades from v7 to v8, and v8 to v9 (and beyond), should feel significantly easier thanks to automigrations and better tooling.
+</Callout>
+
+#### Minor Release
+
+**Cadence**: Roughly every 8 weeks
+
+**Channel**: Stable (`latest`)
+
+Minor releases deliver new features, enhancements, and non-breaking improvements. Each minor release may be preceded by an alpha [pre-release](#pre-release) (e.g. `x.y.0-alpha`).
+
+#### Patch Release
+
+**Cadence**: as needed (only for the current minor)
+
+**Channel**: Stable (`latest`)
+
+Patch releases include critical bug fixes and security updates. These are issued only for the current minor version and are not pre-released.
+
+#### Pre-release
+
+**Cadence**: Regularly
+
+**Channel**: Pre-release (`next`)
+
+Pre-releases are created to gather early feedback and ensure stability before an official release. Minor version stable releases are preceded by pre-releases with an `alpha` tag (e.g. `x.y.0-alpha`), with no patch pre-releases. Major version stable releases are preceded by a fuller cycle of `alpha`, `beta`, and `rc` pre-releases before the final release.

docs/migration-guide/from-older-version.mdx → docs/releases/migration-guide-from-older-version.mdx

@@ -1,8 +1,8 @@
 ---
-title: 'Migration guide from Storybook 7.x to 8.0'
+title: 'Migration guide from Storybook 7.x to 8.6'
 sidebar:
-  order: 13
-  title: Migrate from 7.x to 8.0
+  order: 2
+  title: Migrate from 7 to 8
 ---
 
 [full-migration-notes]: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800
@@ -18,7 +18,7 @@ Storybook 8 focuses on improving performance, compatibility, and stability. Key
 * ✨ A refreshed desktop UI & mobile UX
 * ➕ Much, much more
 
-This guide is meant to help you **upgrade from Storybook 7.x to 8.0** successfully!
+This guide is meant to help you **upgrade from Storybook 7.x to 8.6** successfully!
 
 <Callout variant="info">
   **Migrating from Storybook 6.x?**

docs/migration-guide/index.mdx → docs/releases/migration-guide.mdx

@@ -1,8 +1,8 @@
 ---
-title: 'Migration guide for Storybook 9.0'
+title: 'Migration guide for Storybook 9'
 sidebar:
-  order: 13
-  title: Migrate to 9.0
+  order: 1
+  title: Migrate to Storybook 9
 ---
 
 [full-migration-notes]: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-8x-to-900
@@ -17,12 +17,12 @@ Storybook 9 improves performance, compatibility, and stability. Its key features
 - ⚛️ React Native for device and web
 - 🏷️ Tags-based story organization
 
-This guide is meant to help you **upgrade from Storybook 8.x to 9.0** successfully!
+This guide is meant to help you **upgrade from Storybook 8.x to 9** successfully!
 
 <Callout variant="info">
   **Migrating from a Storybook version prior to 8?**
 
-  You'll first need to [upgrade to Storybook 8](./from-older-version.mdx). Then you can return to this guide.
+  You'll first need to [upgrade to Storybook 8](./migration-guide-from-older-version.mdx). Then you can return to this guide.
 </Callout>
 
 ## Major breaking changes
@@ -103,7 +103,7 @@ The automatic upgrade should get your Storybook into a working state. If you enc
 
 If you prefer to debug yourself, here are a few useful things you can do to help narrow down the problem:
 
-1. Try removing all addons that are not in the `@storybook` npm namespace (make sure you don't remove the `storybook` package). Community addons that work well with 8.x might not yet be compatible with 9.0, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 9, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!
+1. Try removing all addons that are not in the `@storybook` npm namespace (make sure you don't remove the `storybook` package). Community addons that work well with 8.x might not yet be compatible with 9.x, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 9, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!
 2. Another debugging technique is to bisect to older prerelease versions of Storybook to figure out which release broke your Storybook. For example, assuming that the current prerelease of Storybook is `9.0.0-beta.56`, you could set the version to `9.0.0-alpha.0` in your `package.json` and reinstall to verify that it still works (`alpha.0` should be nearly identical to `8.6.x`). If it works, you could then try `9.0.0-beta.0`, then `9.0.0-beta.28` and so forth. Once you’ve isolated the bad release, read through its [CHANGELOG](https://github.com/storybookjs/storybook/blob/next/CHANGELOG.prerelease.md) entry and perhaps there’s a change that jumps out as the culprit. If you find the problem, please submit an issue or pull request to the Storybook monorepo and we’ll do our best to take care of it quickly.
 
 ## Package structure changes

docs/contribute/roadmap.mdx → docs/releases/roadmap.mdx

@@ -2,7 +2,7 @@
 title: 'Roadmap'
 hideRendererSelector: true
 sidebar:
-  order: 6
+  order: 5
   title: Roadmap
 ---