If you received an error message, please include it and any exceptions.
We commonly need to know what platform you are on:
We definitely welcome patches and contributions to OpenCensus! Here are some guidelines and information about how to do so.
In order to protect both you and ourselves, you will need to sign the Contributor License Agreement.
Eclipse and IntelliJ style configurations are commonly useful. For IntelliJ 14, copy the style to
~/.IdeaIC14/config/codestyles/, start IntelliJ, go to File > Settings > Code Style, and set the Scheme to
We follow the Google Java Style Guide. Our build automatically will provide warnings for simple style issues.
Run the following command to format all files. This formatter uses google-java-format:
We also follow these project-specific guidelines:
@sincetag specifying the minor version when it was released (or the next minor version).
Continuous integration builds the project, runs the tests, and runs multiple types of static analysis.
Run the following commands to build, run tests and most static analysis, and check formatting:
./gradlew clean assemble check verGJF
gradlew.bat clean assemble check verGJF
Use these commands to run Checker Framework null analysis:
./gradlew clean assemble -PcheckerFramework
gradlew.bat clean assemble -PcheckerFramework
OpenCensus uses the Checker Framework to prevent NullPointerExceptions. Since the project uses Java 6, and Java 6 doesn't allow annotations on types, all Checker Framework type annotations must be put in comments. Putting all Checker Framework annotations and imports in comments also avoids a dependency on the Checker Framework library.
org.checkerframework.checker.nullness.qual.Nullable for all nullable annotations on types, since
javax.annotation.Nullable cannot be applied to types. However, it uses
javax.annotation.Nullable in API method signatures whenever possible, so that the annotations can be uncommented and be included in .class files and Javadocs.
This project uses Checkstyle to specify the allowed dependencies between packages, using its ImportControl feature (http://checkstyle.sourceforge.net/config_imports.html#ImportControl).
buildscripts/import-control.xml specifies the allowed imports and contains some guidelines on OpenCensus' inter-package dependencies. An error messsage such as
Disallowed import - edu.umd.cs.findbugs.annotations.SuppressFBWarnings. [ImportControl] could mean that
import-control.xml needs to be updated.
$ ./gradlew clean :opencensus-impl-core:jmh
./gradlew -PjmhIncludeSingleClass=BinaryFormatImplBenchmark clean :opencensus-impl-core:jmh
When you make incompatible changes in the Benchmarks classes you may get compilation errors which are related to the old code not being compatible with the new code. Some of the reasons are:
Run this commands to clean the Gradle's cache:
./gradlew --stop rm -fr .gradle/ rm -fr benchmarks/build
Create a Pull Request with your changes. Please add any user-visible changes to CHANGELOG.md. The continuous integration build will run the tests and static analysis. It will also check that the pull request branch has no merge commits. When the changes are accepted, they will be merged or cherry-picked by an OpenCensus core developer.