Как изменить Ruxe Engine

Ruxe Engine является проектом с открытым исходным кодом и приветствует изменения от всех желающих. С недавних пор RE обзавёлся публичным репозиторием на сервисе GitHub, благодаря чему процесс внесения изменений упростился.

Итак, вас что-то не устраивает в Ruxe Engine, и вы хотите это самостоятельно исправить. Слова «Git» и «GitHub», могут быть и знакомы, но опыта работы с ними у вас нет? В таком случае, последующая инструкция позволит вам сделать свой первый Pull Request (предложить свои изменения) в Ruxe Engine. Для программистов, имеющих опыт работы с Git и GitHub, в конце статьи представлены рекомендации по работе с нашим репозиторием (как именовать ответвления, от какой ветки ответвляться и т.п.).

Что же, приступим.

 

1) Установка Git

1. На странице git-scm.com/downloads выберите свою операционную систему и установите Git согласно инструкции.

2. Передача данных между локальным и удалённым репозиторием будет осуществляться через SSH протокол. И для того, чтобы при каждом соединении не вводить пароль, используются SSH ключи. Если вы ещё не генерировали SSH ключ, то откройте консоль или терминал (в случае Linux, Mac), либо на рабочем столе из контекстного меню (вызовом правой кнопкой мыши по пустому месту) выберите пункт Git Bash (в случае Windows). Затем введите:

ssh-keygen -t rsa -C "ваш_email@сервер.ru"

На запрос о расположении файла ключа, нажмите клавишу Enter. Далее будет предложено задать пароль, но это необязательно.

3. Введите в консоли:

git config --global user.email "ваш_email@сервер.ru"
git config --global user.name "ваш_username"
git config --global core.autocrlf false

Консоль не закрывайте.

 

2) Регистрация на GitHub.com

1. Перейдите на страницу github.com и зарегистрируйтесь на сервисе.

Снимок экрана 2014-03-13 в 10.44.18

2. Перейдите в раздел Account Settings, нажав кнопку Edit Your Profile:

Снимок экрана 2014-03-13 в 11.48.18 копия

3. Затем в подраздел SSH Keys, нажав на соответствующую кнопку. Здесь добавляются публичные ключи. Когда вы генерировали SSH ключ, в консоли вы получили что-то вроде:

Your identification has been saved in ...
Your public key has been saved to in ...

Откройте файл, в который был сохранён публичный ключ, и скопируйте его содержимое. На открытой странице SSH Keys нажмите кнопку Add SSH Key и вставьте скопированное содержимое в поле «Key». Сохраните.

Снимок экрана 2014-03-13 в 12.03.36

4. Для проверки работоспособности, введите в консоли:

ssh -T git@github.com

На запрос продолжения соединения ответьте утвердительно (yes). Результат должен быть примерно таким:

Hi ваш_username! You've successfully authenticated, but GitHub does not 
provide shell access.

 

3) Форк Ruxe Engine

Напрямую в репозиторий Ruxe Engine вносить изменения может только определённый круг людей (одним из них можете стать и вы, если захотите). Другие люди могут только предлагать свои изменения (Pull Request). После чего владелец репозитория проверяет правку и, в случае её работоспособности и корректности, сохраняет изменения.

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

Снимок экрана 2014-03-13 в 13.04.22 копияТеперь уже можно начинать работать над RE. Для того, чтобы развернуть репозиторий на рабочем компьютере, выберите нужный каталог веб-сервера (в случае Windows — перейдите в нужную папку, затем, нажатием правой кнопки мыши по пустому месту в окне, вызовите контекстное меню, где выберите пункт Git Bash) и введите:

git clone git@github.com:ваш_username/ruxe-engine.git .

Форк репозитория RE не будет обновляться вместе с обновлением оригинального репозитория RE. Все новые изменения вам необходимо будет сливать в свой репозиторий самому. Это не сложно, скорее всего достаточно будет ввести одну команду, о которой будет сказано ниже.

Важно отслеживать изменения в репозитории RE, добавив привязку к RE репозиторию следующими командами:

git remote add re git://github.com/maindefine/ruxe-engine.git
git fetch re

 

4) Внесение изменений

Следующие действия выполняются каждый раз для каждой новой задачи. Инструкция показывает не самый корректный стиль работы с Git, но очень простой и достаточный для первого времени. Желающие смогут изучить основы Git по ссылкам в конце статьи.

1. Создайте или выберите существующий Issue на странице github.com/maindefine/ruxe-engine/issues.

Снимок экрана 2014-03-13 в 13.50.26В описании следует достаточно ясно выражать смысл правки. Один Issue для одной задачи. Не нужно делать сразу несколько задач в одной.

У каждого Issue есть номер (#номер). Он-то нам и нужен.

2. Перейдите через консоль в рабочий каталог проекта (или откройте консоль в рабочем каталоге проекта) и введите следующие команды:

git fetch re
git checkout re/dev
git checkout -b номер_Issue

Так мы ответвлимся от dev ветки RE репозитория. Почему от dev? Потому что master должна быть стабильной веткой, которую может скачать пользователь в любой момент. А dev ветка предназначена для разработки.

Каждая ветка — это самостоятельная версия проекта. Изменения в одной ветке не касаются других. Чтобы слить две ветки в одну, делают объединение (мёржинг). А ответвляются от определённой ветки для того, чтобы сделать новую ветку на основе необходимой. По инструкции все новые ветки ответвляются от re/dev. Это значит, что если требуются собственные изменения для последующих задач, то нужно дождаться, когда они будут применены в re/dev.

А потом, когда в re/dev будет готов и протестирован новый релиз RE, re/dev будет объединён с re/master владельцем репозитория.

3. Работаем над проектом. Можно создавать коммиты в новую ветку и пушить её на свой удалённый репозиторий:

git add имя_изменяемого_файла_(и_относительный_путь_до_него,_если_требуется)

...

git add ... (если нужно добавить в коммит ещё файлы)

...

git commit -m '#номер_Issue комментарий, описывающий изменения в коммите'
git push origin номер_Issue

Коммиты — это сохранение изменений и отправка их в репозиторий.

Старайтесь не добавлять в коммит файлы, которые не относятся к вашей правке. Например, конфигурацию в conf.

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

Обратите внимание: настройте свой редактор кода на использование UNIX-style конца строка (
) и кодировки UTF-8 (без BOM).

4. Когда работа над задачей завершена и протестирована, создаём коммит (если были изменения после последнего коммита):

git add имя_изменяемого_файла_(и_относительный_путь_до_него,_если_требуется)
git commit -m '#номер_Issue комментарий, описывающий изменения в коммите'
git push origin номер_Issue

5. Теперь заходим на страницу вашего репозитория на GitHub и выбираем branch с номером вашего Issue:

Снимок экрана 2014-03-13 в 14.17.09 копия

6. Затем нажимаем Pull Request:

Снимок экрана 2014-03-13 в 14.19.51 копия

7. GitHub по умолчанию создаёт Pull Request в master ветку, но нам важно предлагать изменения в dev ветку. Почему в dev? Как было сказано выше, master — стабильная ветка для загрузки RE пользователем в любой момент времени, а разработка новой версии RE осуществляется в dev ветке. Для того, чтобы выбрать dev ветку при создании Pull Request нажмите кнопку Edit:

Снимок экрана 2014-03-13 в 15.26.42 копияА затем измените base с master на dev:

Снимок экрана 2014-03-13 в 15.28.04 копияУкажите достаточно ясные заголовок и описание, после чего отправьте Pull Request.

8. Теперь ожидайте проверки вашего Pull Request владельцем репозитория RE. Следите за комментариями в вашем Issue и Pull Request. Если нужно будет модифицировать предложенную вами правку, то переключитесь на вашу ветку через консоль:

git checkout номер_Issue

 

5) Рекомендации

  1. Перед началом работы над новой задачей, необходимо создать или выбрать существующий Issue на странице: https://github.com/maindefine/ruxe-engine/issues;
  2. Ответвляться необходимо от dev ветки;
  3. Рабочая ветка должна иметь в качестве имени номер Issue;
  4. Конец строки в файлах должен быть UNIX-Style (
    );
  5. Кодировка файлов — UTF-8 (без BOM);
  6. Не добавлять в коммиты файлы, не относящиеся к правке (конфигурацию, например);
  7. Комментарий коммита желателен в формате:
    #номер_Issue достаточно ясное описание смысла изменений
  8. Pull Request должен быть применён к dev ветке.

 

Полезные ссылки

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *