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.
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.
You need the following:
- Git
- Composer (https://getcomposer.org)
- Phive (https://phar.io)
- Docker (https://docker.com), including Docker Compose
Once you cloned the repository you should be able to run the following commands to get started
$ composer install
$ phive install
$ docker-compose run phpdoc
To run the tests you can use the following command:
$ docker-compose run phpunit
Before issuing a pull request it is also recommended to run the following commands:
$ docker-compose run phpcs
$ docker-compose 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.
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:
$ docker-compose run phpcs
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:
$ docker-compose run phpunit