14 KiB

Raw Permalink Blame History

Contributing Guide

Introduction

Welcome to the OpenTelemetry PHP repository! We appreciate your interest in contributing and helping improve this project. No contribution is too small—whether you're fixing a typo, improving documentation, or implementing a major feature, we value your help.

This repository is part of the larger OpenTelemetry ecosystem, aimed at providing observability solutions for PHP applications. If you have any questions, feel free to ask in our community channels (See further help below). Your contributions make a difference!

Pre-requisites

To contribute effectively, ensure you have the following tools installed:

PHP 8.1 or higher (Check supported PHP versions)

We aim to support officially supported PHP versions, according to https://www.php.net/supported-versions.php. The developer image ghcr.io/open-telemetry/opentelemetry-php/opentelemetry-php-base is tagged as 8.1, 8.2 and 8.3 respectively, with 8.1 being the default. You can execute the test suite against other PHP versions by running the following command:

PHP_VERSION=8.1 make all
#or
PHP_VERSION=8.3 make all

For repeatability and consistency across different operating systems, we use the 3 Musketeers pattern. If you're on Windows, it might be a good idea to use Git bash for following the steps below.

Note: After cloning the repository, copy .env.dist to .env.

Skipping the step above would result in a "The "PHP_USER" variable is not set. Defaulting to a blank string" warning

We use docker and docker compose to perform a lot of our static analysis and testing. If you're planning to develop for this library, it'll help to install docker engine and the compose plugin.

Development tasks are generally run through a Makefile. Running make or make help will list available targets.

Workflow

Pull Requests

To propose changes to the codebase, you need to open a pull request to the opentelemetry-php project.

After you open the pull request, the CI will run all the associated github actions.

To ensure your PR doesn't emit a failure with GitHub actions, it's recommended that you run the important CI tests locally with the following command:

make all # composer update, then run all checks
make all-lowest # composer update to lowest dependencies, then run all checks

This does the following things:

Installs/updates all the required dependencies for the project
Uses Rector to refactor your code according to our standards.
Uses php-cs-fixer to style your code using our style preferences.
Uses Deptrac to check for dependency violations inside our code base
Makes sure the composer files for the different components are valid
Runs all of our phpunit unit tests.
Performs static analysis with Phan, Psalm and PHPStan

Local Run/Build

To ensure you have all the correct packages installed locally in your dev environment, you can run

make install

This will install all the library dependencies to the /vendor directory.

To update these dependencies, you can run

make update

To downgrade to the lowest dependencies, you can run

make update-lowest

To run all checks without doing a composer update:

make all-checks

Testing

To make sure the tests in this repo work as you expect, you can use the included docker test wrapper.
To run the test suite, execute

make test

This will output the test output as well as a test coverage analysis (text + html - see tests/coverage/html). Code that doesn't pass our currently defined tests will emit a failure in CI

Contributing Rules

Even though it may not be reflected everywhere in the codebase yet, we aim to provide software which is easy to read and change. The methods described in Clean Code book(s) by Robert C. Martin (Uncle Bob) are a de facto industry standards nowadays. Reading those books is highly recommended, however you can take a look at the examples given at Clean Code PHP. While we have no rule to strictly follow said methods and patterns, they are highly recommended as an orientation for your pull requests and to be referenced in reviews.

We might add additional guidelines regarding for example testing in the future.

Additional Information

Automatic Refactoring and Upgrading

We use Rector to automatically refactor our code according to given standards and upgrade the code to supported PHP versions. The associated configuration can be found here

If you want to check what changes would be applied by rector, you can run:

make rector

This command will simply print out the changes rector would make without actually changing any code.

To refactor your code following our given standards, you can run:

make rector-write

This command applies the changes to the code base. Make sure to run make style (see below) after running the rectorcommand as the changes might not follow our coding standard.

Styling

We use PHP-CS-Fixer for our code linting and standards fixer. The associated configuration can be found here

To ensure that your code follows our coding standards, you can run:

make style

This command executes a required check that also runs during CI. This process performs the required fixes and prints them out. Code that doesn't meet the style pattern will emit a failure with GitHub actions.

Static Analysis

We use Phan for static analysis. Currently, our phan configuration is just a standard default analysis configuration. You can use our phan docker wrapper to easily perform static analysis on your changes.

To run Phan, one can run the following command:

make phan

This process will return 0 on success. Usually this process is performed as part of a code checkin. This process runs during CI and is a required check. Code that doesn't match the standards that we have defined in our phan config will emit a failure in CI.

We also use Psalm as a second static analysis tool.
You can use our psalm docker wrapper to easily perform static analysis on your changes.

To run Psalm, one can run the following command:

make psalm

We use PHPStan as our third tool for static analysis. You can use our PHPStan docker wrapper to easily perform static analysis on your changes.

To perform static analysis with PHPStan run:

make phpstan

Code Coverage

We use codecov.io to track code coverage for this repo. This is configured in the php.yaml github action. We don't require a specific level of code coverage for PRs to pass - we just use this tool in order to understand how a PR will potentially change the amount of code coverage we have across the code base. This tool isn't perfect - sometimes we'll see small deltas in code coverage where there shouldn't be any - this is nothing to fret about.

If code coverage does decrease on a pull request, you will see a red X in the CI for the repo, but that's ok - the reviewer will use their judgement to determine whether or not we have sufficient code coverage for the change.

Dependency Validation

To make sure the different components of the library are distributable as separate packages, we have to check for dependency violations inside the code base. Dependencies must create a DAC in order to not create recursive dependencies. For this purpose we use Deptrac and the respective configuration can be found here

To validate the dependencies inside the code base, you can run:

make deptrac

This command will create an error for any violation of the defined dependencies. If you add new dependencies to the code base, please configure them in the rector configuration.

PhpMetrics

To generate a report showing a variety of metrics for the library and its classes, you can run:

make phpmetrics

This will generate a HTML PhpMetrics report in the var/metrics directory. Make sure to run make test before to create the test log-file, used by the metrics report.

Proto Generation

Our protobuf files are committed to the repository into the /proto folder. These are used in gRPC connections to the upstream. These get updated when the opentelemetry-proto repo has a meaningful update. The maintainer SIG is discussing a way to make this more automatic in the future.

To generate protobuf files for use with this repository, you can run the following command:

make protobuf

This will replace proto/otel/Opentelemetry and proto/otel/GPBMetadata with freshly generated code based on the latest tag from opentelemetry-proto, which can then be committed.

Semantic Conventions Generation

Autogenerated semantic convention files are committed to the repository in the /src/SemConv directory. These files are updated manually when a new version of semantic-conventions is released.

SEMCONV_VERSION=1.8.0 make semconv

Run this command in the root of this repository.

API Documentation

We use phpDocumentor to automatically generate API documentation from DocBlocks in the code.

To generate a recent version of the API documentation, you can run:

make phpdoc

To preview the documentation and changes you might expect, you can run:

make phpdoc-preview

This will start a HTTP server running at http://localhost:8080 serving the updated documentation files.

Maintainers

@open-telemetry/php-maintainers

Bob Strecansky
Brett McBride, Deakin University

Find more about the maintainer role in community repository

Approvers

@open-telemetry/php-approvers

Find more information about the approver role in the community repository

Triagers

@open-telemetry/php-triagers

Find more information about the triager role in the community repository

Members

Kishan Sangani

Find more information about the member role in the community repository

Emeritus maintainers/approvers/triagers

Find more about emeritus roles in the community repository

Further Help

Most of our communication is done on CNCF Slack in the channel otel-php. To sign up, create a CNCF Slack account here

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

Our open issues can all be found in the GitHub issues tab. Feel free to reach out on Slack if you have any additional questions about these issues; we are always happy to talk through implementation details.

14 KiB Raw Permalink Blame History