Рабочий процесс Git для разработчиков Yii2

Итак, вы хотите разрабатывать Yii? Хорошо! Но для того чтоб увеличить шанс принятия ваших изменений, пожалуйста следуйте следующим шагам. Если вы новичок в git и github, вы можете сначала проверить github help, try git или прочитать о внутренней модели данных git.

Подготовка вашего рабочего окружения

Следующие шаги будут создавать рабочее окружение для Yii, которое вы можете использовать для работы над основным кодом фреймворка. Эти шаги будут нужны только в первый раз.

1. Форкаем репозиторий Yii на github и клонируйте ваш форк в ваше рабочее окружение.

git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git

Если у вас есть проблемы с настройкой GIT для работы с GitHub в Linux, или вы получаете ошибку похожую на "Permission Denied (publickey)", тогда вы должны настроить ваш GIT по этой инструкции

2. Добавляем главный репозиторий Yii как дополнительный внешний git репозиторий называемый "upstream"

Перейдите в каталог, куда вы склонировали Yii, как правило "yii2". Затем введите следующую команду:

git remote add upstream git://github.com/yiisoft/yii2.git

3. Настройка тестовой среды

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

• выполните composer update для установки зависимостей (если composer у вас установлен глобально).
• выполните php build/build dev/app basic для клонирования базового приложения и установки его зависимостей. Эта команда установит сторонние пакеты composer обычным образом, но создаст ссылку с репозитория yii2 на только что загруженный репозиторий. Таким образом у вас будет только один экземпляр кода.

При необходимости делаем тоже самое для приложения advanced: php build/build dev/app advanced.

Данная команда также может быть использована для обновления зависимостей, внутри она использует composer update.

Теперь у нас есть рабочая площадка для экспериментов с Yii 2.

Следующие шаги не обязательны.

Модульные тесты

Вы можете выполнить модульные тесты с помощью команды phpunit в корневой директории приложения. Если у вас phpunit не установлен глобально, вы можете запустить php vendor/bin/phpunit.

Некоторые тесты требуют дополнительно установки и настройки баз данных. Вы можете создать tests/data/config.local.php для переопределения настроек, которые определены в tests/data/config.php.

Вы можете ограничить тестирование группой тестов, с которой вы сейчас работаете, например запускать только тесты для валидаторов и redis. Вы можете получить список доступных групп выполнив phpunit --list-groups.

Расширения

Для работы над расширениями вы можете склонировать репозиторий расширения. Мы сделали команду, которая поможет вам сделать это:

php build/build dev/ext <extension-name>

где <extension-name> это имя расширения, например redis.

Если вы хотите протестировать расширение в одном из шаблонов приложений, просто добавьте его в composer.json приложения, например добавив "yiisoft/yii2-redis": "*" в секцию require базового приложения. Запустите php build/build dev/app basic для установки расширения и его зависимостей и создания символической ссылки на extensions/redis так чтоб вы работали не папке вендорных пакетов composer, а напрямую в репозиторий yii2.

Работа над багами и новыми функциями

Приготовив вашу среду разработки вы можете начать работу над исправлением багов и разработкой новых функций.

1. Убедитесь, что issue создана для того, над чем вы работаете, если потребуется много времени для исправления

Все новые функции и баги должны быть связаны с issue для того, чтоб иметь единое место для обсуждения и документирования. Потратьте несколько минут на поиск существующей issue, которая соответствует вашим изменениям. Если вы найдёте её в списке, то пожалуйста оставьте комментарий, что вы начали над ней работать. Если вы не нашли нужной issue пожалуйста создайте новую issue или создайте сразу запрос на изменения если это простые изменения. Это позволит команде проверить ваше предложение, и обеспечивать соответствующую обратную связь.

Для небольших изменении или документации, или простых исправлений, вам нет необходимости создавать issue, запрос на изменения в этом случае подходит лучше.

2. Вытягивание последнего кода из основного репозитория Yii

git fetch upstream

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

3. Создание новой ветки для ваших изменений, основанных на текущем мастере Yii

Это очень важно, так как вы не сможете отправлять более одного запроса на изменения из вашего репозитория, если будете использовать ветку master.

Каждая отдельное исправление или изменение должно разрабатываться в своей ветке. Имя ветки должно быть описательным и начинаться с номера issue, с которым связан ваш код. Если вы не исправляете какой-то конкретный issue, просто пропустите номер. Например:

git checkout upstream/master
git checkout -b 999-name-of-your-branch-goes-here

4. Делайте свою магию, пишите ваш код

Убедитесь, что он работает :)

Модульные тесты всегда приветствуются. Протестированный и с хорошим покрытием код значительно упрощает задачу проверки вашего предложения. Сломанные модульные тесты, как описание проблемы, тоже приветствуются.

5. Обновите CHANGELOG

Отредактируйте файл CHANGELOG, включив ваши изменения. Для этого нужно вставить строки в начало файла под заголовком "Work in progress", строки с описанием изменений должны выглядеть похожими на следующие:

Bug #999: a description of the bug fix (Your Name)
Enh #999: a description of the enhancement (Your Name)

#999 это номер issue описывающей Bug или Enh. Лог изменений должен быть сгруппирован по типу (Bug,Enh) и отсортирован по номеру issue.

Для очень маленьких исправлений, например опечаток и изменений документации, нет необходимости обновлять CHANGELOG.

6. Фиксация ваших изменений

Добавляем файлы/изменения которые вы хотите зафиксировать в staging area

git add path/to/my/file.php

Вы можете использовать опцию -p для того, чтоб выбрать, какие изменения вы хотите добавить в коммит.

Фиксируйте ваши изменения с описательным сообщением. Убедитесь что в сообщение есть номер #XXX, так github автоматически свяжет ваш коммит с тикетом:

git commit -m "A brief description of this change which fixes #999 goes here"

7. Получение последнего кода из апстрима Yii в вашу ветку

git pull upstream master

Это гарантирует, что вы используете самый последний код в вашей ветке перед отправкой запроса на изменения. Если есть какие-либо конфликты слияния, вы должны исправить их и зафиксировать изменения ещё раз. Это гарантирует, что команда Yii сможет слить ваши изменения одним кликом.

8. Разрешив зависимости, отправляем код на github

git push -u origin 999-name-of-your-branch-goes-here

Опция -u сохранит указание на ветку в github, чтобы при следующем выполнении git push, git знал, куда отправлять изменения. Это полезно, если вы хотите позже отправлять ещё коммиты в этот запрос на слияние.

9. Открываем запрос на слияние в upstream.

Перейдите в репозиторий на github и нажмите "Pull Request", выберите ветку справа и введите больше информации в поле комментариев. Чтобы связать запрос на изменение с issue, добавьте в комментарий #999 - где 999 это номер issue.

Обратите внимание, что каждый запрос на слияние должен исправлять единственное изменение. Для множества независимых изменений, пожалуйста откройте несколько запросов на слияние.

10. Проверка вашего кода кем-то

Кто-то будет проверять ваш код, и, возможно, вам будет предложено внести некоторые изменения, если это так, то перейдите к шагу #6 (вам не надо открывать новый запрос на слияние, если текущий ещё открыт). Если код будет принят, он будет влит в основную ветку и станет частью следующего релиза Yii. Если нет, не унывайте, разным людям необходимы различные функции и Yii не может реализовывать всё для всех, ваш код будет ещё доступен на github как ссылка для людей кому он может пригодится.

11. Очистка

После того, как код был принят или отклонён, вы можете удалить ветки, над которыми вы работали в локальном репозитории и в origin.

git checkout master
git branch -D 999-name-of-your-branch-goes-here
git push origin --delete 999-name-of-your-branch-goes-here

Примечание:

Для обнаружения регрессии как можно раньше, каждое слияние кодовой базы Yii на github будет подхвачено Travis CI для автоматического запуска тестов. Люди из core team не хотят нагружать этот сервис, поэтому добавляют текст [ci skip] в описание запроса на слияние, в следующих ситуациях:

• затронуты только javascript, css файлы или файлы изображений,
• обновление документации,
• изменения затрагивают только строки (например обновление переводов).

Это защитит travis от запуска тестов на изменениях, которые не покрыты тестами.

Обзор команд (для продвинутых участников)

git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git
git remote add upstream git://github.com/yiisoft/yii2.git

git fetch upstream
git checkout upstream/master
git checkout -b 999-name-of-your-branch-goes-here

/* ваша магия, обновление changelog если нужно */

git add path/to/my/file.php
git commit -m "A brief description of this change which fixes #999 goes here"
git pull upstream master
git push -u origin 999-name-of-your-branch-goes-here