Skip to content

Latest commit

 

History

History
158 lines (106 loc) · 4.36 KB

CONTRIBUTING.md

File metadata and controls

158 lines (106 loc) · 4.36 KB
Raw

Contributing to dd-trace-php

As an open-source project we welcome contributions of many forms, but due to the experimental pre-beta nature of this repository, you should reach out to us before starting work on any major code changes. This will ensure we avoid duplicating work, or that your code can't be merged due to a rapidly changing base.

Getting set up with Docker

The easiest way to get the development environment set up is to install Docker and Docker Compose.

Developing and testing locally

PHP linting

The PHP tracer conforms to the PSR-2 coding style guide. The code style is checked with PHP_CodeSniffer which can be invoked with the following command:

$ composer lint

To try to automatically fix the code style, you can run:

$ composer fix-lint

Testing

Start your container

While tests in CI run on all php versions, you typically develop on one version locally. Currently the latest local dev environment we support is 8.0.

Ensure that docker has at least 4 GB of RAM available, otherwise composer may run out of memory.

Execute one the following commands from your command line, this will bring up all required services:

# For 7.0
$ docker-compose run --rm 7.0-buster bash
# For 7.1
$ docker-compose run --rm 7.1-buster bash
# For 7.2
$ docker-compose run --rm 7.2-buster bash
# For 7.3
$ docker-compose run --rm 7.3-buster bash
# For 7.4
$ docker-compose run --rm 7.4-buster bash
# For 8.0
$ docker-compose run --rm 8.0-buster bash
# For 8.1
$ docker-compose run --rm 8.1-buster bash
# For 8.2
$ docker-compose run --rm 8.2-buster bash

📝 Note: To run the container in debug mode, pass docker-compose an environment variable: DD_TRACE_DOCKER_DEBUG=1, eg:

docker-compose run --rm 8.2-buster -e DD_TRACE_DOCKER_DEBUG=1 bash

Set up the container

Once inside the container, update dependencies with Composer.

$ composer update

Then install the ddtrace extension.

$ composer install-ext

📝 Note: You'll need to run the above install-ext command to install the ddtrace extension every time you access the container's bash for the first time.

You can check that the extension was installed properly.

$ php --ri=ddtrace

You should see output similar to the following:

ddtrace


Datadog PHP tracer extension
For help, check out the documentation at https://docs.datadoghq.com/tracing/languages/php/
(c) Datadog 2020

Datadog tracing support => enabled
Version => 1.0.0-nightly
DATADOG TRACER CONFIGURATION => ...

Run the tests

First you need to update composer's dependecies in ./tests folder:

$ make composer_tests_update

📝 Note: To disable reliance on the generated files during development and testing, set the following environment variable:

export DD_AUTOLOAD_NO_COMPILE=true

Then you can run tests:

# Run all tests
$ make test_all

# Run unit tests (tests/Unit folder)
$ make test_unit

# Run integration tests (tests/Integration folder)
$ make test_integration

# Run auto-instrumentation tests (tests/AutoInstrumentation folder)
$ make test_auto_instrumentation

# Run composer integration tests (tests/Composer folder)
$ make test_composer

# Run distributed tracing tests (tests/DistributedTracing folder)
$ make test_distributed_tracing

# Run library integrations tests (tests/Integrations folder)
$ make test_integrations

# Run web frameworks integrations tests
$ make test_web

# Run C Tests (the ones in tests/ext)
$ make test_c

In order to run the phpt tests for the php extension:

$ composer test-ext

Treardown the environment

When you're done with development, you can stop and remove the containers with the following:

$ docker-compose down -v

Sending a pull request (PR)

There are a number of checks that are run automatically with CircleCI when a PR is submitted. To ensure your PHP code changes pass the CircleCI checks, make sure to run all the same checks before submitting a PR.

$ composer composer lint && test-all-<php-version>