Общепринятые коммиты

Обновлено 2023-07-19 3 мин. для прочтения Computer-Science

Использование спецификации Conventional Commits.

Содержание

1 Описание

Соглашение о том, как нужно писать сообщения commit’ов.
Совместимо с SemVer (см. Семантическое версионирование). Даже вернее сказать, сильно связано с семантическим версионированием.
Регламентирует структуру и основные типы коммитов.

1.1 Структура коммита

1<type>(<scope>): <subject>
2<BLANK LINE>
3<body>
4<BLANK LINE>
5<footer>

Или, по-русски:

1<тип>(<область>): <описание изменения>
2<пустая линия>
3[необязательное тело]
4<пустая линия>
5[необязательный нижний колонтитул]

Заголовок является обязательным.
Любая строка сообщения о фиксации не может быть длиннее 100 символов.
Тема (subject) содержит краткое описание изменения.
- Используйте повелительное наклонение в настоящем времени: «изменить» (“change” not “changed” nor “changes”).
- Не используйте заглавную первую букву.
- Не ставьте точку в конце.
Тело (body) должно включать мотивацию к изменению и противопоставлять это предыдущему поведению.
- Как и в теме, используйте повелительное наклонение в настоящем времени.
Нижний колонтитул (footer) должен содержать любую информацию о критических изменениях.
- Следует использовать для указания внешних ссылок, контекста коммита или другой мета информации.
- Также содержит ссылку на issue (например, на github), который закрывает эта фиксация.
- Критические изменения должны начинаться со слова BREAKING CHANGE: с пробела или двух символов новой строки. Затем для этого используется остальная часть сообщения фиксации.

1.2 Типы коммитов

1.2.1 Базовые типы коммитов

fix: — коммит типа fix исправляет ошибку (bug) в вашем коде (он соответствует PATCH в SemVer).
feat: — коммит типа feat добавляет новую функцию (feature) в ваш код (он соответствует MINOR в SemVer).
BREAKING CHANGE: — коммит, который содержит текст BREAKING CHANGE: в начале своего не обязательного тела сообщения (body) или в подвале (footer), добавляет изменения, нарушающие обратную совместимость вашего API (он соответствует MAJOR в SemVer). BREAKING CHANGE может быть частью коммита любого типа.
revert: — если фиксация отменяет предыдущую фиксацию. Начинается с revert:, за которым следует заголовок отменённой фиксации. В теле должно быть написано: Это отменяет фиксацию <hash> (это SHA-хэш отменяемой фиксации).
Другое: коммиты с типами, которые отличаются от fix: и feat:, также разрешены. Например, @commitlint/config-conventional (основанный на The Angular convention) рекомендует: chore:, docs:, style:, refactor:, perf:, test:, и другие.

1.2.2 Соглашения The Angular convention

Одно из популярных соглашений о поддержке исходных кодов — конвенция Angular (The Angular convention).

Типы коммитов The Angular convention
Конвенция Angular (The Angular convention) требует следующие типы коммитов:
- build: — изменения, влияющие на систему сборки или внешние зависимости (примеры областей (scope): gulp, broccoli, npm).
- ci: — изменения в файлах конфигурации и скриптах CI (примеры областей: Travis, Circle, BrowserStack, SauceLabs).
- docs: — изменения только в документации.
- feat: — новая функция.
- fix: — исправление ошибок.
- perf: — изменение кода, улучшающее производительность.
- refactor: — Изменение кода, которое не исправляет ошибку и не добавляет функции (рефакторинг кода).
- style: — изменения, не влияющие на смысл кода (пробелы, форматирование, отсутствие точек с запятой и т. д.).
- test: — добавление недостающих тестов или исправление существующих тестов.

Области действия (scope)
Областью действия должно быть имя затронутого пакета npm (как его воспринимает человек, читающий журнал изменений, созданный из сообщений фиксации).
Есть несколько исключений из правила «использовать имя пакета»:
- packaging — используется для изменений, которые изменяют структуру пакета, например, изменения общедоступного пути.
- changelog — используется для обновления примечаний к выпуску в CHANGELOG.md.
- отсутствует область действия — полезно для изменений стиля, тестирования и рефакторинга, которые выполняются во всех пакетах (например, style: добавить отсутствующие точки с запятой).

1.2.3 Соглашения @commitlint/config-conventional

Соглашение @commitlint/config-conventional входит в пакет Conventional Changelog. В целом в этом соглашении придерживаются соглашения Angular.

2 Программное обеспечение

Links to this note

Education Programming