opentelemetry-java-instrumentation/CONTRIBUTING.md

Contributing

Pull requests for bug fixes are welcome, but before submitting new features or changes to current functionality open an issue and discuss your ideas or propose the changes you wish to make. After a resolution is reached a PR can be submitted for review.

Testing

Java versions

Open Telemetry Auto Instrumentation's minimal supported version is java 7. All jar files that we produce, unless noted otherwise, have bytecode compatible with java 7 runtime. In addition to that we test our code with all later java versions as well: from 8 to 14.

Some libraries that we auto-instrument may have higher minimal requirements. In this case we compile and test corresponding auto-instrumentation with higher java version as required by library. The resulting classes will have higher bytecode level, but as it matches library's java version, no runtime problem arise.

Instrumentation tests

Executing ./gradlew instrumentation:test will run tests for all supported auto-instrumentations using that java version which runs the Gradle build itself. These tests usually use the minimal supported version of the instrumented library.

In addition to that each instrumentation has a separate test set called latestDepTest. It was created by Gradle test sets plugin. It uses the very same tests as before, but declares a dynamic dependency on the latest available version of this library. You can run them all by executing ./gradlew latestDepTest.

Executing tests with specific java version

In order to run tests on a specific java version, just execute ./gradlew testJava7 (or testJava11 or latestDepTestJava14 etc). Then Gradle task rule will kick in and do the following:

• check, if Gradle already runs on a java with required version
• if not, look for an environment variable named JAVA_N_HOME, where N is the requested java version
• if Gradle could not found requested java version, then build will fail
• Gradle will now find all corresponding test tasks and configure them to use java executable of the requested version.

This works both for tasks named test and latestDepTest. But currently does not work for other custom test tasks, such as those created by test sets plugin.

Code Style

This project includes a .editorconfig file for basic editor settings. This file is supported by most common text editors.

Java files must be formatted using google-java-format. Please run the following task to ensure files are formatted before committing:

./gradlew googleJavaFormat

Other source files (Groovy, Scala, etc) should ideally be formatted by Intellij Idea's default formatting, but are not enforced.

Intellij IDEA

Required plugins:

• Lombok

Suggested plugins and settings:

• Editor > Code Style > Java/Groovy > Imports
  • Class count to use import with '*': 9999 (some number sufficiently large that is unlikely to matter)
  • Names count to use static import with '*': 9999
  • With java use the following import layout (groovy should still use the default) to ensure consistency with google-java-format:
• Google Java Format
• Save Actions