Skip to content

Latest commit

 

History

History
95 lines (79 loc) · 5.9 KB

CONTRIBUTING.md

File metadata and controls

95 lines (79 loc) · 5.9 KB
Raw

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

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 use Github pull requests for this purpose.

The submitted code should adhere to the following:

Do's

  • Keep pull requests focused on addressing one issue or feature. If multiple separate issues are fixed by a pull request, prefer committing the fixes under multiple commits, one for each issue.
  • A Pull Request must have a Github Issue filed for it except in the case of trivial spelling/formatting fixes. For a Pull Request without a corresponding issue, please create the issue first and discuss it with the community to ascertain the severity of the issue. This allows us to prioritize your Pull Request and focus on the most pressing issues at hand. Without a proper context for why the change is being made, we cannot guarantee an expedient review or a merge.
  • Before submitting any code changes, please ensure that the Unit Tests and Functional Tests projects build and all tests pass. If you believe that the test failures are due to bugs in the framework then please file an issue.
  • If a pull request looks good then we'll wait for Travis to run all the Unit and Functional tests on the changes. We also trigger an internal test to check for further breakages. For each stage, appropriate labels will be set on the pull request. In case any of the tests are broken, we will let you know.
  • If your pull request does not touch any code, then you could skip the Travis Continuous Integration check by adding [ci skip] to your git commit message. This helps prevent over-encumbering the CI.
  • Any PR marked as experiment will not be merged. You can indicate that either in the title of the PR or by labelling the PR with experiment. Use it to share a prototype for which you want to get more feedback from the core team.
  • If a new custom API is being proposed to be added to EarlGrey, but is still in the experimental phase, then please add it to the EarlGreyContribs project for vetting out. Also, any example code that is added must first be vetted in the EarlGreyContribs project.
  • Please use Github's Markdown Formatting for formatting your comments and issues.
  • Refer to the Google Objective-C style guide and the Google Swift style guide for our code conventions.

Don'ts

  • Consider not adding LGTM's or +1's unless you're specifically asked to do so, since they add noise to the conversation.
  • Refrain from providing small and granular pull requests for changes that could easily be consolidated into one.
  • A vague description for a pull request adds to the review time because we now have to analyze what the code does. A more descriptive description will help the reviewers understand what they're reviewing.
  • Refrain from sending us a pull request with a large refactor / feature change with a vague/negligible description or no issue attached.

Github Issues

Do's

  • Ensure you've searched extensively through the documentation before filing a Github Issue. As a developer, please provide us issue descriptions that you yourself would like to read.
  • Please be as verbose in your comments and descriptions as possible. For each issue, add in the type of project, language used, Xcode version, error trace etc. While we love the fact that you're helping us improve the project, it would be nice for us not to have to ask for debugging clarifications for every issue created.
  • For in-depth discussions please use the EarlGrey Google Group instead of starting a Github Issue.
  • In case of an API update, please make sure the changes are documented in the cheatsheet.html file. The PDF and .PNG cheatsheet files are to be updated only when we update the EarlGrey CocoaPod.

Don'ts

  • Any vaguely worded issue will be immediately closed.
  • If there is inactivity on an issue for an extended period of time, it will be closed. Please update the issue and reopen it in case you find that it still persists.

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.