Merge pull request #19275 from storybookjs/tom/sb-628-properly-docume…

…nt-maintenance-scripts

Refactor bootstrap+sandbox into "task" framework

.circleci/config.yml

@@ -85,26 +85,15 @@ jobs:
       - restore_cache:
           name: Restore Yarn cache
           keys:
-            - build-yarn-2-cache-v3--{{ checksum "code/yarn.lock" }}
+            - build-yarn-2-cache-v4--{{ checksum "code/yarn.lock" }}--{{ checksum "scripts/yarn.lock" }}
       - run:
-          name: Install dependencies
+          name: Compile
           command: |
-            cd code
-            yarn install --immutable
-      - run:
-          name: Install script dependencies
-          command: |
-            cd scripts
-            yarn install --immutable
-      - run:
-          name: Bootstrap
-          command: |
-            cd code
-            yarn bootstrap --build
+            yarn task --task compile --start-from=auto --no-link --debug
             git diff --exit-code
       - save_cache:
           name: Save Yarn cache
-          key: build-yarn-2-cache-v3--{{ checksum "code/yarn.lock" }}
+          key: build-yarn-2-cache-v4--{{ checksum "code/yarn.lock" }}--{{ checksum "scripts/yarn.lock" }}
           paths:
             - ~/.yarn/berry/cache
       - persist_to_workspace:
@@ -324,14 +313,13 @@ jobs:
           at: .
       - run:
           name: Creating Sandboxes
-          command: yarn task --task create --template $(yarn get-template ci create) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task sandbox --template $(yarn get-template ci create) --no-link --start-from=never --junit
       - persist_to_workspace:
           root: .
           paths:
             - sandbox
       - store_test_results:
-          path: code/test-results
+          path: test-results
   smoke-test-sandboxes:
     executor:
       class: medium+
@@ -344,10 +332,9 @@ jobs:
           at: .
       - run:
           name: Smoke Testing Sandboxes
-          command: yarn task --task smoke-test --template $(yarn get-template ci smoke-test) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task smoke-test --template $(yarn get-template ci smoke-test) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
   build-sandboxes:
     executor:
       class: medium+
@@ -360,10 +347,9 @@ jobs:
           at: .
       - run:
           name: Building Sandboxes
-          command: yarn task --task build --template $(yarn get-template ci build) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task build --template $(yarn get-template ci build) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
       - persist_to_workspace:
           root: .
           paths:
@@ -380,10 +366,9 @@ jobs:
           at: .
       - run:
           name: Running Test Runner
-          command: yarn task --task test-runner --template $(yarn get-template ci test-runner) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task test-runner --template $(yarn get-template ci test-runner) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
   chromatic-sandboxes:
     executor:
       class: medium+
@@ -396,10 +381,9 @@ jobs:
           at: .
       - run:
           name: Running Chromatic
-          command: yarn task --task chromatic --template $(yarn get-template ci chromatic) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task chromatic --template $(yarn get-template ci chromatic) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
   e2e-sandboxes:
     executor:
       class: medium+
@@ -412,10 +396,9 @@ jobs:
           at: .
       - run:
           name: Running E2E Tests
-          command: yarn task --task e2e-tests --template $(yarn get-template ci e2e-tests) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task e2e-tests --template $(yarn get-template ci e2e-tests) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
       - store_artifacts: # this is where playwright puts more complex stuff
           path: code/playwright-results/
           destination: playwright

.github/workflows/generate-repros-next.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Install dependencies
         run: node ./scripts/check-dependencies.js
       - name: Bootstrap Storybook libraries
-        run: yarn bootstrap --prep
+        run: yarn task --task compile --start-from=auto --no-link
         working-directory: ./code
       - name: Generate repros
         run: yarn generate-repros-next --local-registry

.github/workflows/tests-unit.yml

@@ -29,12 +29,7 @@ jobs:
         with:
           node-version: ${{ matrix.node_version }}
           cache: yarn
-      - name: install, bootstrap
-        run: |
-          cd code
-          yarn install --immutable
-          yarn bootstrap --core
+      - name: install and compile
+        run: yarn task --task compile --start-from=auto
       - name: test
-        run: |
-          cd code
-          yarn test --runInBand --ci
+        run: yarn test --runInBand --ci

.gitignore

@@ -18,4 +18,4 @@ junit.xml
 !/**/.yarn/sdks
 !/**/.yarn/versions
 /**/.pnp.*
-/yarn.lock
+!/node_modules

.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-3.2.3.cjs

CONTRIBUTING.md

@@ -2,17 +2,34 @@
 
 - Ensure you have node version 14 installed (suggestion: v14.18.1).
 - Ensure if you are using Windows to use the Windows Subsystem for Linux (WSL).
-- Run `./bootstrap.sh` to install the dependencies, and get the repo ready to be developed on.
-- Run `yarn start` inside of the `code` directory to start the development server.
+- Run `yarn start` directory to run a basic test Storybook "sandbox".
 
-# Generating reproductions
+The `yarn start` script will generate a React Vite TypeScript sandbox with a set of test stories inside it, as well as taking all steps required to get it running (building the various packages we need etc).
 
-The monorepo has a script that generates Storybook reproductions based on configurations set in the `code/lib/cli/src/repro-templates.ts` file. This makes it possible to quickly bootstrap examples with and without Storybook, for given configurations (e.g. CRA, Angular, Vue, etc.)
 
-To do so:
-- Check the `code/lib/cli/src/repro-templates.ts` if you want to see what will be generated
-- Run `./generate-repros.sh`
-- Check the result in the `repros` directory
+# Running against different sandbox templates
+
+You can also pick a specific template to use as your sandbox by running `yarn task`, which will prompt you to make further choices about which template you want and which task you want to run. 
+
+# Making code changes
+
+If you want to make code changes to Storybook packages while running a sandbox, you'll need to do the following:
+
+1. In a second terminal run `yarn build --watch <package-1> <package-2>` in the `code/` directory. The package names is the bit after the `@storybook/` in the published package. For instance, to build the `@storybook/react @storybook/core-server @storybook/api @storybook/addon-docs` packages at the same time in watch mode:
+
+```bash
+cd code
+yarn build --watch react core-server api addon-docs
+```
+
+2. If you are running the sandbox in "linked" mode (the default), you should see the changes reflected on a refresh (you may need to restart it if changing server packages)
+
+3. If you are running the sandbox in "unlinked" mode you'll need to re-run the sandbox from the `publish` step to see the changes:
+
+```
+yarn task --task dev --template <your template> --start-from=publish
+```
+
 
 # Contributing to Storybook
 

README.md

@@ -183,9 +183,13 @@ Looking for a first issue to tackle?
 
 Storybook is organized as a monorepo using [Lerna](https://lerna.js.org/). Useful scripts include:
 
-#### `./bootstrap.sh`
+#### `yarn start`
 
-> Installs package dependencies and links packages together - using lerna
+> Runs a sandbox template storybook with test stories
+
+#### `yarn task`
+
+> As above, but gives you options to customize the sandbox (e.g. selecting other frameworks)
 
 #### `yarn lint`