Merge pull request #15058 from storybookjs/update-contributor-docs

Update contributor docs
storybookjs · May 28, 2021 · abc74c3 · abc74c3
2 parents 6d824c5 + d1cfe72
commit abc74c3
Show file tree

Hide file tree

Showing 5 changed files with 59 additions and 51 deletions.
diff --git a/docs/contribute/code.md b/docs/contribute/code.md
@@ -2,11 +2,11 @@
 title: 'Code contributions'
 ---
 
-If you're willing to fix a bug or add a new feature to [Storybook](https://github.com/storybookjs/storybook), the first step is to set up your development environment. This page outlines how to get set up to contribute to Storybook's code. For instructions on working with documentation, check the [documentation contribution](./documentation-updates.md) page. To contribute to the code snippets, check the [snippets contribution](./new-snippets.md) page.
+Contribute a new feature or bug fix to [Storybook's monorepo](https://github.com/storybookjs/storybook). This page outlines how to get your environment set up to contribute code.
 
 ## Initial setup
 
-The first thing you need to do is [fork](https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo) the Storybook repository. Afterward, you need to clone and build your fork locally. Run the following commands:
+First [fork](https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo) the Storybook repository then clone and build your fork locally. Run the following commands:
 
 ```shell
 git clone https://github.com/your-username/storybook.git
@@ -15,9 +15,9 @@ yarn
 yarn bootstrap --core
 ```
 
-## Sanity check
+## Run tests & examples
 
-Once you've completed the [initial setup](#initial-setup), you should have a fully functional version of Storybook built on your local machine. Before making any code changes, it's helpful to verify that everything is working as it should. More specifically, the test suite and examples.
+Once you've completed the [initial setup](#run-tests-&-examples), you should have a fully functional version of Storybook built on your local machine. Before making any code changes, it's helpful to verify that everything is working as it should. More specifically, the test suite and examples.
 
 Run the following command to execute the tests:
 
@@ -68,25 +68,29 @@ Otherwise, if it affects the `Manager` (the outermost Storybook `iframe` where t
 
 ## Check your work
 
-When you're done with your work, we encourage you to include documentation and tests as appropriate. If you don't, we'll add a friendly reminder when you submit your pull request. 🧐
+When you're done coding, add documentation and tests as appropriate. That simplifies the PR review process, which means your code will get merged faster.
 
 ### Add stories
 
-Adding a story or set of stories to an example app is a great way to test your work. If you're modifying part of Storybook's core, or one of the addons, there's probably a set of stories you can add to the [`official-storybook`](../../examples/official-storybook). If you're modifying something related to a specific framework, they have their own examples in the monorepo. For instance, [`examples/vue-kitchen-sink`](../../examples/vue-kitchen-sink) is a natural place to add stories for `@storybook/vue`, [`examples/angular-cli`](../../examples/angular-cli) for `@storybook/angular`, and so on.
+Adding a story or set of stories to our suite of example apps helps you test your work.
+
+If you're modifying part of Storybook's core, or one of the essential addons, there's probably an existing set of stories in the [`official-storybook`](../../examples/official-storybook) that documents how the feature is supposed to work. Add your stories there.
+
+If you're modifying something related to a specific framework, the framework will have its own examples in the monorepo. For instance, [`examples/vue-kitchen-sink`](../../examples/vue-kitchen-sink) is a natural place to add stories for `@storybook/vue` while [`examples/angular-cli`](../../examples/angular-cli) is the place for `@storybook/angular`.
 
 ### Add tests
 
-Unit tests are also part of our test strategy. Therefore, we encourage you to use the following naming convention:
+Unit tests ensure that Storybook doesn't break accidentally. If your code can regress in non-obvious ways, include unit tests with your PR. Use the following naming convention:
 
 ```
 +-- parentFolder
 |   +-- [filename].ts
 |   +-- [filename].test.ts
 ```
 
-## Submit your contribution
+## Submit a pull request
 
-Before submitting your contribution, we recommend that you run the test suite one last time with:
+Before submitting your contribution, run the test suite one last time with:
 
 ```sh
 yarn test
@@ -98,13 +102,20 @@ yarn test
 
 Doing this prevents last-minute bugs and is also a great way to get your contribution merged faster once you submit your pull request. Failing to do so will lead to one of the maintainers mark the pull request with the **Work in Progress** label until all tests pass.
 
+### Target `next` branch
+
 Once the test suite finishes, it's time to commit, push and open a pull request against Storybook's `next` (default) branch. This branch is where all active development happens and is associated with the latest prerelease version (e.g., `6.3.0-alpha.25`).
 
-If your contribution focus on a bugfix and you want it featured in the next stable release, mention it in the pull request description. We'll try to get it in if it appears to be non-disruptive and fixes a critical bug.
+If your contribution focuses on a bugfix and you want it featured in the next stable release, mention it in the pull request description. We'll try to patch it in if it appears to be non-disruptive and fixes a critical bug.
+
+#### Useful resources when working with forks
+
+- [Sync a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork)
+- [Merge an upstream repository into your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork)
 
-## Working with reproductions
+## How to work with reproductions
 
-We strongly encourage contributors to create reproductions for their issues. In the same way, it's possible to [develop interactively](#start-developing) against example projects in the monorepo; it's also possible to develop against a reproduction repository.
+We encourage bug reports to include reproductions. In the same way that it's possible to [develop interactively](#start-developing) against example projects in the monorepo, it's also possible to develop against a reproduction repository.
 
 To do so, run the following command in the root of the monorepo:
 

diff --git a/docs/contribute/documentation-updates.md b/docs/contribute/documentation-updates.md
@@ -2,26 +2,22 @@
 title: 'Documentation updates'
 ---
 
-Contributions to the documentation are welcome and strongly encouraged. Either by fixing a small typo or a semantic error. This page outlines how to get involved and contribute to [Storybook's](https://github.com/storybookjs/storybook) documentation. For instructions on working with the codebase, check the [code contributions](./code.md) page, and for code snippets, check the [code snippets](./new-snippets.md) page.
+Fix a typo or clarify a section of the docs. This page outlines how to edit the documentation.
 
-## Identify and fix documentation issues
+## Find the Markdown file
 
-While browsing our documentation, you encounter an issue with the documentation, either a small typo or a semantic error; we encourage you to help us fix it. 
-
-Start by scrolling to the bottom of the page in question, then click ✍️ Edit on GitHub – PRs welcome!
+Scroll to the bottom of the document in question, then click ✍️ Edit on GitHub – PRs welcome! This will open the Markdown file on GitHub.
 
 ![Storybook documentation edit](./storybook-edit-docs-optimized.png)
 
-Click the pencil icon on the right-hand corner to edit the document and apply your fix.
+Use GitHub's web editor by clicking the pencil icon on the right-hand corner. Tweak the document to your liking.
 
 ![GitHub edit documentation](./github-docs-edit-optimized.png)
 
-Scroll down to the bottom of the page, fill the form with clear and concise information. 
-
-Next, select the `Create a new branch for this commit and start a pull request` option and finally, click the `Propose changes` button.
+Scroll down to the bottom of the document page on GitHub and describe what you changed and why. Select the `Create a new branch for this commit and start a pull request` option then click the `Propose changes` button.
 
 ![Fill the commit information](./storybook-docs-submit-changes-optimized.png)
 
 ## Create the pull request
 
-In the Storybook repository, fill the form with the necessary information, and submit your pull request. One of the maintainers will guide you through the triage and merge process.
+In the Storybook repository, create a pull request that describes changes and includes additional context that would help maintainers review. Once you submit the PR, a maintainer will guide you through the triage and merge process.
diff --git a/docs/contribute/how-to-contribute.md b/docs/contribute/how-to-contribute.md
@@ -1,22 +1,22 @@
 ---
-title: 'How to Contribute'
+title: 'How to contribute'
 ---
 
-We want Storybook contributions to be enjoyable and educational for everyone. Therefore, all contributions are welcome, including issues, new documentation, new features and updates, and much more.
+Storybook is a community-oriented open source project that welcomes contributions. Some of our most popular features started with a developer wanting to solve a problem for themselves.
 
-## Not sure how to start contributing?
+## Contributor covenant
 
-If you don't know where to start, you can reach out with questions on our [Discord Server](https://discord.gg/storybook) or submit an [issue](https://github.com/storybookjs/storybook/issues), and a maintainer can guide you!
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.[Continue reading our contributor covenant »](https://github.com/storybookjs/storybook/blob/next/CODE_OF_CONDUCT.md)
 
+## Ways to contribute
 
-## In this section:
+- [**Code**](./code.md): Features, bug fixes, dependency updates
+- [**Docs**](./documentation-updates.md): Typos, clarifications
+- [**Integrations**](./../api/new-frameworks): Integrate Storybook with your favorite library
+- [**Addons**](./../addons/introduction): Build an addon and share it with the community
 
-- [Code contributions](./code.md)
-- [Documentation contributions](./documentation-updates.md)
-- [Snippet contributions](./new-snippets.md)
+## Not sure how to get started?
 
-
-## Additional resources
-
-- [Synching a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork)
-- [Merging an upstream repository into your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork)
+- [Chat in Discord #contributing](https://discord.gg/storybook)
+- [Browse "good first issues" to fix](https://github.com/storybookjs/storybook/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+- [Submit a bug report or feature request](https://github.com/storybookjs/storybook/issues)
diff --git a/docs/contribute/new-snippets.md b/docs/contribute/new-snippets.md
@@ -2,18 +2,20 @@
 title: 'Code snippets contributions'
 ---
 
-Contributions to the snippets used in our documentation are welcome and greatly encouraged. This page outlines how to contribute to [Storybook's](https://github.com/storybookjs/storybook) code snippets. For instructions on working with the codebase, check the [code contributions](./code.md) page, and for documentation, check the [documentation contributions](./documentation-updates.md) page.
+Add or update the code snippets in the documentation. This page outlines how the code snippets are structured.
 
 ## Documented frameworks
 
-The Storybook documentation is highly versatile and constantly updated to solve everyday scenarios. Currently, it features examples for the following UI frameworks:
+Storybook maintains code snippets for a [variety of frameworks](./../api/frameworks-feature-support.md). We try to keep them up to date as framework APIs evolve. But it's tricky to keep track of every API change in every framework.
 
-| React                                                                       | Vue                                                                       | Angular                                                                       | Web Components                                                                                  | Svelte                                                                       | Ember | HTML | Mithril | Marko | Riot | Preact | Rax |
-|-----------------------------------------------------------------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|-------|------|---------|-------|------|--------|-----|
-| [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/react) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/vue) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/angular) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/web-components) (See note) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/svelte) | ❌     | ❌    | ❌       | ❌     | ❌    | ❌      | ❌   |
+We welcome community contributions to the code snippets. Here's a matrix of the frameworks we have snippets for. Help us add snippets for your favorite framework.
+
+| React                                                                        | Vue                                                                        | Angular                                                                        | Web Components                                                                                   | Svelte                                                                        | Ember | HTML | Mithril | Marko | Riot | Preact | Rax |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----- | ---- | ------- | ----- | ---- | ------ | --- |
+| [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/react) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/vue) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/angular) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/web-components) (See note) | [✅](https://github.com/storybookjs/storybook/tree/next/docs/snippets/svelte) | ❌    | ❌   | ❌      | ❌    | ❌   | ❌     | ❌  |
 
 <div class="aside">
-💡 Note: The <code>Web Components</code> snippets are present but not fully documented. If you're willing to help submit a pull request.
+💡 Note: The <code>Web Components</code> snippets are present but not fully documented. If you're willing to help, submit a pull request.
 </div>
 
 ## Setup
@@ -28,7 +30,7 @@ Before adding your snippets, open the `docs` folder with your editor of choice.
 
 ### Add your first snippet
 
-Now that you're familiar with how the documentation is structured, it's time to add the code snippets. First, go to the `docs/snippets/` folder and create a new directory for your framework of choice (e.g., `ember`). 
+Now that you're familiar with how the documentation is structured, it's time to add the code snippets. First, go to the `docs/snippets/` folder and create a new directory for your framework of choice (e.g., `ember`).
 
 Browse the documentation and look for the code snippets you're willing to contribute. For example, on the [setup page](https://github.com/storybookjs/storybook/blob/next/docs/get-started/setup.md), you should see something similar to:
 
@@ -85,7 +87,7 @@ Go through the rest of the documentation and repeat the process.
 
 ### Preview your work
 
-Before submitting your contribution, we advise you to check your work against the Storybook website. Doing this prevents last-minute issues with the documentation and is also an excellent way for the maintainers to merge faster once you submit the pull request. However, failing to do so will lead one of the maintainers to notify you that your contribution has an issue. 
+Before submitting your contribution, we advise you to check your work against the Storybook website. Doing this prevents last-minute issues with the documentation and is also an excellent way for the maintainers to merge faster once you submit the pull request. However, failing to do so will lead one of the maintainers to notify you that your contribution has an issue.
 
 Start by forking [frontpage repo](https://github.com/storybookjs/frontpage). Then, clone and install the dependencies with the following commands:
 
@@ -111,13 +113,12 @@ yarn start:skip-addons
 💡 <strong>Note:</strong> During the start process if there's an issue with the the documentation, the process will stop and you'll get a notification.
 </div>
 
-Open a browser window to `http://localhost:8000`, click the Docs link, and select your framework from the dropdown. 
+Open a browser window to `http://localhost:8000`, click the Docs link, and select your framework from the dropdown.
 
 ![Storybook docs with dropdown](./local-storybook-website-dropdown-optimized.png)
 
 Go through the documentation and check your work.
 
-
 ## Submit your contribution
 
-Finally, commit, push and open a pull request in the Storybook monorepo. Add a clear description of the work you've done, and one of the maintainers will guide you through and hopefully merge it with little feedback.
+Finally, commit, push and open a pull request in the Storybook monorepo. Add a clear description of the work you've done, and one of the maintainers will guide you through the merge process.
diff --git a/docs/toc.js b/docs/toc.js
@@ -413,7 +413,7 @@ module.exports = {
       children: [
         {
           pathSegment: 'how-to-contribute',
-          title: 'How to Contribute',
+          title: 'How to',
           type: 'link',
         },
         {
@@ -427,13 +427,13 @@ module.exports = {
           type: 'menu',
           children: [
             {
-              pathSegment: 'new-snippets',
-              title: 'Code snippets',
+              pathSegment: 'documentation-updates',
+              title: 'Content',
               type: 'link',
             },
             {
-              pathSegment: 'documentation-updates',
-              title: 'Updates',
+              pathSegment: 'new-snippets',
+              title: 'Code snippets',
               type: 'link',
             },
           ],