Docs: Update migration guide for 8.0 #25569
Conversation
kylegach
added
documentation
ci:docs
There was a problem hiding this comment.
@kylegach aware that this is a draft pr which will be updated as we go, but left a couple of items for you to look into when able.
kylegach
force-pushed
the
docs-migration-8
branch
2 times, most recently
from
ea8ada9 to
0f8d085
Compare
|
I foresee people migrating from Storybook 6 to 8 (seems like over 30% of the npm downloads are v6). So what does this PR mean for people who are looking for instructions from 6 to 7? Will they figure out that they need to switch versions in the docs so they get a sidebar entry for the Storybook 7 migration? |
docs/migration-guide.md
Outdated
|
|
||
| If any of these apply to your project, please read through the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) before continuing. If any of these new requirements or changes do not fit your project, you should probably stick with Storybook 6.x. | ||
| If any of these apply to your project, please read through the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800) before continuing. If any of these new requirements or changes do not fit your project, you should probably stick with Storybook 7.x. |
There was a problem hiding this comment.
I'm not sure why these changes necessitate a full read of the migration notes. I'd say that if any of these apply to your project, you should definitely read those sections in detail.
And everybody might benefit from reading the detailed notes before upgrading OR can try to upgrade and consult the detailed notes as they troubleshoot problems.
docs/migration-guide.md
Outdated
| We published a [detailed post about CSF3](https://storybook.js.org/blog/storybook-csf3-is-here/) including all of its benefits and migration steps. | ||
|
|
||
| If you want to just skip to the migration, we provide a codemod for your convenience which should automatically make the code changes for you (make sure to update the glob to fit your files): | ||
| Then, you can optionally convert CSF 2 to CSF 3 ([why should you do this?](https://storybook.js.org/blog/storybook-csf3-is-here/)): |
There was a problem hiding this comment.
Note that storiesOf-to-CSF converts to CSF1. There is no automated transformation from CSF 1 to 2.
There was a problem hiding this comment.
@shilman — Here's what I came up with:
# Convert storiesOf to CSF 1 npx storybook@latest migrate storiesof-to-csf --glob="**/*.stories.tsx" --parser=tsxWhile stories written in CSF 1 are supported in Storybook 8, we recommend upgrading to CSF 3, which has significant benefits when writing and maintaining stories. You'll need to manually migrate your stories to CSF 2, and then you can use the codemod to automatically upgrade from CSF 2 to 3.
I don't love it. 😕 But we don't have any materials that go straight from CSF 1 to 3, and providing a true guide for that (step-by-step, with multiple renderer snippets) would be a ton of effort for a small set of users that will encounter this. Wdyt?
There was a problem hiding this comment.
@kylegach I don't know if there's much value in converting from 1 to 2 and then 2 to 3.
How about something like this:
# Convert storiesOf to CSF 1
npx storybook@latest migrate storiesof-to-csf --glob="**/*.stories.tsx" --parser=tsx
This will create your stories to CSF1 stories, which are story functions that don't accept args. These are fully supported in Storybook 8, and will continue to be for the foreseeable future. However, we recommend writing all new stories in CSF3, which are story objects that are easier to write, reuse, and maintain.
There was a problem hiding this comment.
My thinking was that CSF 1 (no args) to CSF 3 (implicit render functions, stories are objects, etc) would be quite a leap. So easier for the manual part to go to CSF 2, then let the automod handle it.
But I agree that it's weird.
Oh, I just caught the "all new stories" bit of your edit! That works for me. Thanks!
docs/migration-guide.md
Outdated
|
|
||
| ```sh | ||
| npx storybook@latest migrate csf-2-to-3 --glob="src/**/*.stories.js" | ||
| # Convert CSF 2 to CSF 3 |
There was a problem hiding this comment.
You should probably add this in another section, where you give a brief explanation of CSF2 and why you should upgrade. Note that this is an optional migration, since CSF2 is still fully supported (as is CSF1).
kylegach
force-pushed
the
docs-migration-8
branch
from
f01f6fa to
84dab88
Compare
kylegach
force-pushed
the
docs-migration-8
branch
from
84dab88 to
d944bc4
Compare
|
@yannbf —
That's what this section is for!
That link is versioned. 😎 |
Co-authored-by: Yann Braga <[email protected]>
- Clarify neccessity of reading migration notes in full vs. section
- Clarify that `storiesof-to-csf` codemod produces CSF 1
- Add note about recommended upgrade to CSF 3
- Move CSF 2 to 3 upgrade to optional section
- Use existing snippets
- Fix typos
- Improve link URLs
kylegach
force-pushed
the
docs-migration-8
branch
2 times, most recently
from
a202567 to
a755492
Compare
- Update filenames to consistent convention
kylegach
force-pushed
the
docs-migration-8
branch
from
a755492 to
e5e05a1
Compare
What I did
Updated the official migration guide for
8.0Checklist for Contributors
Testing
Manual testing
docs-migration-8Documentation
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/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>