1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
# How to submit a bug report
If you received an error message, please include it and any exceptions.
We commonly need to know what platform you are on:
* JDK/JRE version (i.e., `java -version`)
* Operating system (i.e., `uname -a`)
# How to contribute
We definitely welcome patches and contributions to OpenCensus! Here are
some guidelines and information about how to do so.
## Before getting started
In order to protect both you and ourselves, you will need to sign the
[Contributor License Agreement](https://cla.developers.google.com/clas).
[Eclipse](https://google-styleguide.googlecode.com/svn/trunk/eclipse-java-google-style.xml)
and
[IntelliJ](https://google-styleguide.googlecode.com/svn/trunk/intellij-java-google-style.xml)
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 `GoogleStyle`.
## Style
We follow the [Google Java Style
Guide](https://google.github.io/styleguide/javaguide.html). Our
build automatically will provide warnings for simple style issues.
Run the following command to format all files. This formatter uses
[google-java-format](https://github.com/google/google-java-format):
### OS X or Linux
`./gradlew goJF`
### Windows
`gradlew.bat goJF`
We also follow these project-specific guidelines:
### Javadoc
* All public classes and their public and protected methods MUST have javadoc.
It MUST be complete (all params documented etc.) Everything else
(package-protected classes, private) MAY have javadoc, at the code writer's
whim. It does not have to be complete, and reviewers are not allowed to
require or disallow it.
* Each API element should have a `@since` tag specifying the minor version when
it was released (or the next minor version).
* There MUST be NO javadoc errors.
* See
[section 7.3.1](https://google.github.io/styleguide/javaguide.html#s7.3.1-javadoc-exception-self-explanatory)
in the guide for exceptions to the Javadoc requirement.
* Reviewers may request documentation for any element that doesn't require
Javadoc, though the style of documentation is up to the author.
* Try to do the least amount of change when modifying existing documentation.
Don't change the style unless you have a good reason.
### AutoValue
* Use [AutoValue](https://github.com/google/auto/tree/master/value), when
possible, for any new value classes. Remember to add package-private
constructors to all AutoValue classes to prevent classes in other packages
from extending them.
## Building opencensus-java
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:
### OS X or Linux
`./gradlew clean assemble check verGJF`
### Windows
`gradlew.bat clean assemble check verGJF`
Use these commands to run Checker Framework null analysis:
### OS X or Linux
`./gradlew clean assemble -PcheckerFramework`
### Windows
`gradlew.bat clean assemble -PcheckerFramework`
### Checker Framework null analysis
OpenCensus uses the [Checker Framework](https://checkerframework.org/) 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](https://checkerframework.org/manual/#backward-compatibility).
Putting all Checker Framework annotations and imports in comments also avoids a
dependency on the Checker Framework library.
OpenCensus uses `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.
### Checkstyle import control
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.
## Benchmarks
### Invoke all benchmarks on a sub-project
```bash
$ ./gradlew clean :opencensus-impl-core:jmh
```
### Invoke on a single benchmark class
```bash
./gradlew -PjmhIncludeSingleClass=BinaryFormatImplBenchmark clean :opencensus-impl-core:jmh
```
### Debug compilation errors
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:
* Any plugin cannot delete the generated code (jmh generates code) because if the user configured
the directory as the same as source code the plugin will delete users source code.
* After you run jmh, a gradle daemon will stay alive which may cache the generated code in memory
and use use that generated code even if the files were changed. This is an issue for classes
generated with auto-value.
Run this commands to clean the Gradle's cache:
```bash
./gradlew --stop
rm -fr .gradle/
rm -fr benchmarks/build
```
## Proposing changes
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.
|
