Skip to content

Latest commit

 

History

History
143 lines (99 loc) · 8.83 KB

CONTRIBUTING.md

File metadata and controls

143 lines (99 loc) · 8.83 KB

Contributing to Material Components Web (MDC Web)

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:

General Contributing Guidelines

The Material Components contributing policies and procedures can be found in the main Material Components documentation repository’s contributing page.

Development Process

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.

Setting up your development environment

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.json correctly 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 [email protected]:material-components/material-components-web.git  # or a path to your fork
cd material-components-web && npm i

Building Components

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

Running development server

Local development server

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.

App Engine development server

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.

Building MDC Web

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

Linting / Testing / Coverage Enforcement

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

Running Tests across browsers

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:

  1. Sign up for a sauce labs account (choose "Open Sauce" as your selected plan; it's free!)
  2. Download sauce connect for your OS and make sure that the bin folder in the downloaded zip is somewhere on your $PATH.
  3. Navigate to your dashboard, scroll down to where it says "Access Key", and click "Show"
  4. Enter your password when prompted
  5. Copy your access key
  6. 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.

Coding Style

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.

Submitting Pull Requests

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 --rebase instead. 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.