diff --git a/docs/addons/addon-migration-guide.mdx b/docs/addons/addon-migration-guide.mdx index 5616f4e5da0d..0f04e848ff35 100644 --- a/docs/addons/addon-migration-guide.mdx +++ b/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). - 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. ## 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" { diff --git a/docs/api/cli-options.mdx b/docs/api/cli-options.mdx index 3f5e442413f2..92043b63d7af 100644 --- a/docs/api/cli-options.mdx +++ b/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] diff --git a/docs/api/csf/index.mdx b/docs/api/csf/index.mdx index 2f6d6942e454..4534c50c12f3 100644 --- a/docs/api/csf/index.mdx +++ b/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. - 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. 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). diff --git a/docs/configure/integration/frameworks-feature-support.mdx b/docs/configure/integration/frameworks-feature-support.mdx index ceee0d0ed331..7cb43797d5ca 100644 --- a/docs/configure/integration/frameworks-feature-support.mdx +++ b/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.
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.
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. | diff --git a/docs/contribute/index.mdx b/docs/contribute/index.mdx index db8d512ca179..90a52a10b17f 100644 --- a/docs/contribute/index.mdx +++ b/docs/contribute/index.mdx @@ -2,7 +2,7 @@ title: 'How to contribute' hideRendererSelector: true sidebar: - order: 11 + order: 12 title: Contribute --- diff --git a/docs/faq.mdx b/docs/faq.mdx index 1ba0bfd9fa7b..92cd9eeb2c4d 100644 --- a/docs/faq.mdx +++ b/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) | - 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. ## What icons are available for my toolbar or my addon? diff --git a/docs/releases/features.mdx b/docs/releases/features.mdx new file mode 100644 index 000000000000..18f3f9dcb3b4 --- /dev/null +++ b/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). diff --git a/docs/releases/index.mdx b/docs/releases/index.mdx new file mode 100644 index 000000000000..f371a2fd290b --- /dev/null +++ b/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. + + + 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. + + +#### 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. diff --git a/docs/migration-guide/from-older-version.mdx b/docs/releases/migration-guide-from-older-version.mdx similarity index 99% rename from docs/migration-guide/from-older-version.mdx rename to docs/releases/migration-guide-from-older-version.mdx index a3da75f1a9c2..ab9ad03eb9f8 100644 --- a/docs/migration-guide/from-older-version.mdx +++ b/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! **Migrating from Storybook 6.x?** diff --git a/docs/migration-guide/index.mdx b/docs/releases/migration-guide.mdx similarity index 97% rename from docs/migration-guide/index.mdx rename to docs/releases/migration-guide.mdx index 336a9127cb21..b1deb6803f58 100644 --- a/docs/migration-guide/index.mdx +++ b/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! **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. ## 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 diff --git a/docs/contribute/roadmap.mdx b/docs/releases/roadmap.mdx similarity index 99% rename from docs/contribute/roadmap.mdx rename to docs/releases/roadmap.mdx index b419c75cdafc..fd75ab251037 100644 --- a/docs/contribute/roadmap.mdx +++ b/docs/releases/roadmap.mdx @@ -2,7 +2,7 @@ title: 'Roadmap' hideRendererSelector: true sidebar: - order: 6 + order: 5 title: Roadmap --- diff --git a/docs/configure/upgrading.mdx b/docs/releases/upgrading.mdx similarity index 97% rename from docs/configure/upgrading.mdx rename to docs/releases/upgrading.mdx index 6a48d303e013..a77d61fa5f6a 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/releases/upgrading.mdx @@ -1,7 +1,7 @@ --- title: 'Upgrading Storybook' sidebar: - order: 2 + order: 3 title: Upgrading --- @@ -65,7 +65,7 @@ After running the command, the script will: * Detect all Storybook projects in your repository * Upgrade all Storybook packages to the specified version -* Run the relevant [automigrations](../migration-guide/index.mdx#automatic-upgrade) factoring in the [breaking changes](../migration-guide/index.mdx#major-breaking-changes) between your current version and the specified version +* Run the relevant [automigrations](../releases/migration-guide.mdx#automatic-upgrade) factoring in the [breaking changes](../releases/migration-guide.mdx#major-breaking-changes) between your current version and the specified version * Automatically run the [doctor command](#automatic-health-check) to verify the upgrade diff --git a/docs/writing-docs/mdx.mdx b/docs/writing-docs/mdx.mdx index 71485fa6ac52..ab945ee63311 100644 --- a/docs/writing-docs/mdx.mdx +++ b/docs/writing-docs/mdx.mdx @@ -268,7 +268,7 @@ If you run into a situation where Storybook is not able to detect and render the ### The migration seems flaky and keeps failing -By default, running the [migration](../configure/upgrading.mdx) command will prompt you to update the existing MDX files in your project according to the MDX version supported by Storybook. However, this might be a disruptive process, specifically if you're upgrading from a previous version of Storybook where you were using the legacy MDX format. To help you troubleshoot those issues, we've prepared some recommendations that might help you. +By default, running the [migration](../releases/upgrading.mdx) command will prompt you to update the existing MDX files in your project according to the MDX version supported by Storybook. However, this might be a disruptive process, specifically if you're upgrading from a previous version of Storybook where you were using the legacy MDX format. To help you troubleshoot those issues, we've prepared some recommendations that might help you. Start by running the following command inside your project directory: