mirror of
https://github.com/1C-Company/v8-code-style.git
synced 2024-12-14 06:07:00 +02:00
52 lines
6.2 KiB
Markdown
52 lines
6.2 KiB
Markdown
# Правила оформления коммитов
|
|
|
|
|
|
Правила необходимы для предотвращения написания бессмысленных заголовков, мешающих пониманию ситуации на проекте. Хорошие оформленные коммиты помогают значительно облегчить процесс выяснения причин внесенных в код изменений, анализируя историю коммитов. Так же это необходимо для стилистического единообразия сообщений коммитов в репозитории.
|
|
|
|
## Тексты сообщений коммитов
|
|
|
|
При написании сообщения коммита следует использовать формат:
|
|
|
|
```
|
|
#<НОМЕР ЗАДАЧИ> Короткое сообщение что сделано
|
|
|
|
Длинное сообщение что сделано
|
|
```
|
|
|
|
1. Начинаем с номера задачи (например, #12311). Идентификатор необходим для интеграции с задачами GitHub
|
|
2. В качестве разделителя между номером задачи и заголовком коммита используем пробел.
|
|
3. Далее идет заголовок коммита:
|
|
- Пишем на русском языке.
|
|
- Заголовок с большой буквы.
|
|
- В конце заголовка точку не ставим.
|
|
- Желательно использовать настоящее время, а не прошедшее (например, "Исправление ошибок запуска при указанной web ИБ").
|
|
- Рекомендуем писать не слишком длинный заголовок, так как его отображение во многих интерфейсах выполнено в одну строку без переносов, так что, он может не влезть. Подробные детали пишем отдельным параграфом в описании коммита.
|
|
4. Описание коммита (опционально).
|
|
- Отделяем от заголовка пустой строкой.
|
|
- Пишем полноценные предложения (начинаем с большой буквы, заканчиваем точкой)
|
|
- Хорошей практикой является ограничение длины строк в сообщении ≈72 символами, с добавлением переносов, если не влезает. Многие UI инструменты для GIT (в том числе EGit) не делают переносы текста описания, если он не влез.
|
|
|
|
### Контент сообщения коммита:
|
|
|
|
В сообщении коммита пишем "что" и "почему" сделано, но избегаем деталей "как" сделано. Назначение комментария - дать коллегам понять, что происходит в проекте.
|
|
|
|
1. Заголовок должен быть ёмкий и информативный.
|
|
2. Заголовок должен быть написан официальным языком, без разговорных оборотов.
|
|
3. Чтобы определить достаточность детализации заголовка коммита, попробуйте ответить на вопрос, не заглядывая в код:
|
|
- `[Bug]` Какая конкретно проблема здесь исправлена?
|
|
- `[Feature]` Какая функциональность здесь добавлена?
|
|
- `[Refactoring]` В каких компонентах/классах произведен рефакторинг?
|
|
- `[Tests]` Что они тестируют?
|
|
- `[Baseline]` В каком компоненте/плагине/пакете подняли версию/версии?
|
|
- `[docs]` В каком компоненте добавлена документация?
|
|
- `[fix]` Какие именно проблемы вы исправили?
|
|
4. Зачем писать сообщение коммита?
|
|
- Когда сделанные изменения неочевидны коллегам, то, помимо комментария в самом коде, не будет лишним описать детальнее, зачем эти изменения были сделаны или, почему сделаны именно так, а не иначе.
|
|
- При исправлении сложных багов можно воспользоваться методологией [Root_cause_analysis](https://en.wikipedia.org/wiki/Root_cause_analysis), и указать причину ошибочного поведения, а так же каким образом это исправили. Человек (или даже вы сами), который через пару лет наткнется на неочевидное изменение, скажет вам спасибо.
|
|
|
|
## Количество коммитов
|
|
|
|
Стоит ли делать один коммит на фичу - зависит от фичи. Коммит - логически завершенное изменение, а сложная фича может содержать много таких изменений, слияние которых в один коммит, приводит к потере информации о деталях ее выполнения. Это касается не только фич.
|
|
|
|
Squash'ить коммиты стоит, если были сделаны лишнее изменения, которые в следующих коммитах отменили. Так же, стоит избегать коммитов вида "Поднятие версий", которые не являются самостоятельными (вызваны другими изменениями, без них билд проекта не будет выполнен).
|
|
|