Docs: How we develop features and release Storybook #31662
Conversation
vanessayuenn
changed the title
vanessayuenn
changed the title
vanessayuenn
added
documentation
ci:docs
|
View your CI Pipeline Execution ↗ for commit 3f6a06c.
☁️ Nx Cloud last updated this comment at |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 files reviewed, 3 comments
Edit PR Review Bot Settings | Greptile
docs/releases/features.mdx
Outdated
| title: Feature Lifecycle | ||
| --- | ||
|
|
||
| This page explains how the Storybook team classifies features using three 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. |
There was a problem hiding this comment.
logic: The introduction mentions 'three lifecycle labels' but proceeds to list four stages (Experimental, Preview, Stable, and Deprecated). Update the text to say 'four lifecycle labels' for accuracy.
| This page explains how the Storybook team classifies features using three 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. | |
| 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. |
docs/releases/index.mdx
Outdated
|
|
||
| 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 prereleases —— `alpha`, `beta`, and `rc` (release candidate) —— before landing in the stable channel. We aim to include automated migrations and provide [a comprehensive migration guide](../migration-guide/index.mdx) when manual changes are necessary. |
There was a problem hiding this comment.
style: Double em dash '——' should be a single em dash '—' or double hyphen '--'
| 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 prereleases —— `alpha`, `beta`, and `rc` (release candidate) —— before landing in the stable channel. We aim to include automated migrations and provide [a comprehensive migration guide](../migration-guide/index.mdx) when manual changes are necessary. | |
| 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 prereleases — `alpha`, `beta`, and `rc` (release candidate) — before landing in the stable channel. We aim to include automated migrations and provide [a comprehensive migration guide](../migration-guide/index.mdx) when manual changes are necessary. |
docs/releases/features.mdx
Outdated
| --- | ||
| title: 'Features Lifecycle' | ||
| sidebar: | ||
| order: 13 | ||
| title: Feature Lifecycle | ||
| --- |
There was a problem hiding this comment.
style: The frontmatter title 'Features Lifecycle' and sidebar title 'Feature Lifecycle' are inconsistent. Consider using the same form (plural or singular) for both.
* next: (350 commits) Update CHANGELOG.md for v9.0.9 [skip ci] fix scripts test Next.js: Add styled-jsx to optimize Vite dependencies in configuration Next.js: Update styled-jsx resolution method in Vite configuration Prevent destructuring of undefined Next.js: Enhance Vite configuration with styled-jsx aliasing Next.js: Add webpack alias to resolve Next.js package conflicts dont at-mention users in release PR descriptions cleanup, fix unit tests Angular: Update MiniCssExtractPlugin configuration for cache busting remove unneeded preview entrypoints for core addons relatively import preview annotations of core addons Refactor import statements in find-implicit-spies.ts to consolidate Babel imports Update dependencies in yarn.lock and package.json use babel from core in codemods bundle in giget Bump version from "9.1.0-alpha.5" to "9.1.0-alpha.6" [skip ci] prebundle more in cli-storybook package Write changelog for 9.1.0-alpha.6 [skip ci] fix package manager instance in empty dir flow ...
|
|
||
| ## Supported Versions | ||
|
|
||
| - We only support the **latest major** version of Storybook. |
There was a problem hiding this comment.
@vanessayuenn — Can you clarify what this means, exactly?
Let's say that latest is currently 9.2.1. Is any 9.x.x version supported? Given that there are no breaking changes in the minors, I'd expect only the absolute latest, 9.2.1 to be supported.
There was a problem hiding this comment.
What I meant is: we only provide active maintenance (bug fixes, patches, etc.) for the current major version. So if the latest release is 9.2.1, only 9.2.x is getting patched. Earlier minors like 9.1.x or 9.0.x won’t receive updates unless it’s a critical bug or a critical security fix. But I think this sentence is not conveying what I meant.
How about if we replace this whole section with:
We actively maintain only the latest major version of Storybook (e.g. 9.x).
- Within the current major, we patch only the latest minor (e.g. 9.2.x).
- Most fixes and new work go into the next minor (e.g. 9.3-alpha) and are not backported.
- Critical security fixes may be backported more broadly across 9.x, and in rare cases, to the previous major.
Better?
|
|
||
| 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 |
There was a problem hiding this comment.
@vanessayuenn — Should we add our definitions of "alpha", "beta", and "rc" to this section? And, umm, do we have those? 😅
There was a problem hiding this comment.
We don't have definitions of the different prereleases yet but we were just talking about formalizing them at retro today! We can add that in later when we have consensus.
What I did
Add documentation pages on our feature and release cycles.
Checklist for Contributors
Testing
The changes in this PR are covered in the following automated tests:
Manual testing
Not needed
Documentation
MIGRATION.MD
Checklist for Maintainers
When this PR is ready for testing, make sure to add
ci:normal,ci:mergedorci:dailyGH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found incode/lib/cli-storybook/src/sandbox-templates.tsMake sure this PR contains one of the labels below:
Available labels
bug: Internal changes that fixes incorrect behavior.maintenance: User-facing maintenance tasks.dependencies: Upgrading (sometimes downgrading) dependencies.build: Internal-facing build tooling & test updates. Will not show up in release changelog.cleanup: Minor cleanup style change. Will not show up in release changelog.documentation: Documentation only changes. Will not show up in release changelog.feature request: Introducing a new feature.BREAKING CHANGE: Changes that break compatibility in some way with current major version.other: Changes that don't fit in the above categories.🦋 Canary release
This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the
@storybookjs/coreteam here.core team members can create a canary release here or locally with
gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>Greptile Summary
Added new documentation pages that detail Storybook's feature lifecycle and release processes, providing clearer guidance on versioning strategy and feature maturity stages.
docs/releases/features.mdxdescribing feature lifecycle stages (Experimental, Preview, Stable, Deprecated)docs/releases/index.mdxoutlining versioning strategy and release channels (major, minor, patch, pre-releases)