First of all, thank you for contributing, you are awesome!
Everybody should be able to help. Here's how you can do it:
- Fork it
- improve it
- submit a pull request
Here's some tips to make you the best contributor ever:
Here are a few rules to follow in order to ease code reviews, and discussions before maintainers accept and merge your work.
- You MUST follow the PSR-1 and
PSR-12 coding standards. In practice, the project
enforces the
@Symfonyrule set through PHP CS Fixer - just runcastor qa:cs(see Standard code) and it is taken care of for you. - You MUST run the test suite (see Green tests).
- Your code MUST pass the static analysis:
castor qa:phpstan(PHPStan, level 9). CI fails on any error. - You MUST write (or update) unit tests.
- You SHOULD write documentation.
Please, write commit messages that make sense, and rebase your branch before submitting your Pull Request (see also how to keep your fork up-to-date).
One may ask you to squash your
commits
too. This is used to "clean" your Pull Request before merging it (we don't want
commits such as fix tests, fix 2, fix 3, etc.).
Also, while creating your Pull Request on GitHub, you MUST write a description which gives the context and/or explains why you are creating it.
Your work will then be reviewed as soon as possible (suggestions about some changes, improvements or alternatives may be given).
The tooling runs with the PHP task runner Castor. Downloading the W3C test suites also needs the ZipArchive PHP extension.
Clone the repository, then install the library's dependencies and the QA tooling:
composer install # the library's own dependencies (Composer, not Castor)
castor qa:install # the QA tooling: php-cs-fixer, phpstan, phpunit, phpbench, infectionAll the tasks are defined in the .castor directory, one file per namespace.
Run the tests using the following command:
castor qa:phpunit:runBoth schema.org and Google validator tests are included. You can run a single group with:
castor qa:phpunit:run -g schema-org
castor qa:phpunit:run -g googleThis project includes two main validators: the schema.org validator and the Google validator.
The validation classes shipped in src/Vocabularies/Generated are generated from the
vocabulary definitions (see Vocabulary generation). When adding or
updating validator support (new types, schema versions, special validation rules):
- Google validator updates track the Google structured-data documentation, which evolves continuously. For special rules or complex validation logic, see the existing rule implementations in
src/Vocabularies/Validators/Google/SpecialRules/. - Schema.org validator updates are driven by the official schema.org releases. When upgrading, always review the release notes and check that the changes to the
schema-org-baseline.jsontest fixture reflect real schema.org changes.
For comprehensive upgrade procedures for either validator, refer to:
Use PHP CS fixer to make your code compliant with our coding standards:
castor qa:cs| Command | Description |
|---|---|
castor qa:install |
Installs the QA tooling |
castor qa:update |
Updates the QA tooling |
castor qa:cs |
Fixes coding standards |
castor qa:phpstan |
Runs PHPStan |
castor qa:all |
Runs all QA tasks |
castor qa:earl |
Runs the W3C test suites and writes the EARL conformance report (see Conformance) |
| Command | Description |
|---|---|
castor qa:phpunit:prepare |
Downloads the W3C tests suite |
castor qa:phpunit:run |
Runs PHPUnit |
castor qa:phpunit:coverage |
Runs PHPUnit with code coverage (requires the pcov or xdebug extension) |
castor qa:infection |
Runs Infection mutation testing on the validator and mapper layers (requires the pcov or xdebug extension) |
The W3C test suite is pinned to a known-good upstream commit (see W3C_TEST_SUITE_REF in .castor/qa.php).
To re-download it, or to test against the upstream main branch:
castor qa:phpunit:prepare --force
castor qa:phpunit:prepare --force --ref main| Command | Description |
|---|---|
castor qa:bench:all |
Runs all the benchmarks |
castor qa:bench:algorithms |
Runs the JSON-LD manipulation algorithms benchmark |
castor qa:bench:validators |
Runs the validators benchmark |
castor qa:bench:validators -d |
Runs the detailed and slow validators benchmark |
The latest figures, and what each of them measures, are in BENCHMARKS.md.
These commands build the demo website, that runs the validator in the browser:
| Command | Description |
|---|---|
castor website:build |
Builds the demo website: its assets, and PHP as WebAssembly with the validator |
castor website:check |
Checks, in node, that what is built boots, and audits a document |
castor website:serve |
Serves the demo website |
These commands refresh the validation classes shipped in src/Vocabularies/Generated:
| Command | Description |
|---|---|
castor schema-org:update-version |
Bump the schema.org version to the latest release published on GitHub |
castor schema-org:download |
Download the schema.org types definition file and JSON-LD context |
castor schema-org:generate |
Generate the schema.org validation classes |
castor schema-org:download-examples |
Refresh the schema.org examples used by the tests |
castor google:download |
Crawl the Google structured-data documentation |
castor google:generate |
Generate the Google validation classes |
castor google:check |
Check the Google documentation coverage against the curated manifest |
To keep your fork up-to-date, you should track the upstream (original) one using the following command:
git remote add upstream https://github.com/jolicode/structured-data.gitThen get the upstream changes:
git checkout main
git pull --rebase origin main
git pull --rebase upstream main
git checkout <your-branch>
git rebase mainFinally, publish your changes:
git push -f origin <your-branch>Your pull request will be automatically updated.
Thank you!