Соглашение о коммитах
Вступление
Привет, меня зовут Сергей Валюшицкий.
Я руковожу продуктовой командой в Цифровых сервисах.
Когда я был разработчиком у меня была дилемма — что писать в сообщениях к коммитам? С одной стороны нет смысла описывать, то что видно в дифе кода;
повторять в каждом сообщении заголовок тикета из Джиры тоже глупо, если коммитов много и каждый решает свою подзадачу;
в граф гита смотрят другие участники и им хорошо бы понимать прямо из дерева о внесенных изменениях.
Хотелось в сообщениях говорить о том, что делают мои изменения в коде для компонента: исправляют дефект и какой, какой добавляют функционал, как влияют на сборку, изменяют ли документацию или улучшают производительность.
Тогда я попробовал Соглашение о коммитах и оно изменило старую реальность отношения к коду и процессам поверх него.
Моя текущая команда второй год работает по Соглашению. Правила работы распространяются на всех, кто взаимодействует с кодовой базой: бекендеров, фронтов, системных инженеров, спецов по качеству, системных аналитиков.
Ниже расскажу какую автоматизацию мы строим поверх него, выгодах использования и подводных камнях.
Соглашение
Соглашение говорит, как писать сообщения к коммитам.
Минимальная структура сообщения такая:
feat!: обязательное поле "цвет глаз" в форме
Восклицательный знак перед двоеточием в примере тоже часть соглашения – это указатель на то, что в коде сломана обратная совместимость.
Типы сообщений
Мы в проекте используем такие типы:
- feat: новая фича;
- fix: исправление дефекта;
- perf: изменение кода, повышающее производительность;
- refactor: переработка кода, чтобы он стал более простым и понятным;
- chore: прочие изменения в коде, обычно ничего такого, что увидел бы внешний пользователь (изменения в .gitignore, вывод данных в консоль, версия релиза в манифесте и тд);
- build: изменения, влияющие на систему сборки или внешние зависимости;
- ci: изменения в файлах конфигурации CI и скриптах;
- docs: изменения документации;
- style: стилевые изменения кода (пробелы, форматирование, прочий линтинг);
- test: добавление отсутствующих тестов или исправление существующих тестов.
Ошибок с выбором типа не избежать. Но рука набивается быстро.
Автоматизация
Поверх типизированнового графа коммитов можно придумать ряд автоматизаций.
И первое, что напрашивается – версионирование компонет системы.
Версионирование
В мире материальных объектов все просто и чаще всего подойдет инкрементальное версионирование (АйФон 12, 13, 14 ... 42).
В подсистемах и сервисах, работающих в интеграционной среде, зачастую используют семантическое версионирование (СемВер), чтобы показать класс вносимых изменений.
Структура Cемвера такая:
vМАЖОР. МИНОР. ПАТЧ
Мы автоматизировали выпуск версий по СемВер на основе сообщений к коммитам, выпущенных по Cоглашению.
Код попадает в главную ветку — выпускаем версию (тег и запись в файл манифеста проекта).
Задачу выпуска у нас решает standard-version. Но умолчанию библиотека работает с package.json, но есть возможность написать апдейтер для других манифестов. У нас написан для pom.xml.
Чтобы убрать опечатки в типах при печати сообщения мы используем commitlint. Библиотека на хуке commit-msg валидирует сообщение и, в случае неконвенциональности, отменяет коммит.
Ченджлог и уведомления
Формируем ченджлог между двумя последними версиями компонента, сохраняем его в артефакты.
Далее уведомляем участников процесса об обновах в релизе.
Инструменты для формирования лога в ассортименте. Наш выбор git-cliff. Подсмотрел его когда-то у ведущих подкаста Радио-Т.
Выгода
Соглашение о коммитах однозначно добавит в ваши репозитории порядка, если раньше там царила анархия.
Разработчики научатся декомпозировать код на основе типов изменений; получат возможность задуматься о классе изменений, что особенно критично при мажорных правках.
Релизные процессы можно автоматизировать (выпуск версий, формирование лога изменений).
Граф коммитов станет более понятным для участников процесса.
Заключение
Наличие в проекте Соглашения о коммитах — хороший задел.
Скорее всего вы приведете свое приватное или публичное API к порядку по средствам СемВера и автоматизаций рутинных процессов.
Но не стоит идеализировать процесс – незарегистрированых мажорных версий не избежать и с применением Соглашения. Но на подходе хороший тулинг на основе языковых моделей. Но это уже другая история.