Thanks for your interest in improving Storybook! We are a community-driven project and welcome contributions of all kinds: from discussion to documentation to bugfixes to feature improvements.
Please review this document to help to streamline the process and save everyone's precious time.
This guide assumes you're using yarn as package manager. You may have some success using npm as well, but there are chances you'll get wrong versions of root dependencies in that case (we only commit yarn.lock to the repo).
No software is bug free. So, if you got an issue, follow these steps:
- Search the issue list for current and old issues.
- If you find an existing issue, please UPVOTE the issue by adding a "thumbs-up reaction". We use this to help prioritize issues!
- If none of that is helping, create an issue with with following information:
- Clear title (make is shorter if possible).
- Describe the issue in clear language.
- Share error logs, screenshots and etc.
- To speed up the issue fixing process, send us a sample repo with the issue you faced:
To test your project against the current latest version of storybook, you can clone the repository and link it with yarn. Try following these steps:
git clone https://github.com/storybooks/storybook.git
cd storybook
yarn install
yarn bootstrapThe bootstrap command will ask which sections of the codebase you want to bootstrap. Unless you're going to work with ReactNative or the Documentation, you can keep the default.
You can also pick directly from CLI:
yarn bootstrap -- --core
You can use one of the example projects in examples/ to develop on.
This command will list all the suites and options for running tests.
yarn testNote that in order to run the tests fro ReactNative, you must have bootstrapped with ReactNative enabled
You can also pick suites from CLI:
yarn test -- --coreIn order to run ALL unit tests, you must have bootstrapped the react-native
If you want to test your own existing project using the github version of storybook, you need to link the packages you use in your project.
```sh
cd app/react
yarn link
cd <your-project>
yarn link @storybook/react
# repeat with whichever other parts of the monorepo you are using.
```
The best way to help figure out an issue you are having is to produce a minimal reproduction against the master branch.
A good way to do that is using the example cra-kitchen-sink app embedded in this repository:
# Download and build this repository:
git clone https://github.com/storybooks/storybook.git
cd storybook
yarn install
yarn bootstrap
# make changes to try and reproduce the problem, such as adding components + stories
cd examples/cra-kitchen-sink
yarn storybook
# see if you can see the problem, if so, commit it:
git checkout "branch-describing-issue"
git add -A
git commit -m "reproduction for issue #123"
# fork the storybook repo to your account, then add the resulting remote
git remote add <your-username> https://github.com/<your-username>/storybook.git
git push -u <your-username> masterIf you follow that process, you can then link to the github repository in the issue. See storybookjs/storybook#708 (comment) for an example.
NOTE: If your issue involves a webpack config, create-react-app will prevent you from modifying the app's webpack config, however you can still modify storybook's to mirror your app's version of storybook. Alternatively, use yarn eject in the CRA app to get a modifiable webpack config.
We welcome your contributions. There are many ways you can help us. This is few of those ways:
- Fix typos and add more documentation.
- Try to fix some bugs.
- Work on API, Addons, UI or Webpack use enhancements and new features.
- Add more tests (specially for the UI).
Before you submit a new PR, make you to run yarn test. Do not submit a PR if tests are failing. If you need any help, create an issue and ask.
As a PR submitter, you should reference the issue if there is one, include a short description of what you contributed and, if it is a code change, instructions for how to manually test out the change. This is informally enforced by our PR template. If your PR is reviewed as only needing trivial changes (e.g. small typos etc), and you have commit access, then you can merge the PR after making those changes.
As a PR reviewer, you should read through the changes and comment on any potential problems. If you see something cool, a kind word never hurts either! Additionally, you should follow the testing instructions and manually test the changes. If the instructions are missing, unclear, or overly complex, feel free to request better instructions from the submitter. Unless the PR is tagged with the do not merge label, if you approve the review and there is no other required discussion or changes, you should also go ahead and merge the PR.
If you are looking for a way to help the project, triaging issues is a great place to start. Here's how you can help:
Issues that are tagged question / support or needs reproduction are great places to help. If you can answer a question, it will help the asker as well as anyone searching. If an issue needs reproduction, you may be able to guide the reporter toward one, or even reproduce it yourself using this technique.
Once you've helped out on a few issues, if you'd like triage access you can help label issues and respond to reporters.
We use the following label scheme to categorize issues:
- type -
bug,feature,question / support,discussion,greenkeeper,maintenance. - area -
addon: x,addons-api,stories-api,ui, etc. - status -
needs reproduction,needs PR,in progress, etc.
All issues should have a type label. bug/feature/question/discussion are self-explanatory. greenkeeper is for keeping package dependencies up to date. maintenance is a catch-all for any kind of cleanup or refactoring.
They should also have one or more area/status labels. We use these labels to filter issues down so we can easily see all of the issues for a particular area, and keep the total number of open issues under control.
For example, here is the list of open, untyped issues, or here is a list of bugs that have not been modified since 2017-04-01. For more info see searching issues in the Github docs.
If an issue is a bug, and it doesn't have a clear reproduction that you have personally confirmed, label it needs reproduction and ask the author to try and create a reproduction, or have a go yourself.
- Duplicate issues should be closed with a link to the original.
- Unreproducible issues should be closed if it's not possible to reproduce them (if the reporter drops offline, it is reasonable to wait 2 weeks before closing).
bugs should be labelledmergedwhen merged, and be closed when the issue is fixed and released.features,maintenances,greenkeepers should be labelledmergedwhen merged, and closed when released or if the feature is deemed not appropriate.question / supports should be closed when the question has been answered. If the questioner drops offline, a reasonable period to wait is two weeks.discussions should be closed at a maintainer's discretion.
If you want to work on a UI feature, refer to the Storybook UI page.
This project written in ES2016+ syntax so, we need to transpile it before use. So run the following command:
yarn devThis will watch files and transpile in watch mode.
First of all link this repo with:
yarn linkIn 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.
yarn global add create-react-app getstorybook
create-react-app my-demo-app
cd my-demo-app
getstorybookIt's pretty important to create a very simple sample project like above. Otherwise some of the functionality won't work because of linking.
Then link storybook inside the sample project with:
yarn link @storybook/reactAfter you've done any change, you need to run the yarn storybook command every time to see those changes.
This section is for Storybook maintainers who will be creating releases.
Each release is described by:
- A version
- A list of merged pull requests
- Optionally, a short hand-written description
Thus, the current release sequence is as follows:
NOTE: This is a work in progress. Don't try this unless you know what you're doing. We hope to automate this in CI, so this process is designed with that in mind.
First, build the release:
# make sure you current with origin/master.
git checkout master
git status
# clean out extra files & build all the packages
# WARNING: destructive if you have extra files lying around!
yarn bootstrap -- --reset --allFrom here there are different procedures for prerelease (e.g. alpha/beta/rc) and proper release.
NOTE: the very first time you publish a scoped package (
@storybook/x) you need to publish it by hand because the default for scoped packages is private, and we need to make our packages public. If you try to publish a package for the first time using ourlernapublish script,lernawill crash halfway through and you'll be in a world of pain.
# publish and tag the release
yarn run publish -- --concurrency 1 --npm-tag=alpha
# push the tags
git push --tags# publish but don't commit to git
yarn publish -- --concurrency 1 --skip-git
# Update `CHANGELOG.md`
# - Edit PR titles/labels on github until output is good
# - Optionally, edit a handwritten description in `CHANGELOG.md`
yarn changelog
# tag the release and push `CHANGELOG.md` and tags
# FIXME: not end-to-end tested!
yarn github-release