Docs: Update migration guides #26182

kylegach · 2024-02-24T05:44:00Z

What I did

Add 6 to 8 guide
Account for auto-blockers

Checklist for Contributors

Testing

Manual testing

Follow the steps in the contributing instructions for this branch, migration-guide-updates-2

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts
Make 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/core team 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>

- Add 6 to 8 guide - Account for auto-blockers

- Remove babel breaking change mention

jonniebigodes

Appreciate you taking the time to put this together and so that we can try and unblock users as much as possible during their transition from 6.x to 8. Left some items for you to look into. Let me know once you've addressed them and we'll take it from there.

docs/migration-guide/from-older-version.md

Co-authored-by: jonniebigodes <[email protected]>

- Per: #26201

- Fix typos and small prose improvements

valentinpalkovic · 2024-02-27T09:02:54Z

docs/migration-guide/from-older-version.md

+
+If any of these changes apply to your project, please read through the linked migration notes before continuing.
+
+If any of these new requirements or changes are blockers for your project, we recommend [migrating to Storybook 7](../../release-7-6/docs/migration-guide).


I think this isn't true for Webpack4. As far as I know, we don't have Webpack4 support in Storybook 7.

valentinpalkovic · 2024-02-27T09:04:02Z

docs/migration-guide/from-older-version.md

+### Upgrade MDX1 to MDX3
+
+Storybook 8 uses MDX3 by default for rendering [docs](./writing-docs/index.md). The upgrade from MDX1 to MDX3 is not fully automated due to the large number of changes between versions (particularly v1 to v2). Fortunately, we have some tips to help make it a lot easier.


This is already part of the automigrations. A manual migration afterwards is only necessary if the user declines the automigration. Nevertheless, the whole Upgrade MDX1 to MDX3 section adds so much valuable information that I think it's nice to have it!

valentinpalkovic · 2024-02-27T09:09:07Z

docs/migration-guide/from-older-version.md

+### `storiesOf` to CSF
+
+Storybook architecture focuses on performance and now needs statically analyzable code. For that reason, it does not work with `storiesOf`. We provide a codemod which, in most cases, should automatically make the code changes for you (make sure to update the glob to fit your files):
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-migrate-stories-of-to-csf.npm.js.mdx',
+    'common/storybook-migrate-stories-of-to-csf.pnpm.js.mdx',
+    'common/storybook-migrate-stories-of-to-csf.yarn.js.mdx'
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+This will transform your stories into [CSF 1](/blog/component-story-format/) stories, which are story functions that don't accept [args](../writing-stories/args.md). These are fully supported in Storybook 8, and will continue to be for the foreseeable future.
+
+However, we recommend [writing all **new** stories in CSF 3](../writing-stories/index.md), which are story objects that are easier to write, reuse, and maintain.
+
+### `storiesOf` to dynamically created stories
+
+If you are using `storiesOf` for its ability to create stories dynamically, you can build your own "storiesOf" implementation by leveraging the new [(experimental) indexer API](../api/main-config-indexers). A proof of concept (with a deeper explanation of the implementation) can be seen in [this StackBlitz demo](https://stackblitz.com/edit/github-h2rgfk?file=README.md).


If we detect that the user uses storyStoryV7: false, we block the upgrade to 8. And the storiesOf API ONLY works with storyStoryV6 (storyStoryV7: false). So in theory, the user has to remove storyStoryV7: false to allow the upgrade. In this middle state, Storybook will be broken for user's who continue to use storiesOf in Storybook 6. So they upgrade to Storybook 8 and then they have to run the necessary steps to get rid of the storiesOf API. I just wanted to clarify this.

- Restructure to more accurately provide `storyStoreV7`, `storiesOf`, and MDX 2 guidance

kylegach · 2024-02-27T17:11:31Z

@valentinpalkovic — Thank you for the well-considered feedback! I tried to address your comments here. Mind taking another look?

* next: (39 commits) Typo cleanup Add story for empty argTypes and address review fix issues with types, change the comment to not be jsdoc Add E2E test for multiple CSF files with same title in autodocs Fix overflow bug by using a better link remove deprecation of `manager-api`'s `types` export Don't show empty arg tables in doc pages Fix Yarn2Proxy findInstallations method revert component values back to array done perf(manager): improve performance when switching stories Add todo comment Refactor MDX to CSF transform function to return an object instead of a tuple Rename broken MDX files to .mdx.broken Upgrade migration-guide to mention limitations of mdx-to-csf codemod Fix issues where stories.js files were generated although a story doesn't exist Rename transformed mdx files Add version range for removeLegacyMDX1 fix Fix typo in automigrate/types.ts ...

valentinpalkovic

LGTM!

Update migration guides

a7e4187

- Add 6 to 8 guide - Account for auto-blockers

kylegach added documentation ci:docs Run the CI jobs for documentation checks only. labels Feb 24, 2024

kylegach self-assigned this Feb 24, 2024

jonniebigodes and others added 2 commits February 26, 2024 14:27

Merge branch 'next' into migration-guide-updates-2

3af7219

Update migration guides

10b6e17

- Remove babel breaking change mention

jonniebigodes requested changes Feb 26, 2024

View reviewed changes

kylegach and others added 4 commits February 26, 2024 11:32

Apply suggestions from code review

5853950

Co-authored-by: jonniebigodes <[email protected]>

Remove *.stories.mdx manual migration in 6 -> 8

7e6efff

- Per: #26201

Address comments

0dab452

- Fix typos and small prose improvements

Further prose tweaks

0c44973

valentinpalkovic reviewed Feb 27, 2024

View reviewed changes

Address feedback

5263629

- Restructure to more accurately provide `storyStoreV7`, `storiesOf`, and MDX 2 guidance

valentinpalkovic approved these changes Feb 27, 2024

View reviewed changes

kylegach merged commit 67add2e into next Feb 27, 2024
18 checks passed

kylegach deleted the migration-guide-updates-2 branch February 27, 2024 19:54

github-actions bot mentioned this pull request Feb 27, 2024

Release: Prerelease 8.0.0-beta.6 #26174

Merged

30 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Update migration guides #26182

Docs: Update migration guides #26182

kylegach commented Feb 24, 2024 •

edited

Loading

jonniebigodes left a comment

valentinpalkovic Feb 27, 2024

valentinpalkovic Feb 27, 2024

valentinpalkovic Feb 27, 2024

kylegach commented Feb 27, 2024

valentinpalkovic left a comment


		If any of these changes apply to your project, please read through the linked migration notes before continuing.

		If any of these new requirements or changes are blockers for your project, we recommend [migrating to Storybook 7](../../release-7-6/docs/migration-guide).

		### Upgrade MDX1 to MDX3

		Storybook 8 uses MDX3 by default for rendering [docs](./writing-docs/index.md). The upgrade from MDX1 to MDX3 is not fully automated due to the large number of changes between versions (particularly v1 to v2). Fortunately, we have some tips to help make it a lot easier.

Docs: Update migration guides #26182

Docs: Update migration guides #26182

Conversation

kylegach commented Feb 24, 2024 • edited Loading

What I did

Checklist for Contributors

Testing

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

jonniebigodes left a comment

Choose a reason for hiding this comment

valentinpalkovic Feb 27, 2024

Choose a reason for hiding this comment

valentinpalkovic Feb 27, 2024

Choose a reason for hiding this comment

valentinpalkovic Feb 27, 2024

Choose a reason for hiding this comment

kylegach commented Feb 27, 2024

valentinpalkovic left a comment

Choose a reason for hiding this comment

kylegach commented Feb 24, 2024 •

edited

Loading