diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 88b6618e0..2e139a74b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -9,6 +9,8 @@ We use `docker` and `docker-compose` to perform a lot of our static analysis and The installation instructions for these tools are [here](https://docs.docker.com/install/), under the `Docker Engine` and `Docker Compose` submenus respectively. +Development tasks are generally run through a `Makefile`. Running `make` or `make help` will list available targets. + To ensure you have all the correct packages installed locally in your dev environment, you can run ```bash diff --git a/Makefile b/Makefile index 52a847e64..1ac8328fb 100644 --- a/Makefile +++ b/Makefile @@ -1,38 +1,45 @@ PHP_VERSION ?= 7.4 DC_RUN_PHP = docker-compose run --rm php -all: update rector style deptrac packages-composer phan psalm phpstan test -install: +.DEFAULT_GOAL : help + +help: ## Show this help + @printf "\033[33m%s:\033[0m\n" 'Available commands' + @awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z0-9_-]+:.*?## / {printf " \033[32m%-18s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) +all: update rector style deptrac packages-composer phan psalm phpstan test ## Run all tests, linting, checks +pull: ## Pull latest developer image + docker-compose pull php +install: ## Install dependencies $(DC_RUN_PHP) env XDEBUG_MODE=off composer install -update: +update: ## Update dependencies $(DC_RUN_PHP) env XDEBUG_MODE=off composer update -test: test-unit test-integration -test-unit: +test: test-unit test-integration ## Run unit and integration tests +test-unit: ## Run unit tests $(DC_RUN_PHP) env XDEBUG_MODE=coverage vendor/bin/phpunit --testsuite unit --colors=always --coverage-text --testdox --coverage-clover coverage.clover --coverage-html=tests/coverage/html --log-junit=junit.xml -test-integration: +test-integration: ## Run integration tests $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/phpunit --testsuite integration --colors=always -test-coverage: +test-coverage: ## Run units tests and generate code coverage $(DC_RUN_PHP) env XDEBUG_MODE=coverage vendor/bin/phpunit --testsuite unit --coverage-html=tests/coverage/html -test-compliance: +test-compliance: ## Run compliance tests $(DC_RUN_PHP) env XDEBUG_MODE=coverage vendor/bin/phpunit --group compliance -test-trace-compliance: +test-trace-compliance: ## Run trace compliance tests $(DC_RUN_PHP) env XDEBUG_MODE=coverage vendor/bin/phpunit --group trace-compliance -phan: +phan: ## Run phan $(DC_RUN_PHP) env XDEBUG_MODE=off env PHAN_DISABLE_XDEBUG_WARN=1 vendor/bin/phan -psalm: +psalm: ## Run psalm $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/psalm --threads=1 --no-cache -psalm-info: +psalm-info: ## Run psalm and show info $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/psalm --show-info=true --threads=1 -phpstan: +phpstan: ## Run phpstan $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/phpstan analyse --memory-limit=256M -packages-composer: +packages-composer: ## Validate composer packages $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/otel packages:composer:validate -benchmark: +benchmark: ## Run phpbench $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/phpbench run --report=default -phpmetrics: +phpmetrics: ## Run php metrics $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/phpmetrics --config=./phpmetrics.json --junit=junit.xml -smoke-test-examples: smoke-test-isolated-examples smoke-test-exporter-examples smoke-test-collector-integration smoke-test-prometheus-example -smoke-test-isolated-examples: +smoke-test-examples: smoke-test-isolated-examples smoke-test-exporter-examples smoke-test-collector-integration smoke-test-prometheus-example ## Run smoke test examples +smoke-test-isolated-examples: ## Run smoke test isolated examples $(DC_RUN_PHP) php ./examples/traces/getting_started.php $(DC_RUN_PHP) php ./examples/traces/features/always_off_trace_example.php $(DC_RUN_PHP) php ./examples/traces/features/batch_exporting.php @@ -45,7 +52,7 @@ smoke-test-isolated-examples: $(DC_RUN_PHP) php ./examples/traces/troubleshooting/air_gapped_trace_debugging.php $(DC_RUN_PHP) php ./examples/traces/troubleshooting/logging_of_span_data.php $(DC_RUN_PHP) php ./examples/traces/troubleshooting/setting_up_logging.php -smoke-test-exporter-examples: FORCE +smoke-test-exporter-examples: FORCE ## Run (some) exporter smoke test examples # Note this does not include every exporter at the moment docker-compose up -d --remove-orphans $(DC_RUN_PHP) php ./examples/traces/features/exporters/zipkin.php @@ -55,7 +62,7 @@ smoke-test-exporter-examples: FORCE docker-compose run -e NEW_RELIC_ENDPOINT -e NEW_RELIC_INSERT_KEY --rm php php ./examples/traces/features/exporters/newrelic.php docker-compose run -e NEW_RELIC_ENDPOINT -e NEW_RELIC_INSERT_KEY --rm php php ./examples/traces/features/exporters/zipkin_to_newrelic.php docker-compose stop -smoke-test-collector-integration: +smoke-test-collector-integration: ## Run smoke test collector integration docker-compose -f docker-compose.collector.yaml up -d --remove-orphans # This is slow because it's building the image from scratch (and parts of that, like installing the gRPC extension, are slow) # This can be sped up by switching to the pre-built images hosted on ghcr.io (and referenced in other docker-compose**.yaml files) @@ -70,24 +77,24 @@ stop-prometheus: @docker-compose -f docker-compose.prometheus.yaml -p opentelemetry-php_metrics-prometheus-example stop fiber-ffi-example: @docker-compose -f docker-compose.fiber-ffi.yaml -p opentelemetry-php_fiber-ffi-example up -d web -protobuf: +protobuf: ## Generate protobuf files ./script/proto_gen.sh -thrift: +thrift: ## Generate thrift files ./script/thrift_gen.sh -bash: +bash: ## bash shell into container $(DC_RUN_PHP) bash -style: +style: ## Run style check/fix $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --using-cache=no -vvv -rector: +rector: ## Run rector $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/rector process src -rector-dry: +rector-dry: ## Run rector (dry-run) $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/rector process src --dry-run -deptrac: +deptrac: ## Run deptrac $(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/deptrac --formatter=table --report-uncovered --no-cache w3c-test-service: @docker-compose -f docker-compose.w3cTraceContext.yaml run --rm php ./tests/TraceContext/W3CTestService/trace-context-test.sh -semconv: +semconv: ## Generate semconv files ./script/semantic-conventions/semconv.sh -split: +split: ## Run git split docker-compose -f docker/gitsplit/docker-compose.yaml --env-file ./.env up FORCE: