Permalink
2ea3f4f Mar 9, 2018
3 contributors

Users who have contributed to this file

@xian @pjdelport @ngbravo
71 lines (43 sloc) 3.7 KB
title group order toc
Contributor Guidelines
Contributing
1
true

Contributor Guidelines

Getting Started

Dependencies:

  • Android SDK with Tools, Extras, and 'Google APIs' for latest API level installed.

Set Android environment variables:

export ANDROID_HOME=/path-to-sdk-root
export PATH=${PATH}:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

Fork and clone the repo:

git clone git@github.com:username/robolectric.git

Create a feature branch to make your changes:

git checkout -b my-feature-name

Copy all required Android dependencies to your local Maven repository:

./scripts/install-dependencies.rb

Perform a full build of all shadows:

./gradlew clean assemble install compileTest

We develop Robolectric on Mac and Linux. You might be able to figure out how to get it to work on Windows if you really want to for some reason. Good luck.

Contribution Requirements

Code Style

Essentially the IntelliJ default Java style, but with two-space indents and Google-style imports.

  1. Spaces, not tabs.
  2. Two space indent.
  3. Curly braces for everything: if, else, etc.
  4. One line of white space between methods.
  5. No 'm' or 's' prefixes before instance or static variables.
  6. Import Google's java imports style (IntelliJ style file here).

Writing Tests

Robolectric is a unit testing framework and it is important that Robolectric itself be very well tested. All classes should have unit test classes. All public methods should have unit tests. Those classes and methods should have their possible states well tested. Pull requests without tests will be sent back to the submitter.

Documentation

Robolectric uses Markdown Doclet, so write javadoc using markdown, with javadoc tag extensions.

For developers with the Robolectric Chrome Extension installed, javadoc on Robolectric shadow classes and methods are inserted into developer.android.com sections for the classes and methods they shadow, and identified as Robolectric-related testing notes. Javadoc on visible, non-@Implementation methods on shadow classes are displayed in a new 'Testing APIs' section for the shadowed class.

There are special rules for javadoc on shadow classes to support the Robolectric Chrome Extension:

  • All @Implementation methods whose behavior varies from the standard Android behavior MUST have Javadoc describing the difference. Use @see or {@link} to indicate if the method's behavior can be changed or inspected by calling testing API methods. If the method's behavior is identical to the normal framework behavior, no javadoc is necessary.
  • All visible non-@Implementation methods SHOULD have descriptive Javadoc.
  • Don't write javadoc comments like "Shadow for (whatever).". The javadoc will appear in a section clearly related to testing, so make it make sense in context.

Deprecations and Backwards Compatibility

To provide an easy upgrade path, we aim to always mark methods or classes @Deprecated in at least a patch release before removing them in the next minor release. We realize that's not quite how Semantic Versioning is supposed to work, sorry. Be sure to include migration notes in the /** @deprecated */ javadoc!