Как писать сообщения коммитов (сообщение при фиксации кода в систему хранения версий кода), которые удобны для чтения людьми и машинами. В итоге это может дать нам возможность автоматически генерировать Changelog, и автоматически выпускать новые версии при добавлении возможностей.
За основу взято соглашение https://www.conventionalcommits.org/ru/v1.0.0-beta.4/
Для оформления сообщения коммита следует использовать следующий шаблон:
<тип>(<область>): <описание изменения>
<пустая линия>
[необязательное тело]
<пустая линия>
[необязательный нижний колонтитул]
Возможные типы:
- возможность - используется при добавлении новой функциональности уровня приложения (необходимо изменить MINOR версию приложения, см. SemVer)
- исправление - если исправили какую-то серьезную ошибку (bug, необходимо изменить PATCH версию приложения, см. SemVer)
- доки - всё, что касается документации
- стиль - исправляем опечатки, исправляем форматирование кода, переименование переменных/типов/классов/констант, добавили комментарии
- рефакторинг - рефакторинг кода приложения, улучшение кода без изменения функциональности
- тест - всё, что связано с тестированием
- прочее - обычное обслуживание кода, например переместили файл, удалили зависимость в проекте
Можно указывать несколько типов через запятую.
Версия приложения может иметь формат:
Здесь следует написать затронутые части (например, apiserver или руководство оператора)
- Рекомендуем писать сообщения коммитов так, как будто вы уже выпустили продукт. Как правило, кто-то, например, ваши коллеги, уже используют ваш код. И они хотят знать, что исправилось, что изменилось, какие нарушения обратной совместимости появились и т.д.
- Если один коммит содержит несколько изменений, лучше разбить его на несколько, если это возможно.
- Что мне делать, если я случайно использовал не тот тип коммита? Измените сообщение лога (для SVN). Для GIT отредактировать историю
git rebase -i.
Лучше написать грамотно по-русски, чем неграмотно по-английски!
Общий стиль описания:
действие (с маленькой буквы) + для какой сущности + (необязательно подробности)
На русском:
исправление ошибки NoMethodError в RemoteReader'е
Первое слово - отглагольное существительное.
Не писать в сообщении номер задачи из Redmine или Trac - для этого есть тело коммита (см. далее).
исправление(eventlog): исправлено сохранение события в базу данных
документы(все): исправлены опечатки в фамилии исполнителя
стиль(js): выполнено форматирование кода, исправлены опечатки в именах переменных
Заполнение тела коммита опционально. Нужно в том случае, если описание решенной проблемы достаточно сложно и не может уместиться в строку заголовка. Также сюда можно писать номер закрываемого (закрываемых) тасков из Redmine или Trac. Тело сообщения отделяется от заголовка одной пустой строкой и заполняется произвольно.
Тело может содержать указание на наличие изменения, ведущего к обратной несовместимости с предыдущей версией. Это отмечается указанием в начале строки фразы "ВАЖНОЕ ИЗМЕНЕНИЕ:" далее указывается то, что изменилось в API приложения. Наличие важного изменения говорит о необходимости изменить MAJOR версию продукта.
Если вы ссылаетесь на задачу в Redmine или Trac, указываете другую мета информацию, то размещайте ее построчно. Одна еденица иформации - одна строка.
Сообщение без указания области
исправление: устранены незначительные ошибки в коде
Сообщение с указанием области
исправление(eventlog): исправлено сохранение события в базу данных
Сообщение с дополнительной информацией о задаче
исправление(eventlog): исправлено сохранение события в базу данных
закрывает #2014
Обсуждение тут http://####.xx/sss
Сообщение о важном изменении, ломающим обратную совместимость
возможность(прокладчик тракта): изменена структура базы данных для обеспечения создания нескольких связей между сосоедей
ВАЖНОЕ ИЗМЕНЕНИЕ: в структуре базы данных изменилась структура, необходимо выполнить ручное обновление и проверку
данных после
Инструкция по обновлению: обновите базу данных скриптом, затем запуститие скрипт update_links.bat,
в файле отчет проверьте какие связи нужно создать заново вручную