Как начать участвовать в Open Source

Какое-то время назад я считал, что порог вхождения в OpenSource-разработку очень высок — ведь надо использовать git, отправлять пулл-реквесты. Это было чем-то незнакомым, далеким и останавливало меня. Тем более, что весь github.com на английском и многие слова и, соответственно, функции непонятны.

Однако сейчас я понимаю, как ошибался. Надеюсь, что после этой статьи вы согласитесь со мной и начнете вносить свой вклад в сообщество Open Source (и сообщество MODX в частности). Предлагаю на примере разобрать, как помочь разработчикам радовать нас дополнениями и уроками.

Я давно уже видел одно дополнение — modxSDK, но пользоваться им стал недавно. Заметил, что не все фразы и кнопки переведены. Мне особо не мешает, а новым пользователям может быть неудобно. Давайте, начнем наш вклад с малого — просто переведем поля и кнопки.

Если вы не зарегистрированы на сайте github.com, самое время это сделать. Кроме аккаунта на Gihub нам понадобится сайт на MODX и доступ к нему с помощью SSH. На Windows для подключения я пользуюсь утилитой Putty (скачать), а в Ubuntu достаточно терминала.

В первую очередь, заходим на страничку нужного нам репозитория и нажимаем кнопку Fork. Теперь у вас есть своя версия этого дополнения)

Теперь нам нужно исходный код дополнения выгрузить на сайт, чтобы мы могли его изменять и тут же проверять. Открываем терминал (подключаемся к нашему серверу по SSH) и переходим в папку сайта:
cd modextra.ilyaut.ru/public_html/

И в этой папке выполняем следующую команду:
git clone https://github.com/ilyautkin/modxSDK
(вместо ilyautkin пишем свой логин, а вместо modxSDK — название репозитория)

После этого побегут циферки, указывающие на прогресс «скачивания» исходного кода в вашу папку. Когда все скачается, можно открыть админку нашего сайта и увидеть в файловой системе новую директорию. У меня это modxSDK.

Теперь нам надо сгенерировать пакет для установки, чтобы проверять, что мы там напрограммировали) Открываем http://sitename.ru/modxSDK/_build/build.transport.php. У меня ничего не сгенерировалось — просто белый экран. Обычно это происходит из-за того, что у разных разработчиков дополнения находятся в разных папках. Посмотрим, например, в файл modxSDK/_build/build.config.php:
...
/*
 * Include MODX config
 */
require_once dirname(dirname(dirname(dirname(__FILE__)))).'/core/config/config.inc.php';
...

Видимо, у автора есть отдельная папка для дополнений. А мы папку создали прямо в корне. Давайте, создадим новую папку и перенесем наш каталог в нее, чтобы автор потом не мучился с перепроверкой нашей писанины)
mkdir extras
mv modxSDK/ extras/
У меня после этого файл build.transport.php запустился нормально и показал сообщение об успешной генерации пакета.

Чаще всего пакет генерируется уже сразу в папку /core/packages/, так что идем в Управление пакетами → Искать локально и устанавливаем дополнение. Некоторые разработчики настраивают автоматическую установку пакета после генерации. В таком случае устанавливать уже ничего не надо будет)

Все, подготовка закончена. Теперь мы можем менять код, открывать в браузере файл build.transport.php, переустанавливать пакет и проверять, что мы все поменяли правильно. Для перевода мы идем в папку /core/components/modxsdk/lexicon/ и вносим изменения в файл /core/components/modxsdk/lexicon/ru/default.inc.php

Не бойтесь вносить изменения в несколько файлов — потом мы разом отправим все файлы.

Исправьте версию дополнения в файле /_build/build.transport.php и напишите changelog в файл /core/components/modxsdk/docs/changelog.txt

Когда работа закончена, все проверено, пакет устанавливается, все работает как надо, нужно сохранить все изменения в своем аккаунте на Github. Кстати, сохраняться можно периодически, пока вы работаете — закончили с каким-то моментом, отправьте изменения на Github.

Чтобы это сделать, переходим внутрь рабочей папки:
cd extras/modxSDK/
Индексируем все изменения в файлах:
git add -A
И сохраняем изменения локально:
git commit
После этих действий у вас откроется консольный редактор, в котором будет перечислен список измененных файлов. Например, такой:



Здесь в первой строчке нужно кратко описать, что за изменения вы внесли. Желательно, на английском. 5-7 слов)

Я напишу так:
Added lexicons and translates
Нажимаем Ctrl+O (сохранить), Enter («да»), Ctrl+X (закрыть редактор).

Локально сохранились. Теперь отправим все изменения на github.com:
git push https://ilyautkin@github.com/ilyautkin/modxSDK
Не забываем менять логин на свой и указывать нужный репозиторий.

После этого у вас спросят пароль от Github'а и, если пароль правильный, отправят все, что мы накодили на сервер. Теперь можно зайти на страничку своего репозитория и проверить, что весь код на месте. Если все ОК, нажимаем на зеленую кнопку (Compare, review, create a pull request):

Вы увидите все изменения, которые вы внесли. Поверьте, это очень приятно, когда ты смотришь именно вот так на творение своих рук))) Нажимаем большую зеленую кнопку «Create Pull Request» и заполняем краткое описание — можно уже на русском (если разработчик говорит на русском)). Описание нужно, чтобы автор быстро понял, что именно вы сделали.

Осталось только дождаться, когда автор нажмет у себя кнопку Merge и ваше имя будет увековечено в сообществе Open Source.

Возможно несколько сумбурно написал и опять кажется сложно. В своем блоге я выложил краткую инструкцию, которую можно открывать каждый раз, когда вы захотите оставить свой вклад в развитии MODX: http://ilyaut.ru/tips-and-tricks/github-for-dummies/

Вот пулл-реквест, в котором можно увидеть измененные файлы. У вас скоро будет похожий, да не один))
Илья Уткин
25 апреля 2014, 00:14
modx.pro
14
6 136
+9

Комментарии: 11

Михаил
25 апреля 2014, 11:34
0
Я пока тоже немного от этого отошел что ли. Заморочек много, или я немного не догоняю. Но удобно тем что можно всегда глянуть что сделал или вернуть на какой то этап назад. Еще было бы не плохо если написали статью, как сделать 2 сервера, один для разработки а с него уже на паблик заливать
    Илья Уткин
    25 апреля 2014, 11:49
    0
    Это очень удобно. И приятно))

    Я сначала пробовал на Windows визуальный клиент для Github'а, но он на самом деле сложнее (по крайней мере, для меня), чем работа через консоль.
      Михаил
      25 апреля 2014, 12:03
      0
      На Windows вроде визуальный клиент не сложный. Хотя да через консоль проще
    Alex Vakhitov
    25 апреля 2014, 11:50
    0
    Вместо ввода пароля можно добавить публичный SSH ключ на github и пользоваться такими ссылками git@github.com:ilyautkin/modxSDK.git, при пушах ненужно указывать ссылку на репозиторий он и так отправится туда куда нужно, в ветку которая определена как основная.

    Это так что резко в глаза бросилось, чтобы проще потом было работать (:
      Andrey Grachov
      25 апреля 2014, 11:58
      0
      Насчет ссылки на репозиторий при push/pull — если хочется указать ее для надежности, можно писать не полную ссылку, а ее дефолтное имя — origin.
        Alex Vakhitov
        25 апреля 2014, 12:02
        0
        тогда уже правильней писать ее с веткой (: просто невижу смысла это делать для репозиториев без веток и находящихся на одном сервере, ошибки с ссылкой на репозиторий случаются очень редко при условиях описанных выше, а если что пойдет нетак то git сам же выдаст ошибку, ее можно будет исправить за минуту с гуглением и дальше не использовать лишнии буквы в команде (:
      Andrey Grachov
      25 апреля 2014, 12:02
      0
      Хоть это и внесет сложности, думаю стоит упомянуть про ветки и делать изменения для каждого пул-реквеста в отдельной ветке. Потому что, если пул-реквест отправлен и вы добавите новых коммитов в ту же ветку, они автоматически присоединятся к пул-реквесту. То есть получается, что используя одну ветку, необходимо постоянно ждать пока пул-реквест примут, чтобы сделать следующие изменения.
      Также стоит упомянуть, что если правка очень простая и затрагивает один файл, можно сделать изменения прямо на сайте Github в целевом репозитории, что приведет к прозрачному созданию пул-реквеста :)
        Alex Vakhitov
        25 апреля 2014, 12:06
        0
        И здесь мы приходим к выводу что ветки необходимы и это одна из главных фич контроля версий (: И лучше логику этого изучать с самого начала (:
          Andrey Grachov
          25 апреля 2014, 13:10
          0
          Я не отрицал их необходимость :) Это скорее было предостережение о том, что при таком подходе в пул-реквест могут случайно уйти лишние изменения.
        Илья Уткин
        25 апреля 2014, 12:06
        +2
        Вообще эта статья для тех, кто никак не может попробовать. По статье можно наконец-то сделать свои первые коммиты и пуши. А дальше уже изучать git можно, например по туториалу с сайта githowto.com/ru
          Delovita
          25 апреля 2014, 17:05
          +1
          Илья, спасибо! Изменения в проект приняты, новая версия пакета выложена.
          Авторизуйтесь или зарегистрируйтесь, чтобы оставлять комментарии.
          11