Такие проекты как 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
Всем Спасибо!
Комментарии (41)
SilverFire
16.01.2016 14:16+2Отличная статья, спасибо. От себя добавлю, что нормальные описания PR или Issue очень важны. Есть много статей о том, как правильно составлять баг-репорты, но я представляю идеальный баг-репорт так:
1. Суть проблемы;
2. Минимальный код для воспроизведения и описание окружения;
3. Текущий результат;
4. Ожидаемый результат.
Навскидку несколько свежих примеров неудачных репортов: 1, 2, 3. В одних информации слишком мало и приходится догадываться, а в других она не помещается на 3 экрана и желание вчитаться быстро пропадает. В действительности, чтобы найти золотую середину, достаточно задать себе несколько вопросов: «Этой информации достаточно для воспроизведения проблемы без фантазирования?», «Я оставил только тот минимум кода, который относится к проблеме и необходим для воспроизведения?».
SamDark
16.01.2016 15:30+1По поводу пункта 2 я раскрывал как-то тему: rmcreative.ru/blog/post/minimalnyy-testovyy-nabor. Если не ясно, почему возникает проблема, можно попробовать делить пополам: rmcreative.ru/blog/post/poisk-trudnovylovimoy-oshchibki-deleniem-popolam. В git для этого есть bisect.
andrewnester
16.01.2016 14:23+2SilverFire Спасибо, рад, что понравилось!
Я бы добавил как пример хорошего описания бага, на который недавно наткнулся, пример от SamDark
github.com/yiisoft/yii2/issues/8015
ewgRa
16.01.2016 14:30+5Добавлю свои 5 копеек: основная проблема с которой я столкнулся в Symfony — твои изменения могут дожидаться своего часа месяцами, отсюда начинаются все проблемы и пропадает мотивация учавствовать на регулярной основе.
andrewnester
16.01.2016 14:35согласен, такая проблема существует.
как я сам замечал, баги мержатся напорядок быстрее улучшений, естественно, чем серьёзнее баг, тем быстрее. Баги по безопасности по опыту в топе.
данные советы как раз и направлены на то, чтобы пул риквест был рассмотрен как можно быстрее и удачно смержен.
ведь для команды увидить хорошо составленный отчёт об ошибке, толковый пул риквест с тестами к нему — это только в радость.
SilverFire
16.01.2016 15:41+6В любом крупном проекте найдется хорошая стопка issue или PR, которые висят месяцами или даже годами. Залипают обычно некритичные и часто сложновоспроиводимые проблемы, улучшения, сломы обратной совместимости, неоттестированные опасные PR. Рассматривая новый PR всегда перебираешь варианты: а нужны ли эти изменения, не дублируют ли они что-то существующее, не сломается ли чего, не зарыт ли тут слом обратной совместимости, придется ли менять документацию, и так далее.
Я раньше этого всего до конца не осознавал и сам думал «Блин, ну не уже ли нельзя смёржить то, ничего сложно нет», но после присоединения к Core-team начал невольно смотреть на это немного иначе. Каждый день — это поток изменений, комментариев, новых задач и PR. Случайные люди не видят этого, ведь кто захочет просто так получать 50+ уведомлений каждый день, и вчитываться в них и от всей души стараться решить чью-то проблему?
Я однажды услышал версию, что это происходит из-за плохо организованной работы в команде и если принудительно раздавать задачи и контролировать их исполнение — все будет чётко и быстро. Утверждение толковое, но в Open-source оно не будет работать. Какую бы задачу я не взял, займет она у меня 10 минут или 5 часов, я это буду делать добровольно, с удовольствием, целью помочь сообществу и за идею. Такое принудительно не работает.ewgRa
16.01.2016 21:11+1Все верно и я это все понимаю. Но тут встает проблема разделения ответственности. Если core team не справляется, то надо делегировать ответственность. Сейчас получается так — сори, у нас нету на это времени, до ваших PR и issue мы дойдем нескоро.
То есть с одной стороны страдающая от нагрузки core team везде просит — помогите нам. С другой — извините, у нас нет времени на понять, а помогли ли вы нам.
Это путь в никуда. Если рост core team не будет успевать за ростом проекта — это беда.
dom1n1k
16.01.2016 15:06-30Все-таки git делали инопланетяне. Сайт, понятный и удобный только на чтение.
semenyakinVS
16.01.2016 15:40+12Ну так правильно, octocat же:
Octocatdrdimitru
16.01.2016 15:12-9Автор, друзья, коллеги, разработчики — не забываем про ответственность: habrahabr.ru/post/274791
Maccimo
16.01.2016 21:02+7Если вы так жаждете ответственности, то вы выбрали не ту профессию.
Вам стоило бы пойти в пилоты гражданской авиации, пожарную охрану или во врачи.andrewnester
16.01.2016 21:04+4можно ведь ещё и софт для гражданской авиации писать
neit_kas
21.01.2016 18:32Да и не только. Можно в производство уйти. Станки например программировать. Тут, кстати, не очень давно статья была об ошибках при построении автоматических и автоматизированных систем (что-то про аварийной отключение).
devbutch
16.01.2016 15:18+1С submitting issue более-менее понятно, а вот по code distributing просветите такой момент — улучшение необходимо придумать самому или можно связаться с автором проекта и он назначит тебе таск из своего todo списка?
drdimitru
16.01.2016 15:25По моему опыту работают оба пункта. Можно запросить roadmap проекта и выбрать таск самому.
SamDark
16.01.2016 15:26Вполне можно взять что-то толковое из issue, но за что пока ещё никто не брался. В идеале если авторы проекта написали в issue что-то вроде «да, это круто было бы реализовать, но пока времени нет».
andrewnester
16.01.2016 15:30тут всё зависит от конкретной ситуации и может быть несколько вариантов.
часто бывает, что в обсуждении конкретного issue обсуждаются и идеи, как это можно исправить
например, как здесь github.com/yiisoft/yii2/issues/10218
в таком случае, обычно отправляется Pull Request с обсуждённым решением.
иногда люди, при отправке issue, сразу предлагают в описании возможное решение, в таких случаях, если решение хорошее, делается Pull Request на его основе.
но в большинстве случаев приходится самому приходится придумывать решение.
в больших крупных проектах (да и не в крупных тоже) я видел ситуацию, когда issue на github привязывались к таскам, например, в trello, где уже было их детальное описание.
но в общем и целом ситуация такова, что вы видите список issues на github и берёте из списка открытых, ни на кого не завязанных багов/улучшений и делаете для него Pull Request
semenyakinVS
16.01.2016 15:44+2Спасибо большое за статью. Как раз разбираюсь по теме, хорошо легла.
Рискую отхватить по карме, но тут знающая аудитория собралась и поэтому всё-таки спрошу про subtree (там ещё ссылка на первый вопрос есть). Буду очень благодарен за ответ.
ValdikSS
16.01.2016 22:29+4Как-то однобоко, честно говоря. Далеко не все проекты принимают pull request через github, у многих патчи принимаются исключительно через почтовую рассылку, а pull request на github не отключаются, и патчи висят годами, т.к. никто из разработчиков туда не заходит.
Вот, лучше бы об отправке патчей в рассылки рассказали, т.к. почтовые программы ломают патчи, требуют специальной настройки, и лучше всего настроить git на отправку email через send-email.
kafeman
17.01.2016 00:25+1Удобнее всего прикладывать патч как вложение. Работает с любым клиентом, и ничего не ломается.
ValdikSS
17.01.2016 03:45+1У меня Thunderbird ломал даже патч во вложении. Не всем удобно принимать вложение.
kafeman
17.01.2016 13:23+1Аналогично Thunderbird, до сих пор никто не жаловался. Почему неудобно? Большинство программ отображают такие вложения сразу после тела сообщения.
Вот, например, пожелания разработчиков Wine:
The git send-email command is strongly recommended, but if you can't get it to work, you may send the patch file as an attachment. Remember to only attach one patch per email and use the subject line from the patch file as the subject line in the email. Also, always send your emails as plain text, not HTML or rich text.
fshp
17.01.2016 16:44+2А ещё мир гитом не ограничен. Убунтовские поделки практически все лежат на launchpad и используют bazaar.
RomanPavlov
16.01.2016 22:59+4Еще очень удобно в сообщении коммита делать референс на issue с которым он связан, как показано здесь. Тогда, при мерже кода в ветку по умолчанию, те issue, которые исправляет ваш pull request, будут закрыты автоматически.
uvelichitel
17.01.2016 16:21Не освещен сценарий вендоринга, в котором Pull Request отклонен но правки необходимы вам для собственного проекта. Ветку со своими изменениями вы тогда вовсе не намерены удалять, и желаете еще поддерживать актуальной.
fshp
17.01.2016 16:45Влить ветку в свой мастер и иногда синхронизировать с апстримом. Делов-то.
uvelichitel
17.01.2016 17:12Тонкость в том, что мержить нужно на локальной машине, а потом пушить на свой форк на хабе. Я например не сразу понял что только так и можно, github у себя эту операцию не делает.
fshp
17.01.2016 17:15+3Это не тонкость. Это документированное поведение. Не нужно ждать, пока снизойдёт озарение, достаточно прочитать брошюрку.
uvelichitel
17.01.2016 17:26Ну и у локального репо должны быть два remote, тоже тонкость. И да, документированное поведение, так и статья не про rocket science. Хорошая статья, про документированное поведение. Вендоринг распространенное явление, чаще чем коммиты в апстрим.
fshp
17.01.2016 17:31+1локального репо должны быть два remote
В любой книжке по гиту есть разбор случая, когда вообще нет центрального сервера. Разработчики делятся изменениями прямо из своего локального репозитория напрямую. Итого у нас не 2 удалённых репозитория, а столько, сколько разработчиков в команде. Опять же это не тонкость. Это нормальное поведение гита, для этого, собственно, он и разрабатывался.
fshp
17.01.2016 17:25А вообще можно же сделать PR самому себе. Тем самым смержив ветки на стороне github.
WhiteAngel
20.01.2016 18:27Не хотелось бы начинать холивар, но почему rebase, а не merge? После того, как вы выложили свою ветку в общий доступ (сделали PR) rebase может очень сильно навредить тем, кто решит взять напрямую ваш PR.
Jeditobe
Предлагаю в комментариях устроить перепись репозиториев программ, к разработке которых вы имеете непосредственное отношение.
ReactOS: github.com/reactos/reactos
Indexator
Промоушн такой промоушн… :)
reactos
Я бы с удовольствием почитал, кто чем занимается.
Минусующим: а смысл «промоутить» ReactOS? Во-первых, Jeditobe и так всем и каждому уши прожужжал, во-вторых, это исключительно СПО проект, никакой коммерции нет.
musuk
Ну разве что бюджетных денег от разработки нормальных Linux'ов отвлечь.
Jeditobe
Назовите, сумму которую ReactOS уже «отвлек».
А когда бюджетные деньги тратились на разработку Linux, там точно было целевое использование? Вспомним Пингвин Софтвер, различные юрлица Росы, как это все потом внезапно банкротилось. Может быть и не плохая идея, отвлекать деньги от такой «разработки» линуксов…
0xd34df00d
Давайте просто сразу ссылки на профили: github.com/0xd34df00d