diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b593fa53be9b15..200a8cda5ee236 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,61 +1,66 @@ # Contributing to MUI -If you're reading this, you're awesome! Thank you for helping us make this project great and being a part of the MUI community. Here are a few guidelines that will help you along the way. +If you're reading this, you're awesome! +Thank you for being a part of the MUI community and helping us make these projects great. +Here are a few guidelines that will help you along the way. ## Summary -- [Code of Conduct](#code-of-conduct) +- [Code of conduct](#code-of-conduct) - [A large spectrum of contributions](#a-large-spectrum-of-contributions) -- [Your first Pull Request](#your-first-pull-request) -- [Sending a Pull Request](#sending-a-pull-request) +- [Your first pull request](#your-first-pull-request) +- [Sending a pull request](#sending-a-pull-request) - [Trying changes on the documentation site](#trying-changes-on-the-documentation-site) - [Trying changes on the playground](#trying-changes-on-the-playground) - - [How to increase the chance of being accepted?](#how-to-increase-the-chance-of-being-accepted) + - [How to increase the chances of being accepted](#how-to-increase-the-chances-of-being-accepted) - [CI checks and how to fix them](#ci-checks-and-how-to-fix-them) - [Updating the component API documentation](#updating-the-component-api-documentation) - [Coding style](#coding-style) - [How to add a new demo in the documentation](#how-to-add-a-new-demo-in-the-documentation) -- [How can I use a change that wasn't released yet?](#how-can-i-use-a-change-that-wasnt-released-yet) +- [How can I use a change that hasn't been released yet?](#how-can-i-use-a-change-that-hasnt-been-released-yet) - [Roadmap](#roadmap) - [License](#license) -## Code of Conduct +## Code of conduct -MUI has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. +MUI has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as our code of conduct, and we expect project participants to adhere to it. Please read [the full text](https://github.com/mui/.github/blob/master/CODE_OF_CONDUCT.md) to understand what actions will and will not be tolerated. ## A large spectrum of contributions -There are [many ways](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) to contribute to MUI, code contribution is one aspect of it. For instance, documentation improvements are as important as code changes. +There are [many ways](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) to contribute to MUI, and writing code is only one part of the story—documentation improvements can be just as important as code changes. +If you have an idea for an improvement to the code or the docs, we encourage you to open an issue as a first step, to discuss your proposed changes with the maintainers before proceeding. -## Your first Pull Request +## Your first pull request -Working on your first Pull Request? You can learn how from this free video series: +Working on your first pull request? You can learn how in this free video series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github). -[How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) +Get started with [good first issues](https://github.com/mui/material-ui/issues?q=is:open+is:issue+label:"good+first+issue"), which have a limited scope and a working solution that's already been discussed. +This makes them ideal for newer developers, or those who are new to these libraries and want to see how the contribution process works. -To help you get your feet wet and get you familiar with our contribution process, we have a list of [good first issues](https://github.com/mui/material-ui/issues?q=is:open+is:issue+label:"good+first+issue") that contain changes that have a relatively limited scope. This label means that there is already a working solution to the issue in the discussion section. Therefore, it is a great place to get started. +We also have a list of [good to take issues](https://github.com/mui/material-ui/issues?q=is:open+is:issue+label:"good+to+take"), which are issues that have already been at least partially resolved in discussion, to the point that it's clear what to do next. +These issues are great for developers who want to reduce their chances of falling down a rabbit hole in search of a solution. -We also have a list of [good to take issues](https://github.com/mui/material-ui/issues?q=is:open+is:issue+label:"good+to+take"). This label is set when there has already been some discussion about the solution, and it is clear in which direction to go. These issues are good for developers that want to reduce the chance of going down a rabbit hole. +Of course, you can work on any other issue you like—the "good first" and "good to take" issues are simply those where the scope and timeline may be better defined. +Pull requests for other issues, or completely novel problems, may take a bit longer to review if they don't fit into our current development cycle. -You can also work on any other issue you choose to. -The "good first" and "good to take" issues are just issues where we have a clear picture about scope and timeline. -Pull requests working on other issues or completely new problems may take a bit longer to review when they don't fit into our current development cycle. +If you decide to fix an issue, please make sure to check the comment thread in case somebody is already working on a fix. +If nobody is working on it at the moment, please leave a comment stating that you've started to work on it, so other people don't accidentally duplicate your effort. -If you decide to fix an issue, please make sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you have started to work on it, so other people don't accidentally duplicate your effort. +If somebody claims an issue but doesn't follow up after more than a week, it's fine to take over, but you should still leave a comment. +If there has been no activity on the issue for 7 to 14 days, then it's safe to assume that nobody is working on it. -If somebody claims an issue but doesn't follow up for more than a week, it's fine to take it over, but you should still leave a comment. -If there has been no activity on the issue for 7 to 14 days, it is safe to assume that nobody is working on it. +## Sending a pull request -## Sending a Pull Request +MUI Core projects are community-driven, so pull requests are always welcome, but before working on a large change, it's best to open an issue first to discuss it with the maintainers. -MUI is a community project, so Pull Requests are always welcome, but, before working on a large change, it is best to open an issue first to discuss it with the maintainers. - -When in doubt, keep your Pull Requests small. To give a Pull Request the best chance of getting accepted, don't bundle more than one feature or bug fix per Pull Request. It's often best to create two smaller Pull Requests than one big one. +When in doubt, keep your pull requests small. +For the best chances of being accepted, don't bundle more than one feature or bug fix per PR. +It's often best to create two smaller PRs rather than one big one. 1. Fork the repository. -2. Clone the fork to your local machine and add upstream remote: +2. Clone the fork to your local machine and add the upstream remote: ```bash git clone https://github.com//material-ui.git @@ -84,23 +89,23 @@ yarn install git checkout -b my-topic-branch ``` -6. Make changes, commit and push to your fork: +6. Make changes, commit, and push to your fork: ```bash git push -u origin HEAD ``` -7. Go to [the repository](https://github.com/mui/material-ui) and make a Pull Request. +7. Go to [the repository](https://github.com/mui/material-ui) and open a pull request. -The core team is monitoring for Pull Requests. We will review your Pull Request and either merge it, request changes to it, or close it with an explanation. +The core team actively monitors for new pull requests. +We will review your PR and either merge it, request changes to it, or close it with an explanation. ### Trying changes on the documentation site -The documentation site is built with MUI and contains examples of all the components. -This is the best place to experiment with your changes. -It's the local development environment used by the maintainers. +The documentation site is built with Material UI and contains examples of all of the components. +This is the best place to experiment with your changes—it's the local development environment used by the maintainers. -To get started: +To get started, run: ```bash yarn start @@ -111,29 +116,29 @@ Changes to the docs will hot reload the site. ### Trying changes on the playground -While we recommend trying your changes on the documentation site—it's not always ideal. +While we do recommend trying your changes on the documentation site, this is not always ideal. You might face the following problems: -- updating the existing demos prevent you to work in isolation on a single instance of the component -- emptying an existing page to try your changes in isolation lead to a noisy `git diff` -- static linters will report issues that you might not care about. +- Updating the existing demos prevents you from working in isolation on a single instance of the component +- Emptying an existing page to try your changes in isolation leads to a noisy `git diff` +- Static linters may report issues that you might not care about -To solve these problems—you can use the playground: +To avoid these problems, you can use this playground: ```bash yarn docs:create-playground && yarn start ``` -You can now access it locally: http://localhost:3000/playground/. +Access it locally at: http://localhost:3000/playground/. -You can create as many playgrounds as you want by going to the `/docs/pages/playground/` folder and duplicating the index.tsx file with a different name: `.tsx`. -The new playground will be accessible under: `http://localhost:3000/playground/`. +You can create as many playgrounds as you want by going to the `/docs/pages/playground/` folder and duplicating the `index.tsx` file with a different name: `.tsx`. +The new playground will be accessible at: `http://localhost:3000/playground/`. -### How to increase the chance of being accepted? +### How to increase the chances of being accepted -Continuous Integration (CI) runs a series of checks automatically when a Pull Request is opened. If you're -unsure if your changes will pass, you can always open a Pull Request, and the GitHub UI will display a summary -of the results. If any of them fail, refer to [Checks and how to fix them](#checks-and-how-to-fix-them). +Continuous Integration (CI) automatically runs a series of checks when a PR is opened. +If you're unsure whether your changes will pass, you can always open a PR, and the GitHub UI will display a summary of the results. +If any of these checks fail, refer to [Checks and how to fix them](#checks-and-how-to-fix-them). Make sure the following is true: @@ -141,101 +146,108 @@ Make sure the following is true: - The branch is targeted at `master` for ongoing development. All tests are passing. Code that lands in `master` must be compatible with the latest stable release. It may contain additional features but no breaking changes. We should be able to release a new minor version from the tip of `master` at any time. - If a feature is being added: - - If the result was already achievable with the core library, explain why this feature needs to be added to the core. - - If this is a common use case, consider adding an example to the documentation. -- When adding new features or modifying existing ones, please include tests to confirm the new behavior. You can read more about our test setup in our test [README](https://github.com/mui/material-ui/blob/HEAD/test/README.md). -- If props were added or prop types were changed, the TypeScript declarations were updated. -- When submitting a new component, please add it to the [lab](https://github.com/mui/material-ui/tree/HEAD/packages/mui-lab). + - If the result was already achievable with the core library, you've explained why this feature needs to be added to the core. + - If this is a common use case, you've added an example to the documentation. +- If adding new features or modifying existing ones, you've included tests to confirm the new behavior. You can read more about our test setup in our test [README](https://github.com/mui/material-ui/blob/HEAD/test/README.md). +- If props were added or prop types were changed, you've updated the TypeScript declarations. +- If submitting a new component, you've added it to the [lab](https://github.com/mui/material-ui/tree/HEAD/packages/mui-lab). - The branch is not [behind its target branch](https://github.community/t/branch-10-commits-behind/2403). -Because we will only merge a Pull Request for which all tests pass. The following items need to be true: +We will only merge a PR when all tests pass. +The following statements must be true: - The code is formatted. If the code was changed, run `yarn prettier`. - The code is linted. If the code was changed, run `yarn eslint`. -- The code is type-safe. If TypeScript sources/declarations were changed, `yarn typescript` passed. -- The API docs are up-to-date. If API was changed, run `yarn proptypes && yarn docs:api`. -- The demos are up-to-date. If demos were changed, make sure `yarn docs:typescript:formatted` does not introduce changes. See [about writing demos](#3-write-the-content-of-the-demo). -- The Pull Request title follows the pattern `[Component] Imperative commit message`. (See: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) for a great explanation). +- The code is type-safe. If TypeScript sources or declarations were changed, run `yarn typescript` to confirm that the check passes. +- The API docs are up to date. If API was changed, run `yarn proptypes && yarn docs:api`. +- The demos are up to date. If demos were changed, run `yarn docs:typescript:formatted`. See [about writing demos](#3-write-the-content-of-the-demo). +- The pull request title follows the pattern `[product-name][Component] Imperative commit message`. (See: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) for a great explanation). -If you have missed a step, don't worry, the Continuous Integration will run a thorough test on your commits, and the maintainers of the project can assist. +Don't worry if you miss a step—the Continuous Integration will run a thorough set of tests on your commits, and the maintainers of the project can assist you if you run into problems. If your pull request addresses an open issue, make sure to link the PR to that issue. Use any [supported GitHub keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) in the PR description to automatically link them. -This makes it easier to understand where the PR is coming from, and also speeds things up as the issue gets closed when the PR is merged. +This makes it easier to understand where the PR is coming from, and also speeds things up because the issue will be closed automatically when the PR is merged. ### CI checks and how to fix them -If any of the checks fails click on the _Details_ -link and review the logs of the build to find out why it failed. -For CircleCI you need to log in first. +If any of the checks fail, click on the **Details** link and review the logs of the build to find out why it failed. +For CircleCI, you need to log in first. No further permissions are required to view the build logs. -The following section gives an overview of what each check is responsible for. +The following sections give an overview of what each check is responsible for. #### ci/codesandbox -This task should not fail in isolation. It creates multiple sandboxes on CodeSandbox.com that use the version -of MUI that was built from this Pull Request. Use it to test more complex scenarios. +This task creates multiple sandboxes on CodeSandbox.com that use the version of MUI that was built from this pull request. +It should not fail in isolation. +Use it to test more complex scenarios. #### ci/circleci: checkout -A preflight check to see if the dependencies and lockfile are ok. Running `yarn` -and `yarn deduplicate` should fix most of the issues. +This is a preflight check to see if the dependencies and lockfile are ok. +Running `yarn` and `yarn deduplicate` should fix most issues. #### ci/circleci: test_static -Checks code format, and lints the repository. The log of the failed build should explain -how to fix the issues. It also runs commands that generate or change some files -(like `yarn docs:api` for API documentation). If the CI job fails you might need to run them locally and commit the changes. +This checks code format and lints the repository. +The log of the failed build should explain how to fix any issues. +It also runs commands that generate or change some files (like `yarn docs:api` for API documentation). +If the CI job fails, then you most likely need to run the commands that failed locally and commit the changes. #### ci/circleci: test_unit-1 -Runs the unit tests in a `jsdom` environment. If this fails then `yarn test:unit` -should[1](test/README.md#accessibility-tree-exclusion) fail locally as well. You can narrow the scope of tests run with `yarn test:unit --grep ComponentName`. +This runs the unit tests in a `jsdom` environment. +If it fails then `yarn test:unit` should[1](test/README.md#accessibility-tree-exclusion) fail locally as well. +You can narrow the scope of tests run with `yarn test:unit --grep ComponentName`. If `yarn test:unit` passes locally, but fails in CI, consider [Accessibility tree exclusion in CI](test/README.md#accessibility-tree-exclusion). #### ci/circleci: test_browser-1 -Runs the unit tests in multiple browsers (via BrowserStack). The log of the failed -build should list which browsers failed. If Chrome failed then `yarn test:karma` -should[1](test/README.md#accessibility-tree-exclusion) fail locally as well. If other browsers failed debugging might be trickier. +This runs the unit tests in multiple browsers (via BrowserStack). +The log of the failed build should list which browsers failed. +If Chrome failed then `yarn test:karma` should[1](test/README.md#accessibility-tree-exclusion) fail locally as well. +If other browsers failed, then debugging might be trickier. If `yarn test:karma` passes locally, but fails in CI, consider [Accessibility tree exclusion in CI](test/README.md#accessibility-tree-exclusion). #### ci/circleci: test_regression-1 -Renders tests in `test/regressions/tests` and makes screenshots. This step shouldn't -fail if the others pass. Otherwise, a maintainer will take a look. The screenshots -are evaluated in another step. +This renders tests in `test/regressions/tests` and takes screenshots. +This step shouldn't fail if the others pass. +Otherwise, a maintainer will take a look. +The screenshots are evaluated in another step. #### ci/circleci: test_types -Typechecks the repository. The log of the failed build should list all issues. +This typechecks the repository. +The log of the failed build should list any issues. #### ci/circleci: test_bundle_size_monitor -This task is mostly responsible for monitoring the bundle size. It will only report -the size if the change exceeds a certain threshold. If it fails there's usually -something wrong with the way the packages or docs were built. +This task is primarily responsible for monitoring the bundle size. +It will only report the size if the change exceeds a certain threshold. +If it fails, then there's usually something wrong with the way the packages or docs were built. #### argos -Evaluates the screenshots taken in `test/regressions/tests` and fails if it detects -differences. This doesn't necessarily mean your Pull Request will be rejected as a failure -might be intended. Clicking on _Details_ will show you the differences. +This evaluates the screenshots taken in `test/regressions/tests`, and fails if it detects +differences. +This doesn't necessarily mean that your PR will be rejected, as a failure might be intended. +Clicking on **Details** will show you the differences. #### deploy/netlify -Renders a preview of the docs with your changes if it succeeds. Otherwise `yarn docs:build` -or `yarn docs:export` usually fail locally as well. +This renders a preview of the docs with your changes if it succeeds. +Otherwise `yarn docs:build` or `yarn docs:export` usually fail locally as well. #### codecov/project -Monitors coverage of the tests. A reduction in coverage isn't necessarily bad but -it's always appreciated if it can be improved. +This monitors coverage of the tests. +A reduction in coverage isn't necessarily bad, but it's always appreciated if it can be improved. #### Misc -There are various other checks done by Netlify to check the integrity of our docs. Click -on _Details_ to find out more about them. +There are various other checks done by Netlify to validate the integrity of the docs. +Click on **Details** to find out more about them. ### Updating the component API documentation @@ -249,62 +261,63 @@ $ yarn docs:api ### Coding style -Please follow the coding style of the project. MUI uses prettier and eslint, so if possible, enable linting in your editor to get real-time feedback. +Please follow the coding style of the project. +MUI Core projects use prettier and eslint, so if possible, enable linting in your editor to get real-time feedback. - `yarn prettier` reformats the code. -- `yarn eslint` runs manually the linting rules. +- `yarn eslint` runs the linting rules. -Finally, when you submit a Pull Request, they are run again by our continuous integration tools, but hopefully, your code is already clean! +When you submit a PR, these checks are run again by our continuous integration tools, but hopefully your code is already clean! -## How to add a new demo in the documentation +## How to add a new demo to the documentation -If, for example, you want to add new demos for the button component, you have to take the following steps: +The following steps explain how to add a new demo to the docs using the Button component as an example: -### 1. Add a new React component file under the related directory +### 1. Add a new component file to the directory -In this case, you are going to add the new file to the following directory: +Add the new file to the component's corresponding directory... ```bash docs/src/pages/components/buttons/ ``` -and give it a name: `SuperButtons.js`. +...and give it a name: how about `SuperButtons.tsx`? + +### 2. Write the demo code + +MUI Core uses TypeScript to document our components. +We prefer demos written in TS (using the `.tsx` file format). + +After creating a TypeScript demo, run `yarn docs:typescript:formatted` to automatically create the JavaScript version, which is also required. -### 2. Edit the page Markdown file +If you're not familiar with TypeScript, you can write the demo in JavaScript, and a core contributor may help you migrate it to TS. -The Markdown file is the source for the website documentation. So, whatever you wrote there will be reflected on the website. -In this case, the file you need to edit is `docs/src/pages/components/buttons/buttons.md`. +### 3. Edit the page's Markdown file -Changes should only be applied to the English version e.g. only `app-bar.md` and -not `app-bar-de.md`. For contributions concerning translations please read the [section -about translations](#translations). +The Markdown file in the component's respective folder—in this case, `/buttons/buttons.md`—is the source of content for the document. +Any changes you make there will be reflected on the website. + +Add a header and a brief description of the demo and its use case, along with the `"demo"` code snippet to inject it into the page: ```diff +### Super buttons + -+Sometimes, you need a super button to make your app looks **superb**. Yea ... ++To create a super button for a specific use case, add the `super` prop: + +{{"demo": "pages/components/buttons/SuperButtons.js"}} ``` -### 3. Write the content of the demo - -MUI documents how to use this library with TypeScript. - -If you are familiar with this language, write the demo in TypeScript, and only, in a \*.tsx file. -When you're done run `yarn docs:typescript:formatted` to automatically create the JavaScript version. - -If you are not familiar with that language, write the demo in JavaScript, a core contributor might help you to migrate it to TypeScript. +### 4. Submit your PR -### 4. You are done 🎉 +Now you're ready to [open a PR](#sending-a-pull-request) to add your new demo to the docs. -In case you missed something, [we have a real example that can be used as a summary report](https://github.com/mui/material-ui/pull/19582/files). +Check out [this Toggle Button demo PR](https://github.com/mui/material-ui/pull/19582/files) for an example of what your new and edited files should look like when opening your own demo PR. -## How can I use a change that wasn't released yet? +## How can I use a change that hasn't been released yet? -[CodeSandbox CI](https://codesandbox.io/docs/ci) is used to publish a working version of the packages for each pull request, "a preview". +We use [CodeSandbox CI](https://codesandbox.io/docs/ci) to publish a working version of the packages for each pull request as a "preview." -In practice, you can check the CodeSandbox CI status of a pull request to get the URL needed to install these preview packages: +You can check the CodeSandbox CI status of a pull request to get the URL needed to install these preview packages: ```diff diff --git a//package.json b//package.json @@ -320,7 +333,8 @@ index 791a7da1f4..a5db13b414 100644 "@mui/system": "^5.0.0-alpha.16", ``` -Alternatively, you can open the Netlify preview of the documentation, and open any demo in CodeSandbox. The documentation automatically configures the dependencies to use the preview packages. +Alternatively, you can open the Netlify preview of the documentation, and open any demo in CodeSandbox. +The documentation automatically configures the dependencies to use the preview packages. You can also package and test your changes locally. The following example shows how to package `@mui/material`, but you can package any MUI module with this process: @@ -341,12 +355,12 @@ $test-project> npm i ./path-to-file/mui-material-x.x.x.tar.gz > **Note** > -> If you have already installed this package, your changes will not be reflected when you reinstall it. +> If you've already installed this package, your changes will not be reflected when you reinstall it. > As a quick fix, you can temporarily bump the version number in your `package.json` before running `yarn build`. ## Roadmap -To get a sense of where MUI is heading, or for ideas on where you could contribute, take a look at the [roadmap](https://mui.com/material-ui/discover-more/roadmap/). +Learn more about the future of MUI and its products by visiting our [roadmap](https://mui.com/material-ui/discover-more/roadmap/). ## License