Skip to content

Latest commit

 

History

History
148 lines (101 loc) · 6.84 KB

CONTRIBUTING.md

File metadata and controls

148 lines (101 loc) · 6.84 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.

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

Draft first

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.

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!

Pull Request Reviews

Review Expectations

After making you pull request ready for review by converting it from draft, you can expect getting an initial review comment within two working days, and a full review within a week of work. If you don't receive any update, feel free to send a nice reminder to the assigned reviewers using pull request comments or our internal Slack channel.

Stale Pull Requests

A pull request is considered "stale" if it has had no activity (comments, updates) for the last quarter. Stale PRs will be commented and labelled as such (using the tag: stale label), then closed if they still receive no update for a week after.

Closed PRs can be reopened at any time, but may be closed again if they ever meet the same stale conditions.