From 470ff9a5f9e28b963ef53becf94348df65da7db6 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Tue, 4 Feb 2025 18:35:55 +0100 Subject: [PATCH 1/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 170 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 169 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a493b9..c7534b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,170 @@ -## Project setup +# Contributing to OpenTelemetry Proto Java + +## Introduction + +Welcome to the OpenTelemetry Proto Java repository! πŸŽ‰ + +Thank you for considering contributing to this project. Whether you are fixing a bug, adding new features, improving documentation, or reporting an issue, your contributions help enhance the OpenTelemetry ecosystem. + +This repository provides Java bindings for OpenTelemetry protocol (OTLP) by generating code from the OpenTelemetry protocol definitions. + +If you have any questions, feel free to ask in the community channels. We’re happy to help! 😊 + + +## Pre-requisites + +Before getting started, ensure you have the following installed: + +- **JDK 11 or higher** – [Install OpenJDK](https://adoptopenjdk.net/) +- **Gradle** – [Install Gradle](https://gradle.org/install/) +- **Docker** (optional, for testing) + +Additional Notes: +- Ensure your JAVA_HOME is correctly set. +- Consider using a Gradle wrapper (`./gradlew`) instead of a system-wide Gradle installation. + + +## Workflow + +We follow a structured workflow to ensure smooth collaboration: + +### Branch Naming Convention +- **Feature branches**: `feature/` +- **Bugfix branches**: `fix/` +- **Documentation updates**: `docs/` + +### Commit Message Format +- Use descriptive commit messages (e.g., `fix(telemetry): resolve serialization issue`) +- Follow [Conventional Commits](https://www.conventionalcommits.org/) where possible. + +### Pull Request Guidelines +- Fork the repository and create a new branch. +- Follow the coding guidelines before submitting your PR. +- Ensure tests pass locally before pushing. +- Link relevant issues in the PR description. + +## Local Run/Build + +To set up your local development environment: + +```bash +# Clone the repository +git clone https://github.com/open-telemetry/opentelemetry-proto-java.git +cd opentelemetry-proto-java +``` + +### Building the Project + +To build the project and generate Java bindings from the OpenTelemetry proto definitions: + +```bash +./gradlew build +``` + +By default, the proto definitions will be downloaded from the latest published tag of `opentelemetry-proto-java`. + +If the latest version is, for example, `0.20.0`, the protos will be downloaded from the `v0.20.0` release. + +To override this and specify a different version: + +```bash +./gradlew build -Prelease.version.prop=1.0.0 +``` + +--- + +## Testing + +To run tests: + +```bash +./gradlew test +``` + +To run a specific test: + +```bash +./gradlew test --tests com.example.SomeTest +``` + +To generate a coverage report: + +```bash +./gradlew jacocoTestReport +``` + +--- + +## Contributing Rules + +- Follow [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). +- Ensure new features have appropriate test coverage. +- Run `./gradlew check` before submitting a PR. +- Include clear and concise documentation updates if needed. + +Check for issues labeled [`good first issue`](https://github.com/open-telemetry/opentelemetry-proto-java/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to start contributing. + +--- + +## Further Help + +Need help? Join our community: + +- **Slack**: [OpenTelemetry Slack](https://opentelemetry.io/community/) +- **GitHub Discussions**: [OpenTelemetry Java Discussions](https://github.com/open-telemetry/opentelemetry-java/discussions) +- **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-proto-java/issues) + +--- + +## Troubleshooting Guide + +### Common Issues & Fixes + +#### 1. Build fails due to missing dependencies +**Error:** `Could not resolve dependencies` + +**Fix:** Run: +```bash +./gradlew build --refresh-dependencies +``` + +#### 2. Gradle build issues +**Error:** `Could not find org.openjdk.tools:jdk.tools` + +**Fix:** Ensure JAVA_HOME is correctly set: +```bash +export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which javac)))) +``` + +#### 3. Tests failing +**Error:** `Test XYZ failed` + +**Fix:** +```bash +./gradlew test --info +``` +Check logs and rerun the failing test with: +```bash +./gradlew test --tests com.example.FailingTest +``` + +--- + +## Additional Information + +### Dependency Updates +To check for outdated dependencies: +```bash +./gradlew dependencyUpdates +``` + +### Publishing to Maven Local +To publish artifacts to your local Maven repository: +```bash +./gradlew publishToMavenLocal +``` + +### Project setup The build downloads proto definitions from [open-telemetry/opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto) and @@ -19,3 +185,5 @@ with `-Prelease.version.prop`: ```shell ./gradlew build -Prelease.version.prop=1.0.0 ``` + +Thank you for contributing! πŸš€ From ad4acea57bc981e5639fc81bd1a2a132aabc3273 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Tue, 11 Feb 2025 12:32:03 +0100 Subject: [PATCH 2/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7534b3..439f52d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,20 +23,6 @@ Additional Notes: - Ensure your JAVA_HOME is correctly set. - Consider using a Gradle wrapper (`./gradlew`) instead of a system-wide Gradle installation. - -## Workflow - -We follow a structured workflow to ensure smooth collaboration: - -### Branch Naming Convention -- **Feature branches**: `feature/` -- **Bugfix branches**: `fix/` -- **Documentation updates**: `docs/` - -### Commit Message Format -- Use descriptive commit messages (e.g., `fix(telemetry): resolve serialization issue`) -- Follow [Conventional Commits](https://www.conventionalcommits.org/) where possible. - ### Pull Request Guidelines - Fork the repository and create a new branch. - Follow the coding guidelines before submitting your PR. From ec6d0c12271430c59c2ca7a77e058af678765f34 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Tue, 11 Feb 2025 17:19:26 +0100 Subject: [PATCH 3/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 38 +++++++++----------------------------- 1 file changed, 9 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 439f52d..4df377c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,19 +15,13 @@ If you have any questions, feel free to ask in the community channels. We’re h Before getting started, ensure you have the following installed: -- **JDK 11 or higher** – [Install OpenJDK](https://adoptopenjdk.net/) -- **Gradle** – [Install Gradle](https://gradle.org/install/) -- **Docker** (optional, for testing) +* **JDK 11 or higher** – [Install OpenJDK](https://adoptopenjdk.net/) +* **Gradle** – [Install Gradle](https://gradle.org/install/) +* **Docker** (optional, for testing) Additional Notes: -- Ensure your JAVA_HOME is correctly set. -- Consider using a Gradle wrapper (`./gradlew`) instead of a system-wide Gradle installation. - -### Pull Request Guidelines -- Fork the repository and create a new branch. -- Follow the coding guidelines before submitting your PR. -- Ensure tests pass locally before pushing. -- Link relevant issues in the PR description. +* Ensure your JAVA_HOME is correctly set. +* Consider using a Gradle wrapper (`./gradlew`) instead of a system-wide Gradle installation. ## Local Run/Build @@ -57,8 +51,6 @@ To override this and specify a different version: ./gradlew build -Prelease.version.prop=1.0.0 ``` ---- - ## Testing To run tests: @@ -79,8 +71,6 @@ To generate a coverage report: ./gradlew jacocoTestReport ``` ---- - ## Contributing Rules - Follow [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). @@ -90,7 +80,6 @@ To generate a coverage report: Check for issues labeled [`good first issue`](https://github.com/open-telemetry/opentelemetry-proto-java/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to start contributing. ---- ## Further Help @@ -100,13 +89,13 @@ Need help? Join our community: - **GitHub Discussions**: [OpenTelemetry Java Discussions](https://github.com/open-telemetry/opentelemetry-java/discussions) - **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-proto-java/issues) ---- + ## Troubleshooting Guide ### Common Issues & Fixes -#### 1. Build fails due to missing dependencies +#### Build fails due to missing dependencies **Error:** `Could not resolve dependencies` **Fix:** Run: @@ -114,15 +103,7 @@ Need help? Join our community: ./gradlew build --refresh-dependencies ``` -#### 2. Gradle build issues -**Error:** `Could not find org.openjdk.tools:jdk.tools` - -**Fix:** Ensure JAVA_HOME is correctly set: -```bash -export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which javac)))) -``` - -#### 3. Tests failing +#### Tests failing **Error:** `Test XYZ failed` **Fix:** @@ -134,7 +115,6 @@ Check logs and rerun the failing test with: ./gradlew test --tests com.example.FailingTest ``` ---- ## Additional Information @@ -172,4 +152,4 @@ with `-Prelease.version.prop`: ./gradlew build -Prelease.version.prop=1.0.0 ``` -Thank you for contributing! πŸš€ +Thank you for contributing! From efd553cc5a962551f9467bc416dee8dc8cc8ac73 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Mon, 17 Feb 2025 16:44:48 +0100 Subject: [PATCH 4/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4df377c..6dbccc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,14 +25,6 @@ Additional Notes: ## Local Run/Build -To set up your local development environment: - -```bash -# Clone the repository -git clone https://github.com/open-telemetry/opentelemetry-proto-java.git -cd opentelemetry-proto-java -``` - ### Building the Project To build the project and generate Java bindings from the OpenTelemetry proto definitions: @@ -89,8 +81,6 @@ Need help? Join our community: - **GitHub Discussions**: [OpenTelemetry Java Discussions](https://github.com/open-telemetry/opentelemetry-java/discussions) - **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-proto-java/issues) - - ## Troubleshooting Guide ### Common Issues & Fixes From 83048e9b244761929130f18b512c7f08cd032f53 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Mon, 17 Feb 2025 21:04:57 +0100 Subject: [PATCH 5/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6dbccc6..4afebf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,20 +65,15 @@ To generate a coverage report: ## Contributing Rules -- Follow [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). -- Ensure new features have appropriate test coverage. -- Run `./gradlew check` before submitting a PR. -- Include clear and concise documentation updates if needed. +* Ensure new features have appropriate test coverage. +* Run `./gradlew check` before submitting a PR. +* Include clear and concise documentation updates if needed. Check for issues labeled [`good first issue`](https://github.com/open-telemetry/opentelemetry-proto-java/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to start contributing. ## Further Help -Need help? Join our community: - -- **Slack**: [OpenTelemetry Slack](https://opentelemetry.io/community/) -- **GitHub Discussions**: [OpenTelemetry Java Discussions](https://github.com/open-telemetry/opentelemetry-java/discussions) - **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-proto-java/issues) ## Troubleshooting Guide @@ -105,7 +100,6 @@ Check logs and rerun the failing test with: ./gradlew test --tests com.example.FailingTest ``` - ## Additional Information ### Dependency Updates