Skip to content

Latest commit

 

History

History
135 lines (95 loc) · 6.04 KB

CONTRIBUTING.md

File metadata and controls

135 lines (95 loc) · 6.04 KB
Raw

Contributing

Contributions are welcomed

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

When opening a pull request, please open it as a draft to not auto assign reviewers before you feel the pull request is in a reviewable state.

Adding instrumentations

Check Adding a New Instrumentation for instructions on adding a new instrumentation.

Check How Instrumentations Work for a deep dive into how instrumentations work.

Code contributions

Development environment quick check

Prior to contributing to the project, you can quickly check your development environment using the ./setup.sh command line, and fix any issue found using the Building documentation.

Automatic code formatting

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

We have automatic code formatting enabled in Gradle configuration using Spotless Gradle plugin. Main goal is to avoid extensive reformatting caused by different IDEs having different opinion about how things should be formatted by establishing single point of truth.

To reformat all the files that need reformatting:

./gradlew spotlessApply

To run formatting verify task only:

./gradlew spotlessCheck

IntelliJ IDEA

For IntelliJ IDEA, we suggest the following settings and plugin:

In contrast to the IntelliJ IDEA set up the default JVM to build and run tests from the command line should be Java 8.

  • Use Java 8 to build and run tests:
    Project Structure > Project > SDK > Use a JDK 1.8
  • Configure import formatting:
    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: import layout
  • Google Java Format plugin

Troubleshooting

  • Gradle fails with a "too many open files" error.
    • You can check the ulimit for open files in your current shell by doing ulimit -n and raise it by calling ulimit -n <new number>
More past issues

  • When Gradle is building the project, the error Could not find netty-transport-native-epoll-4.1.43.Final-linux-x86_64.jar is shown.

    • Execute rm -rf ~/.m2/repository/io/netty/netty-transport* in a Terminal and re-build again.

  • IntelliJ 2021.3 complains Failed to find KotlinGradleProjectData for GradleSourceSetData https://youtrack.jetbrains.com/issue/KTIJ-20173

    • Switch to IntelliJ IDEA CE 2021.2.3

  • IntelliJ Gradle fails to import the project with JAVA_11_HOME must be set to build Java 11 code

    • A workaround is to run IntelliJ from terminal with JAVA_11_HOME
    • In order to verify what's visible from IntelliJ use Add Configuration bar and go to Add New -> Gradle -> Environmental Variables

Pull Request Guidelines

Title Format

Pull request titles should briefly describe the proposed changes in a way that makes sense for the users. They should be a sentence starting with an infinitive verb, and avoid using prefixes like [PROD] or PROD - in favor of labels.

Caution

Don't title:

  • Another bug fix: it doesn't describe the change
  • Span sampling bug fix: it doesn't start with an infinite verb
  • Fix off-by-one error from rule parsing: it doesn't make sense for the user
  • [CORE] Fix span sampling rule parsing: it doesn't use label for component tagging
  • Fix span sampling rule parsing when using both remote config and property config: it doesn't fit and will be cut during changelog generation

Tip

Do instead: Fix span sampling rule parsing

Note

If the changes don't make sense for the users, add the tag: no release note label.

Labels

GitHub labels applies to issues and pull requests. They are used to identify the related components using the comp: category or instrumentations using the inst: category.

Both pull requests and issues should be labelled with at least a component or an instrumentation, in addition to the type of changes using the type: category.

Tip

Always add a comp: or inst: label, and a type: label.

Labels are not only used to categorize but also alter the continuous integration behavior:

  • tag: no release note to exclude a pull request from the next release changelog. Use it when changes are not relevant to the users like:
    • Internal features changes
    • Refactoring pull requests
    • CI and build tools improvements
    • Minor changes like typo
  • The run-tests: category to run continuous integration tests on a specific JVM in case of JVM specific changes
  • run-tests: flaky to run the flaky tests on continuous integration as they are disabled by default

Note

For reference, the full list of all labels available. If you feel one is missing, let the maintainer team know!