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).
Так же Вы можете поучаствовать в улучшении документации, ответах на вопросы, возникщих у других разработчков и многое другое.
Отправка Issue
Если Вы захотели уведомить разработчиков о какой-либо найденной ошибке или улучшении, Вам необходимо создать соответствующий GitHub Issue.
Но перед тем, как создавать его, проверьте, не существует ли уже такого же или похожего, созданного кем-либо другим.
Перед созданием также не забудьте ознакомиться с правилами отправки отчёта об ошибке для данного проекта. К примеру, вот правила для Yii Framework
Обычно, описание должно быть максимально чётким, понятным, желательно наличие примеров и описания как воспроизвести ошибку. Это сэкономит огромное время и разработчикам, и Вам, так как избавит Вас от ответа на уточнящие вопросы и т.д.
Отправка Pull Request
Если вы нашли 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
Всем Спасибо!
Автор: andrewnester
