В качестве основы используется Angular Git commit Message Convention - это наиболее авторитетный источник. Все остальные вариации конвенций по коммитам ссылаются на эту.
Также достаточно авторитетным источником является conventionalcommits.org
Ниже находится краткая выжимка того, как я понял эти конвенции.
Для оформления сообщения коммита следует использовать следующий шаблон:
<type>(<scope>): <description>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Type, scope и description вместе составляют заголовок коммита (header).
- Type - тип коммита (рефакторинг, исправление багов, новая фича и т.п.)
- Scope - область действия (где были изменения). Это может быть отдельный файл, директория или затронутая часть проекта (rendering, routing и т.д.). Не обязательно для заполнения (но желательно).
- Description - описание сути коммита. Обычно отвечает на вопрос "что было изменено/добавлено/удалено?" Например: add comment section
- Blank line - пустая строка, ей отделяется тело коммита от заголовка, и тело от футера.
- Body - не обязательно для заполнения. Здесь обычно отвечают на вопрос "Зачем были изменения?" и "Почему сделаны именно такие изменения?" (почему не стоит делать по-другому).
- Footer - не обязательно для заполнения. Может содержать информацию о критических изменениях (breaking changes), а также является местом для указания задач из бэклога, GitHub issues, тикетов, и других проблем, которые этот коммит закрывает или с которыми он связан.
//header
chore: drop Node 6 from testing matrix
//body
see the issue for details on the typos fixed
//footer
BREAKING CHANGE: dropping Node 6 which hits end of life in April
closes issue #12
Плохо:
Changed render method in Block
Лучше:
refactor: Changed render method in Block
Хорошо:
refactor(Block.ts): update render method
- Коммиты пишутся на английском языке.
- Заголовок коммита пишется с маленькой буквы.
- Точка в конце не ставится.
- Длина заголовка не должна превышать 100 символов, а лучше 50. Подробности коммита выносятся в тело и футер.
- Description начинается с глагола. Глагол указывается в настоящем времени, например: add, update, improve, remove (не added, updates) и тд.
- Сообщение коммита при merge PR формируется по такому же принципу как описано выше.
- В конец заголовка коммита включается номер PR в скобочках после основного сообщения. Например:
refactor(Block.ts): update render method (#67) - Все сообщения коммитов из сливаемой ветки вносятся в тело коммита.
В итоге получается примерно так:
docs(readme.md): add documentation about project (#3)
* docs(workFlow.md): fix name of developing branch
* chore(package.json): add commitlint to devDependencies
Some extra notes.
Чтобы было проще писать коммиты по всем правилам для VS Code есть плагин "Commit Message Editor". Если использовать его для написания текста коммитов, то ошибиться невозможно.
У плагина две вкладки - edit as text и edit as form. Безошибочный вариант - это edit as form.
- feat - используется при добавлении новой функциональности.
- fix - исправление багов.
- refactor - изменения кода, которые не исправляет баги и не добавляют функционал.
- chore - изменение конфигов, системы сборки, обновление зависимостей и т.д.
- test - всё, что связано с тестированием.
- style - исправление опечаток, изменение форматирования кода (переносы, отступы, точки с запятой и т.п.) без изменения смысла кода.
- docs - изменения только в документации.
Наиболее часто используемый тип - refactor.
Эти типы расширяют вышеописанные, но их использовать не обязательно:
- perf - изменения кода, повышающие производительность.
- build - изменения, влияющие на систему сборки или внешние зависимости (webpack, npm).
- ci - изменения в файлах конфигурации.
BREAKING CHANGE: указывается в футере и автоматически добавляется в конец заголовка. Критические изменения - это изменения, нарушающие обратную совместимость. Может быть частью коммита любого типа.
Должен начинаться с фразы BREAKING CHANGE:, за которой следует краткое изложение критического изменения, пустая строка и подробное описание критического изменения.
Перед тем как пушить коммиты на сервер стоит их проверить:
- Соответствуют ли они всем правилам?
- Будут ли понятны коммиты другим разработчикам?
- Нет ли лишних коммитов, которые не несут смысловой нагрузки для коллег?
Если какие-то проблемы есть, то их желательно исправить.
Непонятным или не совсем корректным коммитам стоит обновить текст сообщения, а лишние коммиты можно обьединить с другими коммитами.
Как исправить проблемы?
Использовать команду git rebase -i. С помощью нее можно расставить коммиты в правильном порядке, объединить их, переименовать, и т.д. Но с этой командой нужно быть осторожным и действовать аккуратно.
Нельзя использовать rebase в публичных (уже запушенных) ветках! Только в локальных ветках разработки, которые еще не были запушены.
Видео-инструкция как работать с командой git rebase -i.