CONTRIBUTING.md

Contributing

Contributions of any kind are welcome.

Feel free to submit Github Issues or pull requests.

Quick Guide

The documentation site has some details about internals.

How-To

• Fork the repo.

• Checkout the branch you want to make changes on.

  • Typically, this will be master. Note that most of the time, master represents the next release of swagger-php, so Pull Requests that break backwards compatibility might be postponed.

• Install dependencies: composer install.

• Create a new branch, e.g. feature-foo or bugfix-bar.

• Make changes.

• If you are adding functionality or fixing a bug - add a test!

  Prefer adding new test cases over modifying existing ones.

• Update documentation: composer docs:gen.

• Run static analysis using PHPStan/Psalm: composer analyse.

• Check if tests pass: composer test.

• Fix code style issues: composer cs.

Documentation

The documentation website is build from the docs folder with vitepress. This process involves converting the existing markdown (.md) files into static HTML pages and publishing them.

Some reference content is based on the existing code, so changes to annotations, attributes and processors will require to re-generate those markdown files: composer docs:gen.

The actual published content is managed in the gh-pages branch and driven by a publish action.

Useful commands

To run both unit tests and linting execute

composer test

To run static-analysis execute

composer analyse

Running unit tests only

./bin/phpunit

Regenerate reference markup docs

composer docs:gen

Running linting only

composer lint

To make php-cs-fixer fix linting errors

composer cs

Run dev server for local development of gh-pages

composer docs:dev

Project's Standards

• PSR-1: Basic Coding Standard
• PSR-2: Coding Style Guide
• PSR-4: Autoloading Standard
• PSR-5: PHPDoc (draft)