Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (107 loc) · 4.97 KB

CONTRIBUTING.md

File metadata and controls

150 lines (107 loc) · 4.97 KB
Raw

Contributing

The project uses the MIT license. There is no contributor agreement to sign. You keep the copyright in your work and release it under MIT.

Requirements

PHP 8.2 or later, and Composer. The integration suite also needs Docker or a local MariaDB. The unit suite needs neither.

Setup

composer install
composer test

composer test runs the unit suite. It needs no database and must pass on a clean clone.

Tests

composer test              # unit suite, no database
composer test:integration  # integration suite, needs MariaDB
composer test:all          # both

CAUTION: never point PHPUnit at tests/ directly. That directory holds the test application and its vendor directory, which PHPUnit reads into.

The database

The repository ships a disposable MariaDB:

docker compose up -d --wait
DB_PORT=3307 composer test:integration

It publishes on 3307, because 3306 often holds a local MariaDB already. DB_PORT sets both the published port and the port the suite connects to. docker compose down leaves nothing behind.

To use your own server, create the schema and set the variables below. An exported variable takes priority over the defaults in phpunit.xml.

CREATE DATABASE TestJSONLibraryUnit;
Variable Default
DB_HOST 127.0.0.1
DB_PORT 3306
DB_USER root
DB_PASSWORD (empty)
DB_NAME TestJSONLibraryUnit
DB_DRIVER pdo_mysql

Where a new test goes

tests/Unit holds tests that perform no input and no output. They must run on a clean clone with no setup.

tests/Integration holds tests that need a database. Each one extends Tests\Integration\DatabaseTestCase. Real Doctrine against real MariaDB is deliberate: these confirm transaction and flush behavior, and Doctrine behavior that a mock only repeats back at you.

A query-layer test can still be a unit test. Tests\Fixtures\EntityManagerFactory::createUnconnected() builds an EntityManager that never connects, so a test can read the DQL a query produces without running it. See tests/Unit/Query/GeneratorTest.php.

Coverage

No coverage driver is installed. Read the coverage of src/ with phpdbg:

phpdbg -qrr vendor/bin/phpunit --coverage-text --coverage-filter src

The test application

tests/TestApp is a working Symfony application that consumes this library. Use it to see a change behave in a real request.

It holds Article, Author, Comment, and Contact, with a serializer for each. ArticleController serves /articles with GET, POST, PATCH, and DELETE. OperationsController serves POST /operations and shows the atomic endpoint, including the media-type check that the library leaves to you. ContactSerializer declares no operationRoles on purpose, to show that authorizeOperation() denies by default.

The application reaches the library through a Composer path repository, so your local changes apply with no publication step.

cd tests/TestApp
composer install
docker compose up -d --wait
php bin/console doctrine:migrations:migrate
php bin/console doctrine:fixtures:load
symfony server:start

Its compose.yaml runs MariaDB on port 3308, which .env already points at. Override DATABASE_URL in .env.local to use a database of your own.

Both test suites exclude this application. It is a place to run the library by hand, not a place for automated tests.

Code style

There is no automated formatter. Match the file you are editing.

  • Indent with tabs. Indent the body of a file one level inside the <?php tag.
  • Write a DocBlock for every new function and method. Say what to pass and what comes back, and add a short example. src/Request/JSONRequestInterface.php is the model.
  • Do not delete a comment you did not write.

Reporting a bug

CAUTION: if the bug is a security vulnerability, do not open an issue. Read SECURITY.md instead.

Search the open issues first. If yours is already there, add your details to it instead of opening another.

A report needs enough for someone else to reproduce the problem:

  • The smallest case that shows it. The serializer, generator, or request that triggers it is usually enough. A failing test is better.
  • The request, when one is involved: the method, the URL with its query parameters, and the body.
  • What you expected, and what happened instead.
  • The full error and stack trace, not the first line alone.
  • Your versions: PHP, Symfony, Doctrine ORM, this library, and your database server.

php -v and composer show give you the versions.

Merge requests

Open an issue before a large change, so we can agree on the approach first.

  1. Create a branch.
  2. Add a test for the behavior you change. A bug fix needs a test that fails without it.
  3. Make sure composer test:all passes.
  4. Open a merge request and describe what changed and why.

There is no continuous integration yet, so run the tests yourself first.