Вклад в phpDocumentor

Введение

phpDocumentor стремится быть высококачественным приложением для создания документации (DGA), но в то же время хочет предоставить участникам свободу при отправке исправлений или улучшений.

Таким образом, мы хотим поощрять, но не обязывать вас, участника, следовать этим рекомендациям. Единственное исключение из этого — рекомендации, касающиеся использования GitHub и ветвления, чтобы предотвратить «слияние ада».

При этом мы очень ценим, когда вы применяете эти рекомендации частично или полностью, поскольку это сэкономит нам время, которое, в свою очередь, мы можем потратить на исправление ошибок и новые функции.

Использование GitHub и ветвление

Как только вы решите внести свой вклад в phpDocumentor (что мы действительно ценим!), вы можете разветвить проект с https://github.com/phpDocumentor/phpDocumentor.

В настоящее время версия phpDocumentor 3.0 разрабатывается в нашей ветке master. Большие части кода там будут переписаны или удалены. Если вы хотите внести свой вклад в phpDocumentor v3.0, создайте свою функциональную ветку от master. Если вы хотите исправить ошибку в текущей выпущенной версии, основывайте свою ветку на 2.9. Пожалуйста, всегда создавайте новую ветку для каждой функции/исправления, которые вы хотите внести.

Если вы создадите свою ветку не от той базовой ветки, мы не сможем объединить вашу функцию с нужной версией. Это означает, что либо ваша функция будет выпущена только с v3.0, либо исправление никогда не будет в новом выпуске 2.*.

Чтобы получить дополнительную информацию об использовании Git, обратитесь к книге [Pro Git] Скотта Чакона и/или [этой справочной странице GitHub].

Настройка вашей среды разработки

Вам понадобятся:

• Git;
• Composer (https://getcomposer.org);
• Phive (https://phar.io);
• Docker (https://docker.com), включая Docker Compose.

После того как вы клонировали репозиторий, вы сможете запустить следующие команды, чтобы начать работу:

$ composer install
$ phive install
$ docker-compose run phpdoc

Для запуска тестов вы можете использовать следующую команду:

$ make test

Перед отправкой запроса на вытягивание также рекомендуется выполнить следующие команды:

$ make phpcs
$ make phpstan

Эти команды проверят качество вашего кода; это также делает Трэвис во время процесса запроса на вытягивание, но выполнение этих проверок самостоятельно поможет объединить ваш запрос на вытягивание.

Стандарты кодирования

phpDocumentor использует стандарт [PSR-2], определённый [Группой совместимости PHP-FIG].

Рекомендуется проверить свой код с помощью phpCodeSniffer, используя стандарт PSR2, выполнив следующую команду:

$ make phpcs

Модульное тестирование

phpDocumentor нацелен на достижение по крайней мере 90% покрытия кода с использованием модульных тестов с использованием PHPUnit. Рекомендуется включать модульные тесты в ваши запросы на вытягивание, так как они также помогают понять, что именно делает предоставленный код.

Чтобы запустить модульные тесты, вы можете выполнить следующую команду из папки phpDocumentor:

$ make test

Запуск тестов без Docker

Чтобы убедиться, что приложение тестируется контролируемым образом, мы используем Docker. Однако иногда невозможно использовать Docker на компьютере разработчика. В таких случаях рекомендуется выполнить следующие команды:

$ make install-phive
$ ./tools/phive.phar install --copy --trust-gpg-keys 4AA394086372C20A,D2CCAC42F6295E7D,E82B2FB314E9906E,8E730BA25823D8B5,D0254321FB74703A --force-accept-unsigned

И после этого вы можете запустить phpunit с помощью ./tools/phpunit.