3.0.0 migration assistance : codemod, update installation and usage instructions

MIGRATION.md

@@ -0,0 +1,87 @@
+# Migration
+
+## Table of contents
+
+-   [from version 2.x.x to 3.x.x](#from-version-2xx-to-3xx)
+    -   [Webpack upgrade](#webpack-upgrade)
+    -   [Packages renaming](#packages-renaming)
+    -   [Deprecated embedded addons](#deprecated-embedded-addons)
+
+## from version 2.x.x to 3.x.x
+
+This major release is mainly an internal restructuring.
+Upgrading requires work on behalf of users, this was unavoidable.
+We're sorry if this inconveniences you, we have tried via this document and provided tools to make the process as easy as possible.
+
+### Webpack upgrade
+
+Storybook will now use webpack 2 (and only webpack 2).
+If you are using a custom `webpack.config.js` you need to change this to be compatible.
+You can find the guide to upgrading your webpack config [on webpack.js.org](https://webpack.js.org/guides/migrating/).
+
+### Packages renaming
+
+All our packages have been renamed and published to npm as version 3.0.0.
+
+> We have adopted the same versioning strategy as have been adopted by babel, jest and apollo.
+> It's a strategy best suited for ecosystem type tools, which consist of many seperately installable features / packages.
+> We think this describes storybook pretty well.
+
+The new package names are:
+
+| old                                          | new                              |
+| -------------------------------------------- | -------------------------------- |
+| `getstorybook`                               | `@storybook/cli`                 |
+| `@kadira/getstorybook`                       | `@storybook/cli`                 |
+|                                              |                                  |
+| `@kadira/storybook`                          | `@storybook/react`               |
+| `@kadira/react-storybook`                    | `@storybook/react`               |
+| `@kadira/react-native-storybook`             | `@storybook/react-native`        |
+|                                              |                                  |
+| `storyshots`                                 | `@storybook/addon-storyshots`    |
+| `@kadira/storyshots`                         | `@storybook/addon-storyshots`    |
+|                                              |                                  |
+| `@kadira/storybook-ui`                       | `@storybook/ui`                  |
+| `@kadira/storybook-addons`                   | `@storybook/addons`              |
+| `@kadira/storybook-channels`                 | `@storybook/channels`            |
+| `@kadira/storybook-channel-postmsg`          | `@storybook/channel-postmessage` |
+| `@kadira/storybook-channel-websocket`        | `@storybook/channel-websocket`   |
+|                                              |                                  |
+| `@kadira/storybook-addon-actions`            | `@storybook/addon-actions`       |
+| `@kadira/storybook-addon-links`              | `@storybook/addon-links`         |
+| `@kadira/storybook-addon-info`               | `@storybook/addon-info`          |
+| `@kadira/storybook-addon-knobs`              | `@storybook/addon-knobs`         |
+| `@kadira/storybook-addon-comments`           | `@storybook/addon-comments`      |
+| `@kadira/storybook-addon-notes`              | `@storybook/addon-notes`         |
+| `@kadira/storybook-addon-options`            | `@storybook/addon-options`       |
+| `@kadira/storybook-addon-graphql`            | `@storybook/addon-graphql`       |
+| `@kadira/react-storybook-decorator-centered` | `@storybook/addon-centered`      |
+
+If your codebase is small, it's probably doable to just replace them by hand. (in your codebase and in `package.json`).
+
+But if you have a lot of occurances in your codebase, you can use a [codemod we created](./lib/codemod) for you.
+
+You have to change your `package.json`, prune old and install new dependencies by hand.
+
+`npm prune` will remove all dependecies from `node_modules` which are no longer referenced in `package.json`.
+
+### Deprecated embedded addons
+
+We used to ship 2 addons with every single installation of storybook: `actions` and `links`. But in practice not everyone is using them, so we decided to deprecate this and in the future they will be completely removed. If you use `@storybook/react/addons` you will get a deprecation warning.
+
+If you **are** using these addons, migrating is simple:
+
+-   add the addons you use to your `package.json`.
+-   change your code to this:
+    change `addons.js` like so:
+    ```js
+    import '@storybook/addon-actions/register';
+    import '@storybook/addon-links/register';
+    ```
+    change `x.story.js` like so:
+    ```js
+    import React from 'react';
+    import { storiesOf } from '@storybook/react';
+    import { action } from '@storybook/addon-actions';
+    import { link } from '@storybook/addon-links';
+    ```

docs/pages/addons/addon-gallery/index.md

@@ -36,45 +36,58 @@ If you are using Storybook as a style guide, then this addon will help you to bu
 
 The Storybook webapp UI can be customised with this addon. It can be used to change the header, show/hide various UI elements and to enable full-screen mode by default.
 
+### [Storyshots](https://github.com/storybooks/storybook/tree/master/addons/storyshots)
+
+Storyshots is a way to automaticly jest-snapshot all your stories. [More info here](../testing/structural-testing#).
 
 ## Community Addons
 
 You need to install these addons directly from NPM in order to use them.
 
 ### [README](https://github.com/tuchk4/storybook-readme)
+
 With this addon, you can add docs in markdown format for each story.
 It very useful because most projects and components already have README.md files.
 Now it is easy to add them into your Storybook.
 
 ### [Story-router](https://github.com/gvaldambrini/storybook-router)
+
 A [decorator](/addons/introduction) that allows you to integrate react-router components in your stories.
 
 ### [Host](https://github.com/philcockfield/storybook-host)
+
 A [decorator](/addons/introduction) with powerful display options for hosting, sizing and framing your components.
 
 ### [Specs](https://github.com/mthuret/storybook-addon-specifications)
+
 This is a very special addon where it'll allow you to write test specs directly inside your stories.
 You can even run these tests inside a CI box.
 
 ### [Chapters](https://github.com/yangshun/react-storybook-addon-chapters)
+
 With this addon, you can showcase multiple components (or varying component states) within 1 story.
 Break your stories down into smaller categories (chapters) and subcategories (sections) for more organizational goodness.
 
 ### [Props Combinations](https://github.com/evgenykochetkov/react-storybook-addon-props-combinations)
+
 Given possible values for each prop, renders your component with all combinations of prop values.
 Useful for finding edge cases or just seeing all component states at once.
 
 ### [Backgrounds](https://github.com/NewSpring/react-storybook-addon-backgrounds)
+
 With this addon, you can switch between background colors and background images for your preview components. It is really helpful for styleguides.
 
 ### [Material-UI](https://github.com/sm-react/storybook-addon-material-ui)
+
 Wraps your story into MuiThemeProvider.
 It allows you to add your custom themes, switch between them, make changes in the visual editor and download as JSON file
 
 ### [i18n tools](https://github.com/joscha/storybook-addon-i18n-tools)
+
 With this addon, you can test your storybooks with a different text-direction.
 It is very useful if you are working on components that have to work both in LTR as well as in RTL languages.
 
 ### [JSX preview](https://github.com/Kilix/storybook-addon-jsx)
+
 This addon shows a preview of the JSX code for each story.
 It allows you to configure the display and copy the code with a single click.

docs/pages/basics/writing-stories/index.md

@@ -123,6 +123,7 @@ storiesOf('core.Button', module)
 Then you can filter stories to display only the stories you want to see.
 
 ### [Chapters](https://github.com/yangshun/react-storybook-addon-chapters)
+
 With this addon, you can showcase multiple components (or varying component states) within 1 story.
 Break your stories down into smaller categories (chapters) and subcategories (sections) for more organizational goodness.
 

docs/pages/configurations/cli-options/index.md

@@ -11,29 +11,25 @@ Here are all those options:
 
 ## For start-storybook
 
-```
-Usage: start-storybook [options]
+    Usage: start-storybook [options]
 
-Options:
+    Options:
 
-  -h, --help                    output usage information
-  -V, --version                 output the version number
-  -p, --port [number]           Port to run Storybook (Required)
-  -h, --host [string]           Host to run Storybook
-  -s, --static-dir <dir-names>  Directory where to load static files from
-  -c, --config-dir [dir-name]   Directory where to load Storybook configurations from
-```
+      -h, --help                    output usage information
+      -V, --version                 output the version number
+      -p, --port [number]           Port to run Storybook (Required)
+      -h, --host [string]           Host to run Storybook
+      -s, --static-dir <dir-names>  Directory where to load static files from
+      -c, --config-dir [dir-name]   Directory where to load Storybook configurations from
 
 ## For build-storybook
 
-```
-Usage: build-storybook [options]
+    Usage: build-storybook [options]
 
-Options:
+    Options:
 
-  -h, --help                    output usage information
-  -V, --version                 output the version number
-  -s, --static-dir <dir-names>  Directory where to load static files from
-  -o, --output-dir [dir-name]   Directory where to store built files
-  -c, --config-dir [dir-name]   Directory where to load Storybook configurations from
-```
+      -h, --help                    output usage information
+      -V, --version                 output the version number
+      -s, --static-dir <dir-names>  Directory where to load static files from
+      -o, --output-dir [dir-name]   Directory where to store built files
+      -c, --config-dir [dir-name]   Directory where to load Storybook configurations from

docs/pages/configurations/custom-webpack-config/index.md

@@ -13,7 +13,7 @@ There are a few ways to do it:
 
 ## Extend Mode
 
-You'll get *extend-mode* by returning an object.
+You'll get _extend-mode_ by returning an object.
 
 Let's say you want to add [SASS](http://sass-lang.com/) support to Storybook. This is how to do it.
 Simply add the following content to a file called `webpack.config.js` in your Storybook config directory (`.storybook` by default ).

docs/pages/configurations/serving-static-files/index.md

@@ -78,7 +78,6 @@ storiesOf('<img>', module)
   ));
 ```
 
-
 ## Absolute versus relative paths
 
 Sometimes, you may want to deploy your storybook into a subpath, like <https://kadira-samples.github.io/react-button>.

lib/codemod/README.md

@@ -13,28 +13,51 @@ It will help you migrate breaking changes.
 ## Installation
 
 ```sh
+npm install jscodeshift
 npm install @storybook/codemod
 ```
 
+-   `@storybook/codemod` is out collection of codemod scripts.
+-   `jscodeshift` is a tool we use to apply our codemods.
+
+After running the migration commands, you can remove them from your `package.json`, if you added them.
+
+## How to run a codemod script
+
+From the directory where you installed both `jscodeshift` and `@storybook/codemod` run:
+
+Example:
+
+```sh
+./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/update-organisation-name.js . --ignore-pattern "node_modules|dist"
+```
+
+Explanation:
+
+    <jscodeShiftCommand> -t <transformFileLocation> <pathToSource> --ignore-pattern "<globPatternToIgnore>"
+
 ## Transforms
 
 ### add-organisation-to-package-name
 
-Updates package names in imports to include our organisation name prefix
-(`@storybook/`), stripping off the old `@storybook/` prefix.
+Updates package names in imports to migrate to the new package names of storybook.
 
 ```sh
-jscodeshift -t add-organisation-to-package-name path/to/source.js
+./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/update-organisation-name.js . --ignore-pattern "node_modules|dist"
 ```
 
+There's a mapping of paths we replace but this example explains the gist of it:
+
 Example:
 
 ```js
 import { storiesOf } from '@kadira/storybook';
+import { storiesOf } from '@kadira/storybook-addon-links';
 ```
 
-becomes
+Becomes
 
 ```js
 import { storiesOf } from '@storybook/react';
+import { storiesOf } from '@storybook/addon-links';
 ```

lib/codemod/package.json

@@ -10,5 +10,12 @@
   "main": "src/index.js",
   "dependencies": {
     "jscodeshift": "^0.3.30"
+  },
+  "scripts": {
+    "prepublish": "node ../../scripts/prepublish.js && mv dist/transforms/* dist"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "shelljs": "^0.7.7"
   }
 }

lib/codemod/src/transforms/update-organisation-name.js

@@ -1,39 +1,54 @@
-// Demo at https://astexplorer.net/#/gist/f2d0b42c37e4556a4f816892be6ca402/latest
 export default function transformer(file, api) {
   const j = api.jscodeshift;
+
   const packageNames = {
-    '@kadira/storybook-addons': '@storybook/addons',
     '@kadira/react-storybook-decorator-centered': '@storybook/addon-centered',
+    '@kadira/storybook-addons': '@storybook/addons',
+    '@kadira/storybook-addon-actions': '@storybook/addon-actions',
     '@kadira/storybook-addon-comments': '@storybook/addon-comments',
     '@kadira/storybook-addon-graphql': '@storybook/addon-graphql',
     '@kadira/storybook-addon-info': '@storybook/addon-info',
     '@kadira/storybook-addon-knobs': '@storybook/addon-knobs',
     '@kadira/storybook-addon-links': '@storybook/addon-links',
     '@kadira/storybook-addon-notes': '@storybook/addon-notes',
     '@kadira/storybook-addon-options': '@storybook/addon-options',
-    storyshots: '@storybook/addon-storyshots',
     '@kadira/storybook-channels': '@storybook/channels',
     '@kadira/storybook-channel-postmsg': '@storybook/channel-postmessage',
     '@kadira/storybook-channel-websocket': '@storybook/channel-websocket',
-    '@kadira/getstorybook': '@storybook/cli',
-    '@kadira/react-storybook': '@storybook/react',
-    '@kadira/react-native-storybook': '@storybook/react-native',
     '@kadira/storybook-ui': '@storybook/ui',
+    '@kadira/react-native-storybook': '@storybook/react-native',
+    '@kadira/react-storybook': '@storybook/react',
+    '@kadira/getstorybook': '@storybook/cli',
+    '@kadira/storybook': '@storybook/react',
+    storyshots: '@storybook/addon-storyshots',
+    getstorybook: '@storybook/cli',
   };
+  const packageNamesKeys = Object.keys(packageNames);
+
+  /**
+   * Checks whether the node value matches a Storybook package
+   * @param {string} the import declaration node
+   * @returns {string} whether the node value matches a Storybook package
+   */
+  const getMatch = oldpart => packageNamesKeys.find(newpart => oldpart.match(newpart));
 
   /**
-   * Returns the name of the Storybook packages with the organisation name, 
+   * Returns the name of the Storybook packages with the organisation name,
    * replacing the old `@kadira/` prefix.
    * @param {string} oldPackageName the name of the old package
    * @return {string} the new package name
    * @example
-   * // returns '@storybook/react'
-   * getNewPackageName('@kadira/react-storybook')
+   * // returns '@storybook/storybook'
+   * getNewPackageName('@kadira/storybook')
    */
   const getNewPackageName = oldPackageName => {
-    const packageNameWithOrganisation = packageNames[oldPackageName];
+    const match = getMatch(oldPackageName);
 
-    return packageNameWithOrganisation;
+    if (match) {
+      const replacement = packageNames[match];
+      return oldPackageName.replace(match, replacement);
+    }
+    return oldPackageName;
   };
 
   /**