From 8f5a93582ffd6d6c5008ce443b032f9aaa2fe9f6 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Tue, 4 Feb 2025 11:29:27 +0100 Subject: [PATCH 1/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 175 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b88caf04..a8d855937 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,178 @@ +# Contributing to OpenTelemetry PHP + +## Introduction + +Welcome to the OpenTelemetry PHPrepository! πŸŽ‰ + +Thank you for considering contributing to this project. Whether you're fixing a bug, adding new features, improving documentation, or reporting an issue, we appreciate your help in making OpenTelemetry better. + +This repository is part of the OpenTelemetry ecosystem, which provides observability tooling for distributed systems. Your contributions help enhance the PHP ecosystem for OpenTelemetry users worldwide. + +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: + +- **PHP** (8.1 or higher) – [Install PHP](https://www.php.net/downloads) +- **Composer** – [Install Composer](https://getcomposer.org/) +- **Docker & Docker Compose** – [Install Docker](https://docs.docker.com/engine/install/) +- **Make** (for running development tasks) + +Additional Notes: +- Windows users may need [Git Bash](https://gitforwindows.org/) for better compatibility. +- Consider using [phpenv](https://github.com/phpenv/phpenv) for managing multiple PHP versions. + +## 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(tracing): resolve issue with span context`) +- 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-php.git +cd opentelemetry-php + +# Install dependencies +make install +``` + +To update dependencies: + +```bash +make update +``` + +To run checks: + +```bash +make all-checks +``` + + +## Testing + +We use various tools for testing and static analysis: + +```bash +# Run all tests +make test + +# Run static analysis +make phan +make psalm +make phpstan + +# Run style checks +make style +``` + +To run tests against different PHP versions: + +```bash +PHP_VERSION=8.3 make test +``` + +## Contributing Rules + +- Follow [Clean Code PHP](https://github.com/jupeter/clean-code-php) principles. +- Ensure new features have appropriate test coverage. +- Run `make style` 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-php/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to start contributing. + + +## Further Help + +Need help? Join our community: + +Most of our communication is done on CNCF Slack in the channel: + +- **Slack**: [otel-php](https://cloud-native.slack.com/archives/C01NFPCV44V) +- **GitHub Discussions**: [OpenTelemetry PHP Discussions](https://github.com/open-telemetry/opentelemetry-php/discussions) +- **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-php-contrib/issues) + + +## Troubleshooting Guide + +### Common Issues & Fixes + +#### 1. Missing PHP dependencies +**Error:** `Class 'SomeClass' not found` + +**Fix:** Run: +```bash +make install +``` + +#### 2. Linting Errors +**Error:** `Files not formatted correctly` + +**Fix:** Run: +```bash +make style +``` + +#### 3. Tests Failing Due to Missing Dependencies +**Error:** `Dependency missing` + +**Fix:** +```bash +make update +make test +``` + + +## Additional Information + +### Code Coverage +We use [Codecov](https://about.codecov.io/) to track test coverage. You can generate a local coverage report using: + +```bash +make test-coverage +``` + +### Generating API Documentation +To generate API docs: +```bash +make phpdoc +``` + +To preview locally: +```bash +make phpdoc-preview +``` + +### Dependency Validation +We use [Deptrac](https://github.com/qossmic/deptrac) for dependency validation: +```bash +make deptrac +``` + +Thank you for contributing! πŸš€ + + + ## Maintainers [@open-telemetry/php-maintainers](https://github.com/orgs/open-telemetry/teams/php-maintainers) @@ -34,10 +209,6 @@ Find more information about the member role in the [community repository](https: Find more about emeritus roles in the [community repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#emeritus-maintainerapprovertriager) -## Communication - -Most of our communication is done on CNCF Slack in the channel [otel-php](https://cloud-native.slack.com/archives/C01NFPCV44V). -To sign up, create a CNCF Slack account [here](http://slack.cncf.io/) Our meetings are held weekly on zoom on Wednesdays at 10:30am PST / 1:30pm EST. A Google calendar invite with the included zoom link can be found [here](https://calendar.google.com/event?action=TEMPLATE&tmeid=N2VtZXZmYnVmbzZkYjZkbTYxdjZvYTdxN21fMjAyMDA5MTZUMTczMDAwWiBrYXJlbnlyeHVAbQ&tmsrc=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com&scp=ALL) From 5aa56cb624fb7b28ba827a44d7d601765543a4a5 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Tue, 4 Feb 2025 11:33:27 +0100 Subject: [PATCH 2/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8d855937..a4ab314f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## Introduction -Welcome to the OpenTelemetry PHPrepository! πŸŽ‰ +Welcome to the OpenTelemetry PHP repository! πŸŽ‰ Thank you for considering contributing to this project. Whether you're fixing a bug, adding new features, improving documentation, or reporting an issue, we appreciate your help in making OpenTelemetry better. From b5b73c4babb3403f35d495c2ed27fe5d621bc332 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Wed, 5 Feb 2025 10:12:19 +0100 Subject: [PATCH 3/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a4ab314f8..71ab734a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,19 +71,11 @@ make all-checks ## Testing -We use various tools for testing and static analysis: +To ensure your changes meet our project's standards, simply run: ```bash -# Run all tests -make test - -# Run static analysis -make phan -make psalm -make phpstan +make all -# Run style checks -make style ``` To run tests against different PHP versions: @@ -110,7 +102,7 @@ Most of our communication is done on CNCF Slack in the channel: - **Slack**: [otel-php](https://cloud-native.slack.com/archives/C01NFPCV44V) - **GitHub Discussions**: [OpenTelemetry PHP Discussions](https://github.com/open-telemetry/opentelemetry-php/discussions) -- **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-php-contrib/issues) +- **Issues**: If you encounter a bug, [open an issue](https://github.com/open-telemetry/opentelemetry-php/issues) ## Troubleshooting Guide From 68951112b304f78fb497a22f818aff2a41005d88 Mon Sep 17 00:00:00 2001 From: Richard Chukwu <79311274+RichardChukwu@users.noreply.github.com> Date: Tue, 11 Feb 2025 17:15:10 +0100 Subject: [PATCH 4/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71ab734a6..38db746fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,26 +23,6 @@ Additional Notes: - Windows users may need [Git Bash](https://gitforwindows.org/) for better compatibility. - Consider using [phpenv](https://github.com/phpenv/phpenv) for managing multiple PHP versions. -## 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(tracing): resolve issue with span context`) -- 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: