Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Contribution guide updates #26003

Open
wants to merge 3 commits into
base: next
Choose a base branch
from
+158 −16
Open

Docs: Contribution guide updates #26003

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2c0417d
doc: adds internal cross links to CONTRIBUTING.md to contribution doc…
usrrname Mar 9, 2024
a7b9471
doc: adds TOC to CONTRIBUTING.md
usrrname Mar 9, 2024
5f13592
doc: adds hidden folders to folder structure
usrrname Mar 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 158 additions & 16 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,126 @@

Storybook is developed against a specific node version which is defined in an `.nvmrc` file. You can use any Node version manager that uses the `.nvmrc` configuration file (we recommend [fnm](https://fnm.vercel.app/)).

## Table of Contents
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@usrrname, when you have a moment, can you adjust the whole documentation as follows:

# Contributors Guide

We welcome contributions of any type and skill level. As an open-source project, we believe in the power of community and welcome any contributions that help us improve Storybook. Whether you are a developer, designer, writer, or someone who wants to help, we'd love to have you on board. If you are interested in contributing, please read the following guidelines.

## How to Contribute

Whether you're new to open source or a seasoned contributor, we welcome all contributions. Here are a few ways you can contribute to Storybook:

- [Create an RFC](./docs/contribute/rfc.md) for feature requests
- Update our [documentation](./docs/contribute/documentation-updates.md) with fixes, improvements, or clarifications
- Add [new examples](./docs/contribute/new-snippets.md) of code snippets for using Storybook with a JS framework
- [Integrate Storybook with a JS framework](./docs/contribute/framework.md) or improve support of existing frameworks
- [Write an addon](https://storybook.js.org/docs/addons/introduction) to extend Storybook's functionality

### Other ways to contribute

If you're not sure where to start, you can always help us by:

- [Reporting a bug](https://github.com/storybookjs/storybook/issues/new/choose) 
- Answer [Help](https://github.com/storybookjs/storybook/discussions/categories/help?discussions_q=is%3Aopen+category%3AHelp) questions on Storybook's GitHub discussions
- [Browse `Good First Issue`s to fix](https://github.com/storybookjs/storybook/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)


> **Note**: Before you start contributing, please read the [Code of Conduct](./CODE_OF_CONDUCT.md) and reach out to the maintainers if you have any questions or concerns about the project or the contribution process on the [`#contributing`](https://discord.com/channels/486522875931656193/839297503446695956) channel on Discord.

## Quick guide

### Prerequisites

Storybook is developed against a specific Node.js version specified in the `.nvmrc` file. You can use any version manager to install the correct version of Node.js. We recommend using [fnm](https://github.com/Schniz/fnm). 

1. Check if you have the correct version of Node.js installed by running the following command:

```shell
# Check which version you're using
node --version

# node version manager 
nvm use 18

# pnpm
pnpm env use --global 18
```

2. Install [fnm](https://github.com/Schniz/fnm/tree/master?tab=readme-ov-file#installation) and adjust your shell configuration to include the following parameters: `fnm env`, `use-on-cd`, `corepack-enabled`, and `version-file-strategy recursive`.

```shell
  eval "$(fnm env --use-on-cd --corepack-enabled --version-file-strategy recursive)"
```

3. If you're a Windows user, you'll need to enable Windows Subsystem for Linux (WSL). You can follow the instructions [here](https://docs.microsoft.com/en-us/windows/wsl/install).

### What's inside

Storybook uses a monorepo structure to manage the project and its packages. Currently, it's composed of the following packages and directories:

```shell
#  @usrrname can you adjust the tree structure to match the actual project structure?
```

### Fork the repository

If you plan to contribute to Storybook's codebase, you should fork the repository to your GitHub account. This will allow you to make changes to the codebase and submit a pull request to the main repository when you're ready to contribute your changes.

Once you've forked the repository, you should [disable Github Actions for your forked repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) as most of them (e.g., pushing to sandbox) will fail without proper authorization. In your forked repository, go to Settings > Actions > General > set the Actions Permissions to **Disable actions**.

Additionally, adding our codebase as upstream ensures you can rebase against the latest changes in the main repository. To do this, run the following commands:

<!--

@usrrname can you either:
- Adjust the branch name to match what's currently in use (i.e., next) in the main repository? As we're not using the main branch as the default branch, you should adjust the branch name to match the default branch in the main repository.
- Remove the commands and provide links to documentation that explains how to add the upstream repository as a remote and sync your fork with the main repository.
- Combine both options?
 -->

```shell
git remote add upstream [email protected]:storybookjs/storybook.git
```

Now, when you want to update your fork with the latest changes from the main repository, you can run the following commands:

```shell
git fetch upstream # Updates your local copy of the main repository with changes from the official repository

git rebase upstream/main # Rebases your current branch against upstream/main
```

### Running the local development environment

If you're interested in contributing to Storybook's codebase, you can run it locally to get a feel for the codebase and the development environment. To get started with the development environment, you should always run `yarn start` from the root directory. Running `yarn start` will install the required dependencies, build the project, including the packages, and generate a sandbox environment using React with TypeScript with a set of test stories to help you get started.

```shell
git clone && cd ...
yarn start
```

> You don't need to install the dependencies manually to get the project running. The `yarn start` command will install the required dependencies for you.

### 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 name can be found after `@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:

```shell
cd code
yarn build --watch react core-server api addon-docs
```

2. If you are running the sandbox in ["linked"](https://yarnpkg.com/cli/link) 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 rerun the sandbox from the `publish` step to see the changes:

```shell
yarn task --task dev --template <your template> --start-from=publish
```

4. If you have made any changes inside `/code` or other packages, remember to run `yarn test` from inside the package to ensure that your changes do not break any tests.

### Running against different sandbox templates

You can 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.

## Troubleshooting

### The initialization process throws an error

If you run `yarn start` and encounter the following error, try rerunning `yarn start` a second time:

```shell
>  NX   ENOENT: no such file or directory, open 'storybook/code/node_modules/nx/package.json'
```

### Storybook doesn't detect changes in the codebase

If you are a Storybook contributor and still experience issues, it is recommended that you verify your local Storybook instance for any unintentional local changes. To do this, you can use the following command:

```shell
git clean -dx --dry-run
```

By executing this command, you can see which untracked or ignored files and directories will be removed from your working directory if you run it with the `--force` flag. Before running the command with the `--force` flag, please commit any local changes you want to keep. Otherwise, they will be lost.

## Contributing to Storybook

For further advice on contributing, please refer to our [NEW contributing guide on the Storybook website](https://storybook.js.org/docs/contribute).

The reasoning behind this change is to provide a better structure and narrative to this part of the documentation while keeping your much-appreciated changes.


- [Contributing](#contributing)
- [How to contribute](#how-to-contribute)
- [Easy Ways to Contribute](#easy-ways-to-contribue)
- [What's Inside?](#whats-inside)

# Contributing

Check out setup instructions for [Code Contributions](./docs/contribute/code.md)

## How to contribute

- [Create an RFC](./docs/contribute/rfc.md) for feature requests
- [Integrate Storybook with a JS framework](./docs/contribute/framework.md) or improve support of existing frameworks
- Update [Documentation](./docs/contribute/documentation-updates.md) for documentation improvements, typos, and clarifications
- Add [new examples](./docs/contribute/new-snippets.md) of code snippets for using Storybook with a JS framework
- [Write a preset](https://storybook.js.org/docs/presets/introduction)
- [Write an addon](https://storybook.js.org/docs/addons/introduction)

#### Easy Ways to Contribute :sparkle:

- Report a bug by [creating a reproduction](https://storybook.js.org/docs/contribute/bug-report) of the problem

- [Update Documentation](https://storybook.js.org/docs/contribute/documentation-updates), including [code snippets](https://storybook.js.org/docs/contribute/new-snippets) for using Storybook with different frameworks
- [Create a new feature](https://storybook.js.org/docs/contribute/feature)

Don't know where to start?

- Ask [`#contributing`](https://discord.com/channels/486522875931656193/839297503446695956) on Discord

- Answer [Help](https://github.com/storybookjs/storybook/discussions/categories/help?discussions_q=is%3Aopen+category%3AHelp) questions on Storybook Github

- [Browse `Good First Issue`s to fix](https://github.com/storybookjs/storybook/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)


## What's Inside?

This is a brief overview of directories and files most relevant to contributors in this repo.

```bash
.
├── CHANGELOG.md # Changelog of current version of Storybook
├── CODEOWNERS
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING <---------------- You are here!
├── Issue.md
├── MIGRATION.md
├── README.md
├── repros # Hidden folder: Reproductions for issues
├── sandbox # Hidden folder: Sandbox for testing Storybook
└── code # Storybook packages
├── __mocks__ # Mocks for jest tests
├── addons # Storybook addon packages
├── builders # Storybook builder packages
├── deprecated
├── e2e-tests
└── frameworks # Storybook meta-framework packages for spinning up new Storybook instances
├── angular
├── ember
├── html-vite
├── html-webpack5
├── nextjs
├── preact-vite
├── preact-webpack5
├── react-vite
├── react-webpack5
├── server-webpack5
├── svelte-vite
├── svelte-webpack5
├── sveltekit
├── vue-vite
├── vue-webpack5
├── vue3-vite
├── vue3-webpack5
├── web-components-vite
└── web-components-webpack5
│ ├── lib # Storybook core features
│ ├── migrations.json
│ ├── node_modules
│ ├── nx.json
│ ├── package.json
│ ├── playwright-report
│ ├── playwright-results
│ ├── playwright.config.ts
│ ├── presets # Storybook preset packages
│ ├── prettier.config.js
│ ├── renderers # Storybook renderer for integrating JS framework components in stories
│ ├── tsconfig.json
│ ├── ui
│ └── yarn.lock
├── codecov.yml
├── docs # Storybook documentation - the easiest place to start!
├── node_modules
├── package.json
├── repros
│ ├── cra
│ ├── html-vite
│ ├── nextjs
│ └── react-vite
├── sandbox
├── scripts
├── test-storybooks
└── yarn.lock

```

## Ensure you're using Node 18

```bash
# Check which version you're using
node --version

# node version manager
nvm use 18

# pnpm
pnpm env use --global 18
```

## Using fnm as a Node version manager

- Install fnm [as per instructions](https://github.com/Schniz/fnm/tree/master#installation)
Expand All @@ -13,54 +133,76 @@ Storybook is developed against a specific node version which is defined in an `.

## Running the local development environment

- Ensure if you are using Windows to use the Windows Subsystem for Linux (WSL).
- Ensure if you are using Windows to use the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL).
- Run `yarn start` in the root directory to run a basic test Storybook "sandbox".

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). There is no need to run `yarn` or `yarn install` as `yarn start` will do this for you.
The `yarn start` script will by default 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). There is no need to run `yarn` or `yarn install` as `yarn start` will do this for you.

### Issues
#### Forked repos

If you run `yarn start` and encounter the following error, try rerunning `yarn start` a second time:
Unless you're editing docs, you'll have to fork the Storybook repo to make code changes.

```sh
> NX ENOENT: no such file or directory, open 'storybook/code/node_modules/nx/package.json'
```
After forking the repository, you should [disable Github Actions for your repo](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) as many of them (e.g. pushing to sandbox) will fail without proper authorization. In your Github repo, go to Settings > Actions > General > set the Actions Permissions to **Disable actions**.

If you are a Storybook contributor and still experience issues, it is recommended that you verify your local Storybook instance for any unintentional local changes. To do this, you can use the following command:
After forking the repository, adding our codebase as upstream ensures you can rebase against the latest changes in the main repository. To do this, run the following commands:

```sh
git clean -dx --dry-run
git remote add upstream [email protected]:storybookjs/storybook.git
```

By executing this command, you will be able to see which untracked or ignored files and directories will be removed from your working directory if you run it with the `--force` flag. Before running the command with the `--force` flag, please commit any local changes that you want to keep. Otherwise they will be lost.
Now, when you want to update your fork with the latest changes from the main repository, you can run the following commands:

## Forked repos
```sh
git fetch upstream # updates your local copy of the main repository with changes from the official repository

If you have forked the repository, you should [disable Github Actions for your repo](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) as many of them (e.g. pushing to sandbox) will fail without proper authorization. In your Github repo, go to Settings > Actions > General > set the Actions Permissions to **Disable actions**.
git rebase upstream/main # rebases your current branch against upstream/main
```

## 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.
You can 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:
1. In a second terminal run `yarn build --watch <package-1> <package-2>` in the `code/` directory.
The package name can be found after `@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)
2. If you are running the sandbox in ["linked"](https://yarnpkg.com/cli/link) 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:

```sh
yarn task --task dev --template <your template> --start-from=publish
```

4. If you have made any changes inside `/code` or other packages, remember to run `yarn test` from inside the package to ensure that your changes do not break any tests.

### Troubleshooting

If you run `yarn start` and encounter the following error, try rerunning `yarn start` a second time:

```sh
> NX ENOENT: no such file or directory, open 'storybook/code/node_modules/nx/package.json'
```

If you are a Storybook contributor and still experience issues, it is recommended that you verify your local Storybook instance for any unintentional local changes. To do this, you can use the following command:

```sh
git clean -dx --dry-run
```

By executing this command, you will be able to see which untracked or ignored files and directories will be removed from your working directory if you run it with the `--force` flag. Before running the command with the `--force` flag, please commit any local changes that you want to keep. Otherwise they will be lost.


## Contributing to Storybook

For further advice on how to contribute, please refer to our [NEW contributing guide on the Storybook website](https://storybook.js.org/docs/contribute).
For further advice on how to contribute, please refer to our :new: [NEW contributing guide on the Storybook website](https://storybook.js.org/docs/contribute).