Десять заповедей сообщений о фиксации Git - это попытка унифицировать Обычные коммиты 1.0.0, 7 правил сообщений о фиксации и формат, используемый самим git, GitHub и GitLab.

Заповеди были упомянуты в «проповеди на /mnt» следующим образом:

0. Сообщение git commit не должно быть пустым
1. Отделите заголовок от тела и тело от нижнего колонтитула пустой строкой
2. Ограничьте заголовок 72 символами
3. Не следует используйте любой падеж, кроме падежа предложения для подлежащего
4. Не ставьте в конце предмета точку
5. Не используйте в подлежащем только повелительное наклонение
6. Оберните тело и нижний колонтитул - 72 символа
7. Используйте текст, чтобы объяснить, что и почему, а не как
8. Используйте типы для семантического управления версиями
9. Используйте нижний колонтитул для подключения к проблемам и обозначения критических изменений

Введение

Первый раздел, § 1. Commitlint - это настройка линтера фиксации, который проверяет сообщения фиксации в соответствии с заповедями. Второй раздел, § 2. Заповеди, это объяснение Заповедей и причины каждой из них.

§1. Commitlint

Используя Node.js, можно обеспечить соблюдение Заповедей с помощью commitlint и commitlint-config-commandments:

npm i -D commitlint-config-commandments @commitlint/cli
echo "module.exports = {extends: ['commandments']};" \
  > commitlint.config.js

Пока что в этой предустановленной конфигурации применяются только заповеди 1, 2, 3, 4 и 6. После инициализации линтера линтинг может быть выполнен через конвейер через командную строку:

echo "Feat: Add dry run functionality" | commitlint

Git Hook

Чтобы на лету вставлять каждое сообщение коммита, можно использовать husky для настройки ловушки git:

npm i -D husky

Добавьте в свой package.json следующие строки:

"husky": {
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

Трэвис Си

npm install --save-dev @commitlint/travis-cli

А потом в travis.yml:

language: node_js
node_js:
  - node
script:
  - commitlint-travis

GitLab-CI

Создайте следующий сценарий BASH и назовите его commitlint.sh или что-то в этом роде:

if [ $CI_BUILD_BEFORE_SHA == "0000000000000000000000000000000000000000" ]; then
  npx commitlint --from=HEAD~1
else
  npx commitlint --from=$CI_BUILD_BEFORE_SHA;
fi;

Затем запустите его в .gitlab-ci.yml:

test:commitlint:
  image: node:${NODE_VERSION}
  script:
    - bash commitlint.sh

§2. Заповеди

Сообщение фиксации имеет следующий формат:

<header>
[body]
[footer]

Обозначение <x> обозначает обязательные заполнители, где [x] означает, что заполнитель содержит место для необязательной части.

Обычные коммиты v1.0.0 делит заголовок на части, получая следующий формат:

[type]([scope]): <subject>
[body]
[footer]

Тип является обязательным в Conventional Commits v1.0.0, но мы хотели бы оставить его необязательным. Кроме того, круглые скобки области видимости исчезают в случае отсутствия области действия.

Заповедь 0

Сообщение git commit не должно быть пустым

Это фундаментальное правило необходимо для дальнейшего. Хотя возможно иметь пустое сообщение фиксации или, по крайней мере, почти пустое сообщение (например, . в качестве сообщения), этого следует избегать, поскольку это ничего не объясняет о фиксации.

Заповедь 1

Отделите заголовок от тела и текст от нижнего колонтитула пустой строкой.

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

Пустая строка, отделяющая заголовок от тела, хотя и не требуется механически, улучшает читаемость.

Заповедь 2

Ограничьте заголовок до 72 символов

Точное число 72 имеет историческую причину. В свое время программисты использовали перфокарты для ввода своих программ в машины. Перфокарты имели 80 столбцов, 8 из которых были зарезервированы, что делало строки длиной 72 символа.

Когда у программистов были мониторы, на экранах было 72 столбца, а максимальная длина строки составляла 72 символа. Это стандартный приклад для многих вещей с тех пор. В нашем случае GitHub обрезает заголовки длиной более 72 символов.

Заповедь 3.

Не используйте падеж, кроме падежа предложения для подлежащего

«Падеж приговора» означает, что вы начинаете с заглавной буквы. Основная причина этого правила - согласованность с автоматически сгенерированными сообщениями фиксации git.

Например, следующее:

Revert "Feat: Add list transformations" 
     
This reverts commit 1a18b1cef017f457f6e3d39a7bc7b177dc1b24a4.

Это сообщение о фиксации создается при отмене фиксации. Как видите, здесь нет типа или области действия, а субъект - это регистр предложений.

Заповедь 4

Не заканчивай тему точкой

Опять же, для последовательности. Если посмотреть на сгенерированное сообщение возврата из заповеди 3, в заголовке нет точки, а в теле есть.

Заповедь 5.

Не употребляй, кроме повелительного настроения в теме

Опять же, для последовательности. Еще раз заглянув в сгенерированное сообщение возврата из заповеди 3, у субъекта есть повелительное настроение.

Заповедь 6.

Оберните основной и нижний колонтитулы на 72 символа

Git не оборачивает тело сообщения фиксации. Итак, мы должны обернуть его некоторой длиной. Почему не старые добрые 72? Тем более, что это выравнивает тело с заголовком.

Заповедь 7.

Используйте тело, чтобы объяснить, что и почему и как

Фиксация содержит внесенные вами изменения. Так что упоминать, что было изменено, излишне. То, что обычно озадачивает людей, оглядываясь на коммиты, - это их причина. Примером может быть следующее:

Remove the HTTPS server
Removed the HTTPS server from main.ts, as well as the certs folder.

Читая это тело, я бы сказал: «Так какого черта ты это сделал»? Я бы ожидал вот этого:

Remove the HTTPS server
As we now use NGINX in front of the Node.js server, we won't need
to provide HTTPS by Node.js itself; NGINX does it both for dynamic
and static serves.

Заповедь 8.

Используйте типы для семантического управления версиями

Самая важная цель типов сообщений фиксации - семантическое управление версиями. Вот как это происходит:

  • Если у вас тип Fix, то в последней части версия упирается: 1.2.3 → 1.2.4.
  • Если у вас тип Feat, то версия выпирает в средней части: 1.2.3 → 1.3.0.
  • Если у вас BREAKING CHANGE в нижнем колонтитуле, то версия поднимается в первой части: 1.2.3 → 2.0.0.

Это даже можно автоматизировать с помощью подходящих инструментов.

Заповедь 9.

Используйте нижний колонтитул, чтобы сообщать о проблемах и отмечать критические изменения

Сервисы хостинга кода, такие как GitHub и GitLab, теперь достаточно умны, чтобы запускать действия на основе сообщений фиксации. Нижний колонтитул - правильное место для использования этих возможностей:

Add Docker image build process
Fixes #666

Теперь с этой строкой в ​​нижнем колонтитуле:

  • GitHub / GitLab связывает фиксацию с проблемой. Фиксация появится в выпуске.
  • GitHub / GitLab автоматически закрывают проблему после принятия запроса на вытягивание / слияние.
  • Будущие разработчики знают, почему произошла фиксация, и могут изучить проблему, чтобы узнать больше.

Вывод

Десять заповедей основаны на многих существующих стандартах и ​​опыте. Эта статья, так же как и линтер, молоды и могут подвергнуться дополнительным проверкам и исправлениям. Чтобы получать уведомления об обновлениях, подпишитесь на меня в Twitter.