The first step to contributing is to ensure that you are able to build Robolectric. Please visit building Robolectric for more details and instructions on setting up an environment to build Robolectric.
Once you are able to build Robolectric, create a feature branch to make your changes:
git checkout -b my-feature-name
Robolectric is built using Gradle. It is recommended to use Android Studio or IntelliJ to import the top-level build.gradle.kts
file, which will automatically generate their project files from it.
Essentially the Android Studio/IntelliJ default Java style, but with two-space indents and Google-style imports.
if
, else
, etc.'m'
or 's'
prefixes before instance or static variables.If your changes break the code style, the CI will fail, and your PR will be blocked. You can use google-java-format
to format your code locally before you push your changes for reviewing. The wiki's Running Google java format
section is a tutorial for it.
Robolectric uses Spotless + ktfmt to apply Google's code style for Kotlin. Please follow wiki's Robolectric's code style
section to apply Kotlin format for Kotlin modules and code.
Robolectric is a unit testing framework, and it is important that Robolectric itself is 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.
If the change is related to third-party tool, e.g., Mockito and Mockk, please consider creating a dedicated module in Robolectric's integration_tests
module to test third-party tool's regression.
If tests need to check that an exception is thrown, use jUnit's assertThrows
instead of @Test(expected = SomeException.class)
. Using assertThrows
allows more precision to check exactly which line throws a particular exception.
Robolectric uses javadoc to document API's behavior. There are special rules for javadoc on shadow classes:
@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.@Implementation
methods SHOULD have descriptive Javadoc.Robolectric will release javadoc at https://robolectric.org/ after every main version released. For example, Robolectric's 4.13 javadoc is released at https://robolectric.org/javadoc/4.13/.
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!
Once your changes are ready, tested, and documented, you can submit them in a Pull Request targeting the master
branch. Some automated checks will be executed against your PR to ensure that it adheres to Robolectric's quality requirements:
Robolectric welcome discussion in the entire contribution cycle. If you have any idea or question, you can post on GitHub Discussion or Google Groups. The GitHub Discussion is the first choice for discussion if you have GitHub account, because it can help to accumulate community knowledge along with existing GitHub issues.