Skip to content

Latest commit

 

History

History
111 lines (72 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

111 lines (72 loc) · 3.75 KB
Raw

Contributing to phpDocumentor

Introduction

phpDocumentor aims to be a high quality Documentation Generation Application (DGA) but at the same time wants to give contributors freedom when submitting fixes or improvements.

As such we want to encourage but not obligate you, the contributor, to follow these guidelines. The only exception to this are the guidelines regarding GitHub Usage & Branching to prevent merge-hell.

Having said that: we really appreciate it when you apply the guidelines in part or wholly as that will save us time which, in turn, we can spend on bugfixes and new features.

GitHub Usage & Branching

Once you decide you want to contribute to phpDocumentor (which we really appreciate!) you can fork the project from http://github.com/phpDocumentor/phpDocumentor2.

Currently phpdocumentor version 3.0 is developed in our develop branch. Large parts of the code in there will be rewritten or removed. If you want to contribute to phpdocumentor v3.0, create your feature branch from develop. If you want to fix a bug in the current released version, base your branch on master. Please always create a new branch for each feature/bugfix you want to contribute.

If you create your branch from the wrong base branch we won't be able to merge your feature in to the right version. Which means that either your feature will only be released with v3.0 or bugfix will never be in a new 2.* release.

To get more information about the usage of Git, please refer to the Pro Git book written by Scott Chacon and/or this help page of GitHub.

Setting Up Your Development Environment

Using Docker

You need the following:

  • Composer
  • Git
  • Docker
  • Docker Machine

Once you cloned the repository you should be able to run the following commands to get started

$ composer install $ docker-machine run phpdoc

To run the tests you can use the following command:

$ docker-machine run phpunit

Before issuing a pull request it is also recommended to run the following commands:

$ docker-machine run phpcs $ docker-machine run phpstan

These command will check the quality of your code; this is also done by Travis during the pull request process but performing these checks yourself will help getting your pull request merged.

On your local machine

You need the following:

  • Composer
  • Git
  • Curl and PHP's Curl extension
  • PHP's XSL extension and
  • PHP's intl extension

Once you cloned the repository you should be able to run the following commands to get started

$ composer install $ php bin/phpunit $ php bin/behat

Both behat and phpunit tests should pass without issues.

Coding Standards

phpDocumentor uses the PSR-2 Coding Standard as defined by the PHP Framework Interoperability Group (PHP-FIG).

It is recommended to check your code using phpCodeSniffer using the PSR2 standard using the following command:

$ ./bin/phpcs --standard=PSR2 .

or using Docker:

$ docker-machine run phpcs

Unit testing

phpDocumentor aims to be have at least 90% Code Coverage using unit tests using PHPUnit. It is appreciated to include unit tests in your pull requests as they also help understand what the contributed code exactly does.

In order to run the unit tests you can execute the following command from your phpDocumentor folder:

./bin/phpunit

or using Docker:

$ docker-machine run phpunit