1# How to submit a bug report 2 3If you received an error message, please include it and any exceptions. 4 5We commonly need to know what platform you are on: 6 7* JDK/JRE version (i.e., `java -version`) 8* Operating system (i.e., `uname -a`) 9 10# How to contribute 11 12We definitely welcome patches and contributions to OpenCensus! Here are 13some guidelines and information about how to do so. 14 15## Before getting started 16 17In order to protect both you and ourselves, you will need to sign the 18[Contributor License Agreement](https://cla.developers.google.com/clas). 19 20[Eclipse](https://google-styleguide.googlecode.com/svn/trunk/eclipse-java-google-style.xml) 21and 22[IntelliJ](https://google-styleguide.googlecode.com/svn/trunk/intellij-java-google-style.xml) 23style configurations are commonly useful. For IntelliJ 14, copy the style to 24`~/.IdeaIC14/config/codestyles/`, start IntelliJ, go to File > Settings > Code 25Style, and set the Scheme to `GoogleStyle`. 26 27## Style 28We follow the [Google Java Style 29Guide](https://google.github.io/styleguide/javaguide.html). Our 30build automatically will provide warnings for simple style issues. 31 32Run the following command to format all files. This formatter uses 33[google-java-format](https://github.com/google/google-java-format): 34 35### OS X or Linux 36 37`./gradlew goJF` 38 39### Windows 40 41`gradlew.bat goJF` 42 43We also follow these project-specific guidelines: 44 45### Javadoc 46 47* All public classes and their public and protected methods MUST have javadoc. 48 It MUST be complete (all params documented etc.) Everything else 49 (package-protected classes, private) MAY have javadoc, at the code writer's 50 whim. It does not have to be complete, and reviewers are not allowed to 51 require or disallow it. 52* Each API element should have a `@since` tag specifying the minor version when 53 it was released (or the next minor version). 54* There MUST be NO javadoc errors. 55* See 56 [section 7.3.1](https://google.github.io/styleguide/javaguide.html#s7.3.1-javadoc-exception-self-explanatory) 57 in the guide for exceptions to the Javadoc requirement. 58* Reviewers may request documentation for any element that doesn't require 59 Javadoc, though the style of documentation is up to the author. 60* Try to do the least amount of change when modifying existing documentation. 61 Don't change the style unless you have a good reason. 62 63### AutoValue 64 65* Use [AutoValue](https://github.com/google/auto/tree/master/value), when 66 possible, for any new value classes. Remember to add package-private 67 constructors to all AutoValue classes to prevent classes in other packages 68 from extending them. 69 70## Building opencensus-java 71 72Continuous integration builds the project, runs the tests, and runs multiple 73types of static analysis. 74 75Run the following commands to build, run tests and most static analysis, and 76check formatting: 77 78### OS X or Linux 79 80`./gradlew clean assemble check verGJF` 81 82### Windows 83 84`gradlew.bat clean assemble check verGJF` 85 86Use these commands to run Checker Framework null analysis: 87 88### OS X or Linux 89 90`./gradlew clean assemble -PcheckerFramework` 91 92### Windows 93 94`gradlew.bat clean assemble -PcheckerFramework` 95 96Run the following command to install a local snapshot of OpenCensus. This 97can be a very useful tool for testing changes locally against another 98project that uses OpenCensus. 99 100### OS X or Linux 101 102`./gradlew install` 103 104### Windows 105 106`gradlew.bat install` 107 108### Checker Framework null analysis 109 110OpenCensus uses the [Checker Framework](https://checkerframework.org/) to 111prevent NullPointerExceptions. Since the project uses Java 6, and Java 6 doesn't 112allow annotations on types, all Checker Framework type annotations must be 113[put in comments](https://checkerframework.org/manual/#backward-compatibility). 114Putting all Checker Framework annotations and imports in comments also avoids a 115dependency on the Checker Framework library. 116 117OpenCensus uses `org.checkerframework.checker.nullness.qual.Nullable` for all 118nullable annotations on types, since `javax.annotation.Nullable` cannot be 119applied to types. However, it uses `javax.annotation.Nullable` in API method 120signatures whenever possible, so that the annotations can be uncommented and 121be included in .class files and Javadocs. 122 123### Checkstyle import control 124 125This project uses Checkstyle to specify the allowed dependencies between 126packages, using its ImportControl feature 127(http://checkstyle.sourceforge.net/config_imports.html#ImportControl). 128`buildscripts/import-control.xml` specifies the allowed imports and contains 129some guidelines on OpenCensus' inter-package dependencies. An error messsage 130such as 131`Disallowed import - edu.umd.cs.findbugs.annotations.SuppressFBWarnings. [ImportControl]` 132could mean that `import-control.xml` needs to be updated. 133 134## Benchmarks 135 136### Invoke all benchmarks on a sub-project 137 138```bash 139$ ./gradlew clean :opencensus-impl-core:jmh 140``` 141 142### Invoke on a single benchmark class 143 144```bash 145./gradlew -PjmhIncludeSingleClass=BinaryFormatImplBenchmark clean :opencensus-impl-core:jmh 146``` 147 148### Debug compilation errors 149When you make incompatible changes in the Benchmarks classes you may get compilation errors which 150are related to the old code not being compatible with the new code. Some of the reasons are: 151* Any plugin cannot delete the generated code (jmh generates code) because if the user configured 152the directory as the same as source code the plugin will delete users source code. 153* After you run jmh, a gradle daemon will stay alive which may cache the generated code in memory 154and use use that generated code even if the files were changed. This is an issue for classes 155generated with auto-value. 156 157Run this commands to clean the Gradle's cache: 158```bash 159./gradlew --stop 160rm -fr .gradle/ 161rm -fr benchmarks/build 162``` 163 164## Proposing changes 165 166Create a Pull Request with your changes. Please add any user-visible changes to 167CHANGELOG.md. The continuous integration build will run the tests and static 168analysis. It will also check that the pull request branch has no merge commits. 169When the changes are accepted, they will be merged or cherry-picked by an 170OpenCensus core developer. 171