DEV/material-components_material-components-ios
1
0
Fork 0
mirror of https://github.com/material-components/material-components-ios.git synced 2026-02-20 08:27:32 +08:00
Code Issues Packages Projects Releases Wiki Activity
material-components_materia.../contributing
History

README.md

Want to contribute? Great! First, read this page (including the small print).

Contributing

Material Components for iOS is intended to be a full open source project that accepts contributions from community members. We can work together to optimize material design on iOS.

Community Structure

Members of the core team are engineers from Google, Inc. responsible for the strategic direction of Material Components and appointment of technical leaders from the community. The Core Team will work with the community to accept contributions in line with the material design spec.

Code of Conduct

As contributors and maintainers of the project, we pledge to respect everyone who contributes through posting issues, updating documentation, submitting pull requests, providing feedback in comments and any other related activities.

Communication through any of our material design channels (GitHub, Stack Overflow, 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 and expression, gender identity, sexual orientation, disability, personal appearance, body size, age, race, ethnicity, religion, nationality or level of experience. We expect anyone contributing to the project to do the same. We are committed to making participation in this project a harassment-free experience for everyone.

By adopting this Code of Conduct, community members commit themselves to fairly and consistently applying these principles to every aspect of participating in this project. Community members who do not follow the Code of Conduct may be permanently removed from the project.

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

If any member of the community violates this code of conduct, the maintainers of the project may take action, removing issues, comments, and pull requests or blocking accounts as deemed appropriate.

If you are subject to or witness unacceptable behavior, or have any other concerns, please email us at material-components-ios-discuss@googlegroups.com.

Examples of behavior that contributes to creating a positive environment include:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

  • The use of sexualized language or imagery and unwelcome sexual attention or advances
  • Trolling, insulting/derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or electronic address, without explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

This code of conduct was adapted from the following sources:

Questions?

If you have questions about how to use Material Components for iOS:

  • Search previous questions that have been answered by visiting Stack Overflow.
  • Please post questions to Stack Overflow with the tag material-components-ios.

Found an Issue?

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: send a fix as a pull request!

Feature Request?

You can request a new feature by submitting an issue to our GitHub repository. If you would like to implement a new feature then consider what kind of change it is:

Submitting an Issue

Before you submit your issue search the archive in case your question has already been answered. If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues. Providing the following information will increase the chances of your issue being dealt with quickly:

  • Overview of the issue - if an error is being thrown a stack trace helps
  • Motivation and context - explain why this is a bug for you
  • Version number - this will help us identify where fixes should be made
  • Operating system and hardware - which version of iOS and the hardware being run on
  • Reproduction steps - was it just a one time error or can you show the steps to reproduce?
  • Related issues - has a similar issue been reported before?

Here is a great example of a well defined issue in angular.js.

Signing the CLA

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!

Pull requests

For major changes, it's worthwhile discussing the idea on our mailing list—that way you'll get early feedback on your idea and find out if the approach has been tried before or if someone else is working on it. Search our GitHub issues to see if anyone has proposed the idea before, too. Feature requests and bug fixes should be tracked with issues, so file one early on and assign it to yourself once you have started it.

Conventions

MDC follows certain coding styles and conventions for its code to help everyone easily read, review, and understand our code. Please follow these conventions when submitting pull requests.

Tips for a good pull request

Pull requests can be hard to review if they try to tackle too many things at once. Phabricator's "Writing Reviewable Code" provides a set of guidelines that help increase the likelihood of your pull request getting merged.

In short (slightly modified from the original article):

  • A pull request should be as small as possible, but no smaller.
  • The smallest a pull request can be is a single cohesive idea: don't make pull requests so small that they are meaningless on their own.
  • Turn large pull requests into small pull requests by dividing large problems into smaller problems and solving the small problems one at a time.
  • Write sensible pull request descriptions.

Our additions:

  • A pull request should affect as few components as possible.
  • Pull requests must include a modification to the CHANGELOG.md summarizing the change.

Before you contribute

Before we can use your code, you must sign the Google Individual Contributor License Agreement (CLA), which you can do online. The CLA is necessary mainly because you own the copyright to your changes, even after your contribution becomes part of our codebase, so we need your permission to use and distribute your code. We also need to be sure of various other things—for instance that you'll tell us if you know that your code infringes on other people's patents. You don't have to sign the CLA until after you've submitted your code for review and a member has approved it, but you must do it before we can put your code into our codebase. Before you start working on a larger contribution, you should get in touch with us first through the issue tracker with your idea so that we can help out and possibly guide you. Coordinating up front makes it much easier to avoid frustration later on.

Code reviews

All submissions, including submissions by project members, require review. We allow pull requests to be filed, but we perform code reviews on codereview.cc.

The small print

Contributions made by corporations are covered by a different agreement than the one above, the Software Grant and Corporate Contributor License Agreement.

Submitting a Pull Request

Once you have code that is ready to share, please create a pull request against our GitHub repo. See GitHub's documentation about pull requests for more information.

Subject Format

We use a simple format for titles:

  • Start the title with [ComponentName] to identify which component a change affects. Use [ComponentName|OtherComponentName] for commits affecting multiple components, which should be rare.
  • Use [ComponentName]! to indicate that a change introduce a breakage: removing/renaming an element of the public API.
  • Use [ComponentName]? to indicate that a change (deliberately) introduces warnings. For example when we mark an API deprecated.

A good example of a title is:

[FooBar]! Removes the deprecated fooWithBar:(Bar*)bar method.

When referencing GitHub issues, use the full URL: https://github.com/material-components/material-components-ios/issues/nnn instead of the shorthand #nnn.

Pull requests will be reviewed in Phabricator's Differential code review tool instead of directly in GitHub. When you submit your pull request, a bot will reply with a link to the code review discussion. If you haven't done so before, create a new account on Phabricator and join the discussion of your changes.

Component checklist

This checklist describes the process by which Material components are built.

API review

API reviews work like typical code reviews with the added constraint of only reviewing the component's public APIs.

To initiate an API review, send a pull request that only includes the public APIs you wish to review.

TODO(featherless): Flesh this out with some concrete examples of existing API reviews.

License

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses

https://github.com/material-components/material-components-ios/blob/develop/LICENSE

Copyright and License in Source Code

All source files hosted on Material Components for iOS GitHub repo must contain a comment block at the top of the file declaring the license and copyright that applies. This text may be part of a larger header. The wording for the license and copyright portion must be copied as follows, with the appropriate years applied:


Copyright 2016-present the Material Components for iOS authors. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.