From ce3b0cbeecbbf505b51944849d183716a3e826b6 Mon Sep 17 00:00:00 2001
From: Dan Green <dangreen.tlv@gmail.com>
Date: Wed, 27 Sep 2017 21:50:54 -0400
Subject: [PATCH] Synced changes from new-docs to CONTRIBUTING.md

---
 CONTRIBUTING.md | 97 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 70 insertions(+), 27 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b1a0cb3c8985..1fae481ba282 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -175,45 +175,88 @@ If an issue is a `bug`, and it doesn't have a clear reproduction that you have p
 
 > If you want to work on a UI feature, refer to the [Storybook UI](https://github.com/storybooks/storybook/tree/master/lib/ui) page.
 
-This project written in ES2016+ syntax so, we need to transpile it before use.
-So run the following command:
+### Prerequisites
 
-```sh
-yarn dev
-```
+Please have the **_latest_** stable versions of the following on your machine
 
-This will watch files and transpile in watch mode.
+-   node
+-   yarn
 
-### Linking
+### Initial Setup
 
-First of all link this repo with:
+If you run into trouble here, make sure your node, npm, and **_yarn_** are on the latest versions (yarn at least v1.0.0).
 
-```sh
-yarn link
-```
+1.  `cd ~` (optional)
+2.  `git clone https://github.com/storybooks/storybook.git` _bonus_: use your own fork for this step
+3.  `cd storybook`
+4.  `yarn`
+5.  `yarn bootstrap --core`
+6.  `yarn test --core`
+7. `yarn dev` *You must have this running for your changes to show up*
 
-In order to test features you add, you may need to link the local copy of this repo.
-For that we need a sample project. Let's create it.
+#### Bootstrapping everything
 
-```sh
-yarn global add create-react-app getstorybook
-create-react-app my-demo-app
-cd my-demo-app
-getstorybook
-```
+*This method is slow*
 
-> It's pretty important to create a very simple sample project like above.
-> Otherwise some of the functionality won't work because of linking.
+1.  yarn bootstrap --all
+2.  Have a beer 🍺
+3.  `yarn test` (to verify everything worked)
 
-Then link storybook inside the sample project with:
+### Working with the kitchen sink apps
 
-```sh
-yarn link @storybook/react
-```
+Within the `examples` folder of the Storybook repo, you will find kitchen sink examples of storybook implementations for the various platforms that storybook supports.
+
+#### React and Vue
+
+1.  DO NOT RUN `yarn` or `yarn install`
+2. `yarn storybook`
+3.  Verify that your local version works
+
+### Working with your own app
+
+#### Linking Storybook
+
+Storybook is broken up into sub-projects that you can install as you need them. For this example we will be working with `@storybook/react`.
+**Note:** You need to `yarn link` from inside the sub project you are working on **_NOT_** the storybook root directory
+
+1.  `cd app/react`
+2.  `yarn link`
+
+#### Connecting Your App To Storybook
+
+**_Note:_** If you aren't seeing addons after linking storybook, you probably have a versioning issue which can be fixed by simply linking each addon you want to use.
+This applies for the kitchen sink apps as well as your own projects.
+
+*Make sure `yarn dev` is running*
+
+##### 1. Setup storybook in your project
+
+First we are going to install storyboook, then we are going to link `@storybook/react` into our project. This will replace `node_modules/@storybook/react` with a symlink to our local version of storybook. 
+
+1.  `getstorybook`
+2.  `yarn storybook`
+3.  Verify that your local version works
+
+##### 2. Link
+
+**_Note_**: This process is the same fore `@storybook/vue`, `@storybook/addon-foo`, etc
+
+1.  Go to your storybook _root_ directory 
+2.  `yarn dev`
+3.  Wait for the output to stop 
+4.  Go to your storybook-sandbox-app directory
+5.  `yarn link @storybook/react`
+6.  `yarn storybook`
+
+#### Verify your local version is working
+
+You should now have a working storybook dev environment up and running. To verify this you can make changes to the following file:
+
+`open app/react/src/client/manager/preview.js`
 
-### Getting Changes
+Save and go to `http://localhost:9009` (or wherever storybook is running)
 
-After you've done any change, you need to run the `yarn storybook` command every time to see those changes.
+If you don't see the changes rerun `yarn storybook` again in your sandbox app
 
 ## Release Guide