Коммиты

Жизнь любого проекта сопровождается большим количеством изменений. Новые решения и исправления по крупицам составляют одну большую историю, которая может растягиваться годами. В такой каше становится трудно понять, откуда у того или иного изменения растут ноги.

Контроль версий

Контроль версий - это практика в разработке программного обеспечения позволяющая управлять, организовывать и отслеживать различные версии компьютерных файлов.

И хотя систем контроля версий существует большое множество, первое место по популярности таких систем уже довольно продолжительное время удерживает Git, созданный Линусом Торвальдом специально для работы с GNU/Linux в 2005 году, практически вытеснив на тот момент SVN (Apache Subversion).

Git

Главная особенность Git заключается в “снимках” состояния (snapshot) для создания которых используется подкоманда commit (англ. совершать, фиксировать). Для упрощения работы, определения для снимка и процесса его фиксации слились в одно целое: коммит.

Коммит - это часто небольшое разделенное друг от друга изменение в файлах проекта. Для идентификации коммитов используется хеш-сумма, которая используется при работе с VCS, однако для человека такой способ идентификации слишком трудный.

Более понятной уникальной чертой коммита является сообщение (git commit -m), которое по сути представляет собой текст, написанный автором для описания внесенного им изменения. Помимо этого, сообщения коммитов применяются также и для создания списка изменений (changelog). Поэтому важно писать такие сообщения эффективно.

Пишем сообщения коммитов эффективно

В программировании не существует чётких правил для комметариев. Это также касается сообщений для коммитов, однако некоторые компании создают свои практики и конвенции для формирования единообразной и эффективной структуры описаний. Впоследствии она начинает применяться и за пределами одной компании, становясь общественным достоянием.

Одним из таких руководств является "Commit Message Guidelines" (руководство по сообщениям коммитов) для фреймворка Angular. Данное руководство описывает не только сам формат текста сообщения, но также в нём выделены особо часто встречаемые типы изменений и приведены общие рекомендации для их написания.

Руководство по сообщениям коммитов

Использование данных правил поможет сделать сообщения более читаемые и легко отслеживать при просмотре истории проекта.

Форматирование

Каждое сообщение коммита имеет собственные поля: заголовок (header), тело (body) и футер (footer), разделенные между собой пустыми строками. В свою очередь, заголовок разделен на несколько частей: тип (type), область (scope) и тема (subject).

Общий формат сообщения выглядит следующим образом:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

За исключением области (scope) остальные части заголовка в сообщении коммита являются обязательными.

Каждая отдельная строка в сообщении должна быть ограничена 100 символами, это позволяет легко про читать его при помощи любого инструмента, будь то сервис или программа.

Подвал может содержать ссылку на нерешенную проблему на баг-трекере проекта.

Примеры правильных сообщений коммитов можно посмотреть в истории коммитов в git-репозитории Angular.

Отмена

Для отмены предыдущего коммита используется тот же заголовок сообщения что и у предыдущего с добавлением в начало revert:. В теле сообщения может указываться хеш-число последнего отмененного коммита, например: This reverts commit <hash>.

Типы

Для быстрого определения характера коммита его тип выделяется в начале заголовка, всего их 9:

build: Изменения, которые влияют на систему сборки или внешних зависимостей.
ci: Изменения в конфигурационных файлах и скриптах для CI.
docs: Документационные изменения.
feat: Добавление новых функций.
fix: Исправления ошибок.
perf: Изменения, касающийся улучшения производительности.
refactor: Изменения, которые не добавляют новых или исправляют какие-либо функции.
style: Изменения, не касающиеся самого текста программы (форматирование, отсупы).
test: Добавление новых тестов или исправление сущетствующих.

Области

Области используются для проектов с большим количеством собственных зависимостей и отражает название внутреннего пакета (например, в npm).

Отсутствие области в сообщение означает что изменения были выполнены на все доступные пакеты проекта.

Тема

В теме содержится краткое описание изменения.

Помимо этого для темы установлены следующие правила:

текст пишется в повелительном наклонении настоящего времени (“change”, а не “changes” или “changed”).
текст начинается со строчной буквы.
текст закачивается без точки на конце.

Тело

Тело также должно писаться в повелительном наклонении настоящего времени и содержать мотивацию для изменения и контрастировать на фоне предыдущего поведения программы.

Подвал

Подвал должен содержать любую информацию о ломающих изменениях (Breaking Changes), то есть тех, которые меняют совместимость с предыдущими версиями. Помимо этого, подвал может содержать ссылку на ошибку в баг-трекере, которую данный коммит должен закрыть.

Ломающие изменения должны начинаться со слов BREAKING CHANGE: и разделяться пробелом или пустой строкой.