¶ Именование коммитов (commit naming) в Git
Git не имеет никаких изначальных ограничений на имена коммитов. Ограничения часто вводятся самими разработчиками для улучшения понимания проделанной работы другими разработчиками.
¶ Коммиты
Рассмотрим на примере (для получения истории коммитов использовалась команда git log --pretty=format:"%h : %s"):
7aadcea : server changes
cdac316 : new config
f8fcb22 : minor fixes
f54c6ba : start arguments changed
a8e10b4 : new version
144466b : Merge remote-tracking branch 'origin/master'
b1e8079 : some fixes
8a3cdeb : update utils.py
15f3d26 : new mag ou added
b6b568d : op wrong values fixed
Данный набор коммитов является читабельным, а с учетом контекста проекта он также становится и понятным. Однако стоит учесть, что они все разношерстны. Также не конкретизированы решаемые задачи, например, new config и new mag ou added могут иметь схожий смысл: изменения конфигурации программы; второй коммит в свою очередь может описывать и функциональное изменение программы.
Отсюда и выходят проблемы, другим разработчикам требуется исследовать уже сами изменения.
Стоит отметить, что данные коммиты лучше чем:
851a20d3 : Upload New File
29aa2577 : Upload New File
7a4b10c0 : Upload New File
edffb2a1 : Upload New File
306504c6 : Upload New File
0ca2ea3a : Upload New File
46981327 : Upload New File
bc717702 : Upload New File
85f7db8c : Upload New File
ad366e26 : Upload New File
или
92a82550 : Update solution.txt
e966c959 : podbiraem bally from polka
d7c087da : second try
8529f0ff : pop it ka 1
¶ Подходы к именованию
У коммитов практически нет ограничений в Git, потому можно писать практически любой комментарий. Для удобства часто выделяются следующие форматы: [<type>] <description>, <type>: <description> или <type> / <description>. От обычных коммитов их отличает то, что в них указан тип изменения в том или ином формате. Рассмотрим на примере:
7f0a261 : version: new version 0.15.1
360c7ba : feature: file taking priority changed
0b952a3 : fix: input auto variable taking fixed (v1)
5be1e0e : fix: escaping fixed
ff994fe : fix: minor fixes
b7ef6cb : version: new version 0.15.0
df83470 : feature: new image generators
12105d7 : feature: code restructure
7621aa7 : feature: node description changed
Здесь уже можно отметить, что тип изменения кратко отражает смысл коммита, например, version говорит о некой ключевой точке, которую прошел проект, а, например, fix и feature исправления и новый функционал соответственно.
Использование типов накладывает ограничения на смысловую нагрузку описания, а также нагрузку изменений. Исправления не должны содержать новый функционал, аналогично работа с документацией и т.п. Если в вашем проекте возникла такая проблема, то стоит разделить изменения на разные коммиты. Коммитом больше, коммитом меньше. Однако если требуется найти информацию об изменении, а она наложилась на другую, то проблемы не избежать.
Для формирования имени коммита, а также его тела рекомендуется использовать одну конвенцию для проекта, следовательно, все участники проекта также должны придерживаться этой конвенции.
¶ Conventional Commits
Одним из подходов к созданию коммита является Conventional Commits. Для описания коммита используется следующая структура:
<type>[(<scope>)][!]: <description>
[<BLANK LINE>
<body>]
[<BLANK LINE>
<footer>]
Первой строчкой является короткое имя или название коммита. Само название делится на тип, область действия коммита и описание, например, feat(web): add new icon. Область действия является опциональной, так как это лишь уточнение, которое может в дальнейшем быть использовано в поиске. Добавление восклицательного знака означает, что данный коммит создает сильные изменения кода, которые могут быть приравнены к новой версии или могут вовсе сломать работу продукта. Пустые линии между телом коммита и футером обязательны, в случае добавления последних.
Далее идет тело коммита. Напоминаю, что коммиты могут быть многострочными и по идее должны. При использовании команды git commit вызывается редактор по умолчанию с файлом коммита, после закрытия файла коммит считается завершенном. Если открылся неудобный редактор, то можно изменить редактор коммитов Git командой git config --global core.editor "<редактор>". Существует частая практика писать git commit -m <commit description>, в таком случае описывается однострочный коммит, а значит тело коммита уже не будет возможно описать.
Тело коммита нужно для полноценного описания выполненной задачи. Если вспомнить пример сверху, то добавление иконки не дает конкретики.
feat(web): add new icon
Add new icon to button `Login` on the main page of website.
В конце можно добавить футер с метаданными, например, с задачей которую закрыли этим коммитом, автором изменений или другой полезной информацией.
feat(web): add new icon
Add new icon to button `Login` on the main page of website.
Refs: #29
Стоит отметить GitLab или GitHub отображают тело и футер коммита в своем интерфейсе, однако они не анализируют текст, потому единственный способ добавить интерактивности - использовать ссылки.
¶ Типы, области действия и написание текста
Начнем с написания текста коммита. Описание, как и тип и область должны быть в нижнем регистре, за исключением слов по правилам грамматики и исторически сложившихся названий, например, страны, названия технологий, имена и т.п.
feat(lang): add Russian language support
fix: change time format from American to Europe
Тело коммита должно быть описано в формате предложений с точкой в конце. Предложений может быть несколько, ограничений нет.
Футер должен отображать краткую информацию, схожую с окончаниями предоставленными инструментом Git. Например:
Fixes: Z
Cc: Z
Reviewed-by: Z
Signed-off-by: Z
¶ Типы коммитов
Conventional Commits и аналогичные конвенции предлагает следующие типы коммитов:
| Тип | Расшифровка | Описание |
|---|---|---|
| build | Build (Сборка) | Изменения, влияющие на систему сборки или внешние зависимости |
| chore | Chores (Рутинные обязанности) | Изменения, которые не изменяют код, документацию и другие значащие функции |
| ci | Continuous Integrations (CI/CD) | Изменения в конфигурационных файлах и скриптах CI/CD |
| docs | Documentation (Документация) | Изменения документации (и только документации) |
| feat | Features (Новая функция) | Изменения, создавщие новые функции в продукте |
| fix | Bug Fixes (Исправления ошибок) | Изменения, исправляющие ошибки и недочеты продукта |
| perf | Performance Improvements (Улучшение производительности) | Изменения кода, улучшающие производительность |
| refactor | Code Refactoring (Рефакторинг кода) | Изменения кода, которые не исправляют ошибку и не добавляют функцию |
| revert | Reverts (Возврат) | Отмена предыдущего коммита |
| style | Styles (Стиль кода) | Изменения, не влияющие на смысл кода (пробелы, форматирование, пропущенные точки с запятой и т.д.) |
| test | Tests (Тесты) | Изменения, добавляющие тесты или исправляющие их |
¶ Типы областей действия
Данная часть ограничивается лишь воображением разработчика. Рекомендуется исследовать сокращения английских слов, а также сокращения областей разработки и технологий используемых в них. Примером сокращений может послужить следующий сайт Shortened Words.
¶ Использование в проекте
В проекте требуется использовать описанную на данной странице конвенцию (Conventional Commits). Пример использования можно увидеть в одном из репозиториев проекта.