Десять заповедей сообщений о фиксации 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.