development-workflow

name	development_workflow
description	Guide on how to use Docker Compose to run tests, static analysis, and code formatting on this project.

Development Workflow & Docker Commands

This project includes a fully isolated development environment using Docker Compose (docker-compose.yml) and a custom Dockerfile containing PHP 8.5 CLI, Composer, PCOV (for test coverage), and Node.js/npm (for linting and formatting).

As an AI agent, you should never run composer, PHP, or npm commands directly on the host if they require specific environments. Instead, always use the Docker container dev.

Running Commands via Docker

To execute commands within the isolated container, use the following syntax:

docker compose run --rm dev <command>

Available Scripts & QA Checks

Always check the scripts section in composer.json to discover the available commands (e.g., check:*, format:*, test:*, act:*, etc.).

When executing them, follow this pattern:

docker compose run --rm dev composer run <script-name>

Best Practices for AI Agents

• Piping Outputs: When executing commands that can produce hundreds of lines of output (like static analysis, mutation tests, or code quality checks), always pipe the output to a file inside the logs/ directory to avoid flooding your terminal context.
  • Example: docker compose run --rm dev composer run check:types > logs/analyse.txt
  • After piping, use the view_file tool to read the log selectively.
• Environment: The Docker container maps the current directory /app, so it uses the host's vendor folder dynamically. Do not run composer install unless explicitly asked.
• Releases & Commits: We use Release Please for automated semantic versioning. You must use Conventional Commits (e.g., feat:, fix:). To trigger a major version bump for breaking changes, you must append an exclamation mark ! to the commit type (e.g., refactor!: or feat!:).