Skip to content

Latest commit

 

History

History
90 lines (63 loc) · 3.04 KB

CONTRIBUTING.md

File metadata and controls

90 lines (63 loc) · 3.04 KB
Raw

Contributing

Welcome to OpenTelemetry Java repository!

Before you start - see OpenTelemetry general contributing requirements and recommendations.

If you want to add new features or change behavior, please make sure your changes follow the OpenTelemetry Specification. Otherwise file an issue or submit a PR to the specification repo first.

Make sure to review the projects license and sign the CNCF CLA. A signed CLA will be enforced by an automatic check once you submit a PR, but you can also sign it after opening your PR.

Style guideline

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:

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 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.
$ git checkout -b docs
$ ./gradlew javadoc
$ rm -fr docs/*
$ cp -R api/build/docs/javadoc/* docs
$ git add -A .
$ git commit -m "Update javadoc for API."

AutoValue

  • Use AutoValue, 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 opentelemetry-java

Continuous integration builds the project, runs the tests, and runs multiple types of static analysis.

  1. Note: Currently, to run the full suite of tests, you'll need to be running a docker daemon.

  2. From the root project directory, initialize repository dependencies

    make init-git-submodules

  3. Run the following commands to build, run tests and most static analysis, and check formatting:

    OS X or Linux

    make test verify-format

    Windows

    gradlew.bat clean assemble check verGJF