Fullstack Software Engineer @ PandaDoc
0,0
рейтинг
16 января в 10:05

Разработка → Как правильно внести свою лепту в Open Source проект: простые подсказки

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
карма
56,2
рейтинг 0,0
Fullstack Software Engineer @ PandaDoc
Реклама помогает поддерживать и развивать наши сервисы

Подробнее
Спецпроект

Самое читаемое Разработка

Комментарии (41)

  • –16
    Предлагаю в комментариях устроить перепись репозиториев программ, к разработке которых вы имеете непосредственное отношение.

    ReactOS: github.com/reactos/reactos
    • +26
      Промоушн такой промоушн… :)
    • +9
      Я бы с удовольствием почитал, кто чем занимается.

      Минусующим: а смысл «промоутить» ReactOS? Во-первых, Jeditobe и так всем и каждому уши прожужжал, во-вторых, это исключительно СПО проект, никакой коммерции нет.
      • +2
        Ну разве что бюджетных денег от разработки нормальных Linux'ов отвлечь.
        • +4
          Назовите, сумму которую ReactOS уже «отвлек».
          А когда бюджетные деньги тратились на разработку Linux, там точно было целевое использование? Вспомним Пингвин Софтвер, различные юрлица Росы, как это все потом внезапно банкротилось. Может быть и не плохая идея, отвлекать деньги от такой «разработки» линуксов…
    • +3
      Давайте просто сразу ссылки на профили: github.com/0xd34df00d
  • +2
    Отличная статья, спасибо. От себя добавлю, что нормальные описания PR или Issue очень важны. Есть много статей о том, как правильно составлять баг-репорты, но я представляю идеальный баг-репорт так:

    1. Суть проблемы;
    2. Минимальный код для воспроизведения и описание окружения;
    3. Текущий результат;
    4. Ожидаемый результат.

    Навскидку несколько свежих примеров неудачных репортов: 1, 2, 3. В одних информации слишком мало и приходится догадываться, а в других она не помещается на 3 экрана и желание вчитаться быстро пропадает. В действительности, чтобы найти золотую середину, достаточно задать себе несколько вопросов: «Этой информации достаточно для воспроизведения проблемы без фантазирования?», «Я оставил только тот минимум кода, который относится к проблеме и необходим для воспроизведения?».
  • +2
    SilverFire Спасибо, рад, что понравилось!

    Я бы добавил как пример хорошего описания бага, на который недавно наткнулся, пример от SamDark
    github.com/yiisoft/yii2/issues/8015
  • +5
    Добавлю свои 5 копеек: основная проблема с которой я столкнулся в Symfony — твои изменения могут дожидаться своего часа месяцами, отсюда начинаются все проблемы и пропадает мотивация учавствовать на регулярной основе.
    • 0
      согласен, такая проблема существует.
      как я сам замечал, баги мержатся напорядок быстрее улучшений, естественно, чем серьёзнее баг, тем быстрее. Баги по безопасности по опыту в топе.

      данные советы как раз и направлены на то, чтобы пул риквест был рассмотрен как можно быстрее и удачно смержен.
      ведь для команды увидить хорошо составленный отчёт об ошибке, толковый пул риквест с тестами к нему — это только в радость.
    • +6
      В любом крупном проекте найдется хорошая стопка issue или PR, которые висят месяцами или даже годами. Залипают обычно некритичные и часто сложновоспроиводимые проблемы, улучшения, сломы обратной совместимости, неоттестированные опасные PR. Рассматривая новый PR всегда перебираешь варианты: а нужны ли эти изменения, не дублируют ли они что-то существующее, не сломается ли чего, не зарыт ли тут слом обратной совместимости, придется ли менять документацию, и так далее.

      Я раньше этого всего до конца не осознавал и сам думал «Блин, ну не уже ли нельзя смёржить то, ничего сложно нет», но после присоединения к Core-team начал невольно смотреть на это немного иначе. Каждый день — это поток изменений, комментариев, новых задач и PR. Случайные люди не видят этого, ведь кто захочет просто так получать 50+ уведомлений каждый день, и вчитываться в них и от всей души стараться решить чью-то проблему?

      Я однажды услышал версию, что это происходит из-за плохо организованной работы в команде и если принудительно раздавать задачи и контролировать их исполнение — все будет чётко и быстро. Утверждение толковое, но в Open-source оно не будет работать. Какую бы задачу я не взял, займет она у меня 10 минут или 5 часов, я это буду делать добровольно, с удовольствием, целью помочь сообществу и за идею. Такое принудительно не работает.
      • +1
        Все верно и я это все понимаю. Но тут встает проблема разделения ответственности. Если core team не справляется, то надо делегировать ответственность. Сейчас получается так — сори, у нас нету на это времени, до ваших PR и issue мы дойдем нескоро.

        То есть с одной стороны страдающая от нагрузки core team везде просит — помогите нам. С другой — извините, у нас нет времени на понять, а помогли ли вы нам.

        Это путь в никуда. Если рост core team не будет успевать за ростом проекта — это беда.
  • –30
    Все-таки git делали инопланетяне. Сайт, понятный и удобный только на чтение.
    • +12
      Ну так правильно, octocat же:

      Octocat
      image
    • +39
      Откуда вы берётесь, люди, которые не различают git и github? о_О
      • –24
        Различаем. Но сути это не меняет.
  • –9
    Автор, друзья, коллеги, разработчики — не забываем про ответственность: habrahabr.ru/post/274791
    • +7
      Если вы так жаждете ответственности, то вы выбрали не ту профессию.
      Вам стоило бы пойти в пилоты гражданской авиации, пожарную охрану или во врачи.
      • +4
        можно ведь ещё и софт для гражданской авиации писать
        • +1
          И заливать на гитхаб. Авось какой-нить Бойенгъ подключит либу.
        • 0
          Да и не только. Можно в производство уйти. Станки например программировать. Тут, кстати, не очень давно статья была об ошибках при построении автоматических и автоматизированных систем (что-то про аварийной отключение).
  • +1
    С submitting issue более-менее понятно, а вот по code distributing просветите такой момент — улучшение необходимо придумать самому или можно связаться с автором проекта и он назначит тебе таск из своего todo списка?
    • 0
      По моему опыту работают оба пункта. Можно запросить roadmap проекта и выбрать таск самому.
    • 0
      Вполне можно взять что-то толковое из issue, но за что пока ещё никто не брался. В идеале если авторы проекта написали в issue что-то вроде «да, это круто было бы реализовать, но пока времени нет».
    • 0
      тут всё зависит от конкретной ситуации и может быть несколько вариантов.
      часто бывает, что в обсуждении конкретного issue обсуждаются и идеи, как это можно исправить
      например, как здесь github.com/yiisoft/yii2/issues/10218
      в таком случае, обычно отправляется Pull Request с обсуждённым решением.

      иногда люди, при отправке issue, сразу предлагают в описании возможное решение, в таких случаях, если решение хорошее, делается Pull Request на его основе.

      но в большинстве случаев приходится самому приходится придумывать решение.

      в больших крупных проектах (да и не в крупных тоже) я видел ситуацию, когда issue на github привязывались к таскам, например, в trello, где уже было их детальное описание.

      но в общем и целом ситуация такова, что вы видите список issues на github и берёте из списка открытых, ни на кого не завязанных багов/улучшений и делаете для него Pull Request
  • +2
    Спасибо большое за статью. Как раз разбираюсь по теме, хорошо легла.

    Рискую отхватить по карме, но тут знающая аудитория собралась и поэтому всё-таки спрошу про subtree (там ещё ссылка на первый вопрос есть). Буду очень благодарен за ответ.
  • +4
    Как-то однобоко, честно говоря. Далеко не все проекты принимают pull request через github, у многих патчи принимаются исключительно через почтовую рассылку, а pull request на github не отключаются, и патчи висят годами, т.к. никто из разработчиков туда не заходит.
    Вот, лучше бы об отправке патчей в рассылки рассказали, т.к. почтовые программы ломают патчи, требуют специальной настройки, и лучше всего настроить git на отправку email через send-email.
    • +1
      Удобнее всего прикладывать патч как вложение. Работает с любым клиентом, и ничего не ломается.
      • +1
        У меня Thunderbird ломал даже патч во вложении. Не всем удобно принимать вложение.
        • +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.
    • +2
      А ещё мир гитом не ограничен. Убунтовские поделки практически все лежат на launchpad и используют bazaar.
  • +4
    Еще очень удобно в сообщении коммита делать референс на issue с которым он связан, как показано здесь. Тогда, при мерже кода в ветку по умолчанию, те issue, которые исправляет ваш pull request, будут закрыты автоматически.
  • 0
    Не освещен сценарий вендоринга, в котором Pull Request отклонен но правки необходимы вам для собственного проекта. Ветку со своими изменениями вы тогда вовсе не намерены удалять, и желаете еще поддерживать актуальной.
    • 0
      Влить ветку в свой мастер и иногда синхронизировать с апстримом. Делов-то.
      • 0
        Тонкость в том, что мержить нужно на локальной машине, а потом пушить на свой форк на хабе. Я например не сразу понял что только так и можно, github у себя эту операцию не делает.
        • +3
          Это не тонкость. Это документированное поведение. Не нужно ждать, пока снизойдёт озарение, достаточно прочитать брошюрку.
          • 0
            Ну и у локального репо должны быть два remote, тоже тонкость. И да, документированное поведение, так и статья не про rocket science. Хорошая статья, про документированное поведение. Вендоринг распространенное явление, чаще чем коммиты в апстрим.
            • +1
              локального репо должны быть два remote
              В любой книжке по гиту есть разбор случая, когда вообще нет центрального сервера. Разработчики делятся изменениями прямо из своего локального репозитория напрямую. Итого у нас не 2 удалённых репозитория, а столько, сколько разработчиков в команде. Опять же это не тонкость. Это нормальное поведение гита, для этого, собственно, он и разрабатывался.
        • 0
          А вообще можно же сделать PR самому себе. Тем самым смержив ветки на стороне github.
  • 0
    Не хотелось бы начинать холивар, но почему rebase, а не merge? После того, как вы выложили свою ветку в общий доступ (сделали PR) rebase может очень сильно навредить тем, кто решит взять напрямую ваш PR.

Только зарегистрированные пользователи могут оставлять комментарии. Войдите, пожалуйста.