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 npm install
git clone git@github.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
test/unit/with adequate coverage (which we enforce automatically). -
A screenshot test within
test/screenshot/spec/that shows example usage of the component. For more on screenshot tests, please refer to the screenshot testing documentation.
You can find much more information with respect to building components within our authoring components guide
npm start
# open http://localhost:8080
npm start runs a webpack-dev-server instance that starts our screenshot test server. To read more about our screenshot testing framework please see screenshot testing documentation.
MDC_ENV=development npm run build:demos && gcloud app deploy app.yaml --project google.com:mdc-web-dev --version $USER
gcloud app browse
The above script will build and deploy the app to MDC Web's dev server with your userid as its version number, you can switch to your version by prepending $USER-dot- to the URL opened when you run gcloud app browse. This would be helpful if we need to share work-in-progress work within teams and designers.
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
npm run lint:js # Lints javascript using eslint
npm run lint:css # Lints (S)CSS using stylelint
npm run lint # Runs both of the above commands in parallel
npm run fix:js # Runs eslint with the --fix option enabled
npm run fix:css # Runs stylefmt, which helps fix simple stylelint errors
npm run fix # Runs both of the above commands in parallel
npm run test:watch # Runs karma on Chrome, re-running when source files change
npm test # Lints all files, runs karma, runs typescript tests, and then runs coverage enforcement checks.
npm run test:unit # Only runs the karma tests
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:
- Sign up for a sauce labs account (choose "Open Sauce" as your selected plan; it's free!)
- Download sauce connect for your OS and make sure that the
binfolder in the downloaded zip is somewhere on your$PATH. - Navigate to your dashboard, scroll down to where it says "Access Key", and click "Show"
- Enter your password when prompted
- Copy your access key
- Run
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.
Our entire coding style is enforced automatically through the use of linters. Check out our eslint config (heavily influenced by Google's Javascript Styleguide) as well as our stylelint config (heavily annotated, with justifications for each rule) for further details.
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.