We'd love for you to contribute and make Material Components for the web even better than it is today! Here are the guidelines we'd like you to follow:
The Material Components contributing policies and procedures can be found in the main Material Components documentation repository’s contributing page.
We strive to make developing Material Components Web as frictionless as possible, both for ourselves and for our community. This section should get you up and running working on the MDC Web codebase. Before beginning development, you may want to read through our overview on architecture and best practices to get a better understanding of our overall structure.
You'll need a recent version of nodejs to work on MDC Web. We test our builds using both the latest and LTS node versions, so use of one of those is recommended. You can use nvm to easily install and manage different versions of node on your system.
NOTE: If you expect to commit updated or new dependencies, please ensure you are using npm 5, which will also update
package-lock.jsoncorrectly when you install or upgrade packages.
Once node is installed, simply clone our repo (or your fork of it) and run
git clone email@example.com:material-components/material-components-web.git # or a path to your fork cd material-components-web && npm i
Each component requires the following items in order to be complete:
An Engineering Outline Document, which should be linked to in a comment on the GitHub issue where we're tracking the component. This way, the core team can review and sign off on the outline doc. Outline docs should be signed off on before submitting a PR. Please copy this google doc template in order to make your outline.
We have found that enforcing an eng outline doc has allowed us to speed up development by offering more informed feedback on component implementations. This results in components that take into account all of the concepts MDC Web components should account for (RTL, a11y, etc.) before they even reach the PR stage, meaning faster review and merge times 😄.
A foundation class which is integrated into actual components
A component class using vanilla JS + SCSS
A README.md in its subdir which contains developer documentation on the component, including usage.
A set of unit tests within
packages/<mdc-component>/test/ with adequate coverage (which we enforce automatically).
You can find much more information with respect to building components within our authoring components guide
npm run build # Cleans out build/ and builds unminified files for each MDC Web package npm run build:min # Builds minified files for each MDC Web package npm run dist # Runs both of the above commands sequentially npm run build:demos # Cleans out build/ and builds demo CSS/JS files, e.g. for deploying to App Engine
If you're making big changes or developing new components, we encourage you to be a good citizen and test your changes across browsers! A super simple way to do this is to use sauce labs, which is how we test our collaborator PRs on TravisCI:
binfolder in the downloaded zip is somewhere on your
SAUCE_USERNAME=<your-saucelabs-username> SAUCE_ACCESS_KEY=<your-saucelabs-access-key> npm test
This will have karma run our unit tests across all browsers we support, and ensure your changes will not introduce regressions.
Alternatively, you can run
npm run test:watch and manually open browsers / use VMs / use emulators to test your changes.
When submitting PRs, make sure you're following our commit message conventions (which are the same as angular's); our `commit-msg` hook should automatically enforce this. We also support commitizen, which you can use to auto-format commit messages for you.
When submitting PRs for large changes, be sure to include an adequate background in the description so that reviewers of the PR know what the changes entail at a high-level, the motivations for making these changes, and what they affect.
If you've done some experimental work on your branch/fork and committed these via
git commit --no-verify, you can rebase them into one correctly-formatted commit before submitting.
Finally, it helps to make sure that your branch/fork is up to date with what's currently on master. You can ensure this by running
git pull --rebase origin master on your branch.
NOTE: Please do not merge master into your branch. Always
pull --rebaseinstead. This ensures a linear history by always putting the work you've done after the work that's already on master, regardless of the date in which those commits were made.