Работа в функциональных ветках

Этот документ объясняет механизм ветвления и то, каким образом публиковать свои изменения в GitLab.

Терминология

master: главная ветвь проекта. Обычно ветки создаются от master. Вы не должны делать свою работу напрямую в master и должны создавать новые ветки для каждой задачи над которой вы работаете самостоятельно или сообща. Когда работа закончена выполняется слияние вашей ветки обратно в master. Ветвление и слияние в Git должно стать частью вашего ежедневного рабочего процесса.

origin: основной удалённый репозиторий в котором вы публикуете свои изменения и из которого получаете изменения других разработчиков.

Ветки

Две основные долгоживущие ветки:

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

Настройка GitLab аккаунта

GitLab должен знать что вам разрешено делать, а что нет. Для этого вам нужно настроить доступ по SSH-ключам. Это описано здесь

Цикл разработки

Мы используем подход, основанный на мерж-реквестах. Багфиксы и доработки должны быть опубликованы в собственной ветке разработчика, которая создаётся специально под задачу.
Затем создаётся запрос на слияние новой ветки с веткой master в основном репозитории. Следует избегать публикации непосредственно в ветку master.

Добавление изменений
# переключаемся на master т.к. хотим чтобы новая ветка пошла от master
git checkout master
# обновляем master чтобы получить последние правки других разработчиков
git pull
# создаём новую ветку под задачу
git checkout -b my-feature
...работаем над задачей...
# добавляем результат работы в индекс
git add -A
# коммитим изменения в локальный репозиторий на созданную ветку
git commit -m "My changes"
# публикуем изменения в общем репозитории
git push -u origin my-feature

Правила именования коммитов

Комментарии к правкам следует писать по-русски в кодировке UTF-8.
Многострочный комментарий состоит из однострочного заголовка отделённого от тела пустой строкой.
Длина строки заголовка и тела не должна превышать 80 символов.
Тело комментария должно содержать информацию о том что сделано и зачем это было сделано.
Многострочный комментарий используется при необходимости детализировать назначение набора изменений.
Если правка относится к задаче в трекере, в заголовке указывается номер задачи Jira.

Например:

IS-1276. Экспорт РПП в формат CSV. Выгрузка НДС в назначении платежа.

Правила именования веток

Имена функциональных веток должны кратко, в 1-2-3-4 слова (слова разделяются дефисом), характеризовать назначение ветки.
Нет необходимости включать в наименование ничего не значащие или понятные только вам аббревиатуры, постфиксы, указания на нежелаемое поведение.

Хороший пример: fix-service-control

Плохой пример: ab1000610777_notStmt-branch - WTF?!

Создание merge request

Идём на GitLab, находим модуль, в котором мы опубликовали свою ветку, далее на закладке Merge requests и нажимаем кнопку Create merge request.

Вводим Title. Заголовок обязательно должен включать номер задачи в Jira и тему, характеризующую изменения.
В Description можем указывать какие именно изменения были сделаны, почему предпочтение отдано именно такому подходу.
Дополнительно здесь можно указать информацию, которая может быть полезна ревьюверу чтобы сориенироваться в предлагаемых правках.
А также упомянуть тех, кому эти изменения могут быть интересны (чьё мнение вам важно). Для этого введите /cc @<имя пользователя в GitLab>
Здесь работает markdown-синтаксис.
Проверяем что в список Changes попали только коммиты с вашей ветки.
Выбираем того, кому предстоит принимать ваш запрос из выпадающего списка Assignee.
Ставим галку Remove source branch when merge request is accepted.
Жмём Submit merge request. Мерж-реквест создан. О дальнейшей его судьбе вы будете узнавать из уведомлений, которые начнут приходить на электронную почту.

Больше мерж-реквестов

Для набора изменений, затронувшего несколько модулей, если изменения в этом модуле не совсем тривиальны и нуждаются в ревью (см. ниже раздел "Когда направлять мерж-реквест, а когда нет"), создаётся по одному мерж-реквесту на каждый модуль.
Имена веток во всех модулях должны совпадать. Для навигации между ними в описании добавляются перекрёстные ссылки.

Кто принимает мерж-реквест

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

Ревьюверу следует обращать внимание на:

• Соответствие предложенного решения поставленной задаче.
• Соответствие стилю кодирования.
• Наличие тестов и документации.

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

Исправления замечаний делаются в той же ветке и видны в мерж-реквесте.

Когда направлять мерж-реквест, а когда нет

• Коммит связан с багфиксом, патчем, задачей от заказчика, улучшением функциональности, новой доработкой - необходим.
• Коммит не связан ни с чем из перечисленного выше, но затрагивает множество файлов (большой рефакторинг) - необходим.
• Коммит включает изменения в модулях, над которыми работает не только непосредственно коммиттер - необходим.
• В остальных случаях, однофайловый или небольшой рефакторинг, улучшения или добавления тестов, документации, локализации - опционален.