Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (67 loc) · 4.21 KB

CONTRIBUTING.md

File metadata and controls

112 lines (67 loc) · 4.21 KB
Raw

Contributing to Query Monitor

Code contributions, bug reports, and feedback are very welcome. These should be submitted through the GitHub repository. Development happens in the develop branch, and any pull requests should be made to that branch.

Inclusivity and Code of Conduct

Contributions to Query Monitor are welcome from anyone. Whether you are new to Open Source or a seasoned veteran, all constructive contribution is welcome and I'll endeavour to support you when I can.

This project uses a contributor code of conduct and by participating in this project you agree to abide by its terms. The code of conduct is nothing to worry about, if you are respectful then all will be good.

AI-assisted development

AI-assisted development is welcome and encouraged, but you must:

  • Always disclose your use of AI-assisted coding agents. Failure to do so may result in your contribution being refused.
  • Always verify that the changes your AI assistant are proposing are valid and correct. Slop pull requests will be reported as spam.
  • Respect the GNU GPL software license that applies to this project.
  • Prefer human-written issue descriptions and pull request descriptions over AI-generated ones.
  • Always use the .github/PULL_REQUEST_TEMPLATE.md template when writing the body of a pull request.
  • Keep written descriptions brief, there is no need to write a novel that describes every change.

Setting up Locally

You can clone this repo and activate it like a normal plugin, but you'll need to install the developer dependencies in order to build the assets.

Prerequisites

Setup

  1. Install the PHP dependencies:

    composer install

  2. Install the Node dependencies:

    npm install

Building the Assets

To compile the React components:

npm run build

To start the file watcher which will watch for changes and automatically compile the React components:

npm run watch

Data Type Generation

Query Monitor uses JSON Schema to define the structure of data passed between PHP collectors and React output panels. This ensures type safety across both languages.

How it works

  1. JSON Schemas (src/schemas/data/*.json) define the structure of data objects using JSON Schema format with custom extensions:

    • phpClass: The PHP class name to generate
    • phpFile: The file path (relative to data/) where the PHP class will be written
    • phpType: Reference an existing PHP type instead of generating one

  2. Build command (npm run build-schemas) generates:

    • PHP classes in data/ from the schema definitions
    • TypeScript interfaces in output/data-types.ts

  3. PHP collectors (collectors/*.php) populate instances of the generated data classes

  4. React panels (output/html/*.tsx) consume the data with full TypeScript type checking

Architecture

The front-end Preact app must remain declarative, reactive, and state-driven, with no imperative code. Views should be pure components with no side effects where possible.

The server-side PHP in collectors and dispatchers should minimise memory usage as much as possible. Prefer DTOs over array shapes.

Running the Tests

The test suite consists of:

  • Acceptance tests using Playwright
  • Integration tests using PHPUnit
  • Linting using PHPCS and ESLint
  • Static analysis using PHPStan

The acceptance and integration tests run in a container. Ensure Docker Desktop is running before running the tests.

To run the whole test suite:

composer test

To run tests individually, run one of:

npm run typecheck
npm run lint
composer test:phpcs
composer test:phpstan
composer test:integration
composer test:acceptance

To run a single test:

composer test:acceptance -- tests/acceptance/EnqueuedScripts.spec.ts

The individual integration and acceptance tests require the Docker containers to be running. To start and stop them, use:

composer test:start
composer test:stop

Releasing a New Version

See RELEASING.md.