Как правильно внести свою лепту в Open Source проект: простые подсказки16.01.2016 13:48

Open Source проекты с каждым днём набирают всё большие обороты, появляются новые, активно развиваются популярные.
Такие проекты как Bootstrap, Angular.js, Elasticsearch, Symfony Framework, Swift и многие другие привлекают новых разработчиков, их сообщество растёт. Всё это даёт огромный рост проектам, а самим разработчикам интересно поучаствовать в разработке чего-то, чем пользуется весь мир.

Я, как и многие другие программисты, не устоял и также время от времени участвую в разработке Open Source проектов, в основном на PHP.
Но когда я начинал, я столкнулся с проблемой — я не знал, как правильно организовать процесс «контрибьютинга», с чего начать, как сделать так, чтобы мой Pull Request рассмотрели и т.д.

Всем начинающим «контрибьютерам», которые столкнулись с похожим проблемами, добро пожаловать под кат.

Сам процесс участия в Open-Source проекте рассмотрим на примерах различных PHP фреймоворков, возьмём Symfony, Yii2.

Первое, что необходимо сделать — это создать аккаунт на GitHub (если его ещё у Вас нет). Заполняйте его внимательно, так как Ваш GitHub профиль — это фактически Ваша визитная карточка в мире Open Source.

Далее следует ознакомиться с правилами участия в разработке для выбранного Вами проекта. Данные правила обычно находятся в файле

CONTRIBUTING.md

в корне репозитория. Для Symfony, например, это Symfony Contributing.

Обычно, есть несколько способов участия в разработке Open Source проекта, основные — это отправка сообщения о какой-то ошибке или желаемом улучшении (Submitting Issue) или непосредственное создание Pull Request с вашим исправлением или улучшением (Code Contributing).
Так же Вы можете поучаствовать в улучшении документации, ответах на вопросы, возникщих у других разработчков и многое другое.

Если Вы захотели уведомить разработчиков о какой-либо найденной ошибке или улучшении, Вам необходимо создать соответствующий GitHub Issue.
Но перед тем, как создавать его, проверьте, не существует ли уже такого же или похожего, созданного кем-либо другим.
Перед созданием также не забудьте ознакомиться с правилами отправки отчёта об ошибке для данного проекта. К примеру, вот правила для Yii Framework
Обычно, описание должно быть максимально чётким, понятным, желательно наличие примеров и описания как воспроизвести ошибку. Это сэкономит огромное время и разработчикам, и Вам, так как избавит Вас от ответа на уточнящие вопросы и т.д.
Если вы нашли GitHub Issue, которое хотели бы исправить или же создали свой собственный, то следующим Вашим шагом будет отправка соответствующего Pull Request.
Опять же, для начала не забудьте ознакомиться с правилами участия в разработке для выбранного Вами проекта.
Например, вот правила для Yii.

Далее я хотел бы описать наиболее часто встречаемый процесс работы с Git и GitHub при участии в Open Source проектах (Git Workflow).
Этот процесс может отличаться от проекта к проекту, да и в целом он присущ не только Open Source проектам, но и многим закрытым проектам на GitHub и BitBucket.

Шаг 1 — Подготовка рабочего окружения

Естественно, для разработки Вам надо подготовить Ваше рабочее окружение.
Многие Open Source проекты указывают, как именно необходимо его настроить, какие библиотеки, пакеты, инструменты, их версии и тд необходимы.

Для PHP-проектов обычно Вам понадобится приблизительно такой минимальный список

Git;
PHP; (Обычно версии от 5.3+)
MySQL;
Composer.

Кроме того, часто необходим PHPUnit. Обычно он идёт в составе самого проекта и лучше использовать именно его, так как в разных версиях PHPUnit тесты могут попросту не работать и то, что работает у вас с новейшей версии, может не работать на CI сервере проекта, где библиотека более старая.

Шаг 2 — Создаём копию (Fork) репозитория проекта

Заходим на страницу выбранного Вами проекта и нажимаем кнопку «Fork». Данная команда создаст Вашу собственную копию репозитория данного проекта.

Далее Вам необходимо склонировать вашу копию репозитория.

git clone https://github.com/<Ваше-GitHub-имя>/<Название-Репозитория>.git

Далее Вам необходимо добавить ветку upstream для проекта, которая будет ссылаться на базовый репозиторий (вариант для Yii)

cd <Локальная-Папка-Проекта>
git remote add upstream https://github.com/yiisoft/yii2.git

Шаг 3 — Настроим Git

Далее, необходимо сделать небольшую настройку Вашего Git, для того, чтобы при отправке коммитов, отображалось ваше корректное имя.
Для это достаточно выполнить данные команды:

git config --global user.name "Ваше Имя"
git config --global user.email you@example.com

Если вы хотите настроить данные значения локально для данногог проекта, в папке проекта выполните

git config --local user.name "Ваше Имя"
git config --local user.email you@example.com

Шаг 4 — Composer

Далее, в 99% случаев для проекта Вам придётся выполнить загрузку библиотек через Composer

cd <Локальная-Папка-Проекта>
composer install

Шаг 5 — Тесты

Перед тем, как начать работу, настройте в своей любимой IDE или просто в консоли PHPUnit (реже Behat, PhpSpec и тд) для запуска и работы с тестами.
После настройки запустите тесты для проекта и проверьте что они корректно проходят.

Шаг 6 — Работаем с кодом

Начиная работать над вашим исправлением, изначально надо создать соответствующую Git ветку, основанную на актуальном коде из базового репозитория.

Выбирайте чётко и лаконично имя ветки, которое отражало бы суть изменений.
Считается хорошей практикой включать в названии ветки номер GitHub issue.

git fetch upstream
git checkout -b 1234-helper-class-fix upstream/master

Теперь вы можете смело приступать к работе над кодом.
Работая, помните о следующих правилах:

Следуйте стандартам кодирования (обычно это PSR-стандарты);
Пишите юнит-тесты, чтобы доказать, что ошибка исправлена, или что новая функция на самом деле работает;
Старайтесь не нарушать обратную совместимость без крайней необходимости;
Используйте простые и логически цельные коммиты;
Пишите чёткие, ясные, полные сообщения при коммите изменений.

Шаг 7 — Отправляем Pull Request

Пока Вы работали над кодом, в основную ветку проекта могли быть внесены другие изменения. Поэтому перед отправкой ваших изменений Вам необходимо сделать rebase Вашей ветки.
Делается это так:

git checkout <ИМЯ-ВАШЕЙ-ВЕТКИ>
git fetch upstream
git rebase upstream/master

Теперь вы можете отправить Ваши изменения.

git push origin <ИМЯ-ВАШЕЙ-ВЕТКИ>

После этого заходим в Ваш репозиторий-клон проекта, в котором Вы участвуете и нажимаем кнопку «New Pull Request».
И видим следующую форму:

Слева необходимо выбрать ветку, в которую Вы хотите смержить изменения (обычно это master, ну, а вообще это ветка, на которую вы делали rebase).
Справа — ветку с Вашими изменениями.
Далее Вы увидите сообщение от GitHub о том, возможно ли автоматически смержить изменения или нет.
В большинстве случаев, Вы увидите Able to merge.
Если же есть конфликты, Вам скорее всего придётся пересмотреть Ваши изменения.

Далее нажимаем кнопку — Create Pull Request.
При заполнение имени и описания вашего Pull Request считается хорошей практикой указывать номер Issue, для которого создан ваш Pull Request.

Обычно для многих крупных проектов настроен CI сервер, часто Travis-CI.
После создания Pull Request он будет прогонять тесты, возможно какие-то инструменты для метрик и так далее. Результы его работы вы увидите в Вашем Pull Request как показано ниже:

В случае, если тесты не будут пройдены или билд не будет собран, вы увидите красное сообщение об ошибке и по ссылку Details сможете увидите, что же именно не так. В большинстве случае Вам необходимо будет исправить ваш Pull Request, чтобы все проверки проходили успешно.

Шаг 8 — Перерабатываем Pull Request

Если с Вашим Pull Request всё хорошо, то в скором времени он будет смержен кем-то из команды.
Но часто бывает, что разработчики попросят Вас внести какие-то изменения.

Для этого просто возвращаемся к шагу 6 и после внесения изменений и коммита выполняем похожие команды:

git checkout <ИМЯ-ВАШЕЙ-ВЕТКИ>
git fetch upstream
git rebase upstream/master
git push origin <ИМЯ-ВАШЕЙ-ВЕТКИ>

Примечание: Лично я люблю отправлять Pull Request лишь с 1 коммитом. Для этого я делаю «squash» ненужных коммитов. Как это сделать можно прочитать здесь — gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html

Шаг 9 — Убираемся после себя

После того, как ваш Pull Request был принят или же отвергнут, Вам необходимо удалить ветку с Вашими изменениями.
Делается это просто

git checkout master
git branch -D <ИМЯ-ВАШЕЙ-ВЕТКИ>
git push origin --delete <ИМЯ-ВАШЕЙ-ВЕТКИ>

Вместо последней комманды такде можно выполнить

git push origin :<ИМЯ-ВАШЕЙ-ВЕТКИ>

Пожалуй это всё, что касается базовых вещей участия в Open Source проектах.
Хотел бы добавить, чтобы Вы не ленились и участвовали в Open Source проектах, это огромный и интересный опыт, а также галочка в резюме;)

Также, для PHP-разработчиков есть отличный гайд как контрибьютить в Symfony, он будет полезен не только при работе с Symfony
symfony.com/doc/current/contributing/index.html

Всем Спасибо!