Skip to content

Contributing

Workflow

  1. Fork susina/config-builder repository, clone it locally and apply your patches.
  2. Run the test suite by composer test command and fix all red tests.
  3. Run static analysis tool by composer analytics command and fix all errors.
  4. Fix the coding standard by running composer cs:fix.

Tip

We provide a check command for the tests, analytics and code style fixing, 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 Pest and we provide a script to launch it:

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

composer test -- --stop-on-failure

You can also use pest directly:

vendor/bin/pest

Code Coverage

We provides three commands to generate a code coverage report in html or xml format:

  • composer coverage command to print a coverage report summary to the console
  • composer coverage:html command generates a code coverage report in html format, into the directory coverage/
  • 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:

composer analytics

After its analysis, Psalm outputs errors and issues with its suggestions on how to fix them.

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:check

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

Documentation Contributing

susina/config-builder 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 (i.e. syntax highlight). You can find detailed information on https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown.

Additionally, you could get a look at Material theme documentation for further information.

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!