"Fossies" - the Fresh Open Source Software Archive

Member "material-components-web-14.0.0/CONTRIBUTING.md" (28 Apr 2022, 7728 Bytes) of package /linux/www/material-components-web-14.0.0.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "CONTRIBUTING.md": 11.0.0_vs_12.0.0.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.

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 git@github.com: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:

You can find much more information with respect to building components within our authoring components guide

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

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.