We'd love for you to contribute to our source code and to make Material Design Lite even better than it is today! Here are the guidelines we'd like you to follow:
- Code of Conduct
- Development Process
- Questions / Problems
- Issues / Bugs
- "What's the core team up to?"
As contributors and maintainers of the Material Design Lite project, we pledge to respect everyone who contributes by posting issues, updating documentation, submitting pull requests, providing feedback in comments, and any other activities.
Communication through any of Material Design Lite's channels (GitHub, StackOverflow, Google+, Twitter, etc.) must be constructive and never resort to personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, disability, age, race, ethnicity, religion, or level of experience. We expect anyone contributing to the Material Design Lite project to do the same.
If any member of the community violates this code of conduct, the maintainers of the Material Design Lite project may take action, removing issues, comments, and PRs or blocking accounts as deemed appropriate.
If you are subject to or witness unacceptable behavior, or have any other concerns, please drop us a line at [email protected].
NOTE: As we are still in pre-alpha for v2, this section may be incomplete, in flux, and/or lacking some info. We hope to stabilize it by the time we reach alpha. If you have additional follow-up questions about our development process or find something confusing / ambiguous, reach out to us on gitter and we may be able to help.
We strive to make developing Material Design Lite as frictionless as possible, both for ourselves and for our community. This section should get you up and running working on the Material Design Lite codebase. Before beginning development, you may want to read through our brief v2 developer guide to get a better understanding of our overall architecture.
You'll need a recent version of nodejs to work on MDL. 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.
Once node is installed, simply clone our repo (or your fork of it) and run npm install
git clone [email protected]:google/material-design-lite.git # or a path to your fork
cd material-design-lite && npm i
Each component requires the following items in order to be complete:
- 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 demo page within
demos/that shows example usage of the component.
npm run dev
open http://localhost:8080
npm run dev runs a webpack-dev-server instance that uses demos/ as its content base. This should aid you in initial development of a component. It's served on port 8080.
npm run build # Builds an unminified version of MDL within build/
npm run build:min # Same as above, but enables minification
npm run dist # Cleans out build/ and runs both of the above commands sequentially
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, and then runs coverage enforcement checks.
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 tests 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.
Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code changes to be accepted, the CLA must be signed. It's a quick process, we promise!
- For individuals we have a simple click-through form.
- For corporations we'll need you to print, sign and one of scan+email, fax or mail the form.
We prefer small, incremental changes over large, sweeping ones, so please try to adhere to this when submitting PRs. Also, 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.
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.
To submit code for v2, open a PR for your fork/branch against master (not mdl-1.x, which is currently our default branch).
Once you've submitted a PR, it'll be assigned to a core team member for review. If all CI tests pass and you get a LGTM from a reviewer, your code will be merged into master.
If you have questions about how to use Material Design Lite, please direct these to StackOverflow and use the material-design-lite tag.
If you feel that we're missing an important bit of documentation, feel free to file an issue so we can help. Here's an example to get you started:
Component (if any):
What are you trying to do or find out more about?
Where have you looked?
Where did you expect to find this information?
If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix. Before submitting issues, please ensure that you've read through our issue template to ensure a fast and helpful response from the maintainers.
The core team maintains a public Pivotal Tracker (tracker for short) which details all the items we're working on within our current two-week iteration. This tracker mirrors in what's in our GH issues. It is used purely for planning and prioritization purposes, not for discussions or community issue filing. That being said, it's a great place to look at the overall state of our project as well as some the big ticket issues we're working on.
Each tracker story contains a link to its corresponding GH issue within its description. Each GH issue present in tracker is tagged with an in-tracker label. This will hopefully make it easy to move between the two if so desired.