Skip to content

Psr2 Code Generator Contributing Guide

Workflow

  1. Fork, clone and apply your patches.
  2. Run the test suite composer test and fix all red tests.
  3. Run static analysis tool (by now, we use Psalm) composer analytics and fix all errors and issues.
  4. Fix the coding standard composer cs-fix.

Tip

We provide a check command to run all the tests and analytics, required for a pull request. Run composer check

Running the Test Suite

While developing, the test part is very important: if you apply a patch to the existing code, the test suite must run without errors or failures and if you add a new functionality, no one will consider it without tests.

Our test tool is PhpUnit and we provide a script to launch it:

composer test

Since our command runs phpunit binary under the hood, you can pass all phpunit options to it via the -- operator, i.e.:

composer test -- --stop-on-failure

You can also use phpunit directly:

vendor/bin/phpunit

Code Coverage

We provides two commands to generate a code coverage report in html or xml format.

composer coverage:html command generates a code coverage report in html format, into the directory coverage/ while composer coverage:clover generates the report in xml format, into clover.xml file.

Static Analysis Tool

To prevent as many bugs as possible, we use a static analysis tool called Psalm. To launch it, run the following command from the root directory of psr2-code-generator project:

composer analytics

After its analysis, Psalm outputs errors and issues with its suggestions on how to fix them. Errors are more important and generally more dangerous than issues, anyway you should fix both.

Coding Standard

We ship our script to easily fix coding standard errors, via php-cs-fixer tool. To fix coding standard errors just run:

composer cs-fix

and to show the errors without fixing them, run:

composer cs

If you want to learn more about our code style, see https://github.com/susina/coding-standard.

Documentation Contributing

psr2-code-generator documentation resides into the directory docs/. It's written in markdown and it's generated by MkDocs.

Install the Tools

If you want to contribute to the documentation, you should install the following tools, to generate it locally:

  1. Install MkDocs
  2. Install Material theme by running: pip install mkdocs-material

Markdown flavour

MkDocs uses Python-Markdown with some extensions active by default. It supports the standard markdown, markdown-extra and some of the Github-flavoured markdown features. You can find detailed information on https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown.

Admonition

admonition extension helps to write beautiful notes or warnings or other (see the official documentation) with a syntax like the following:

!!! Danger
    Very dangerous operation!

which translates into the following:

Danger

Very dangerous operation!