3. Оформление коммитов

Обзор правил

3.1. В начале коммита указывается номер задачи, над которой идет работа

3.2. Заголовок коммита должен отвечать на вопрос "Что делает этот коммит и где?"

3.3. Если коммит вносит много изменений, то их лучше перечислить в теле сообщения коммита

3.4. В заголовке коммита используются только строчные буквы. После номера задачи не указываются тире, двоеточия, и другие пунктуационные знаки

3.5. Если коммит делается без поставленной задачи (например hotfix), то номер задачи не указывается, а сразу же пишется заголовок

3.6. Сообщение коммита не должно содержать жаргонной и ненормативной лексики (кроме технических жаргонов)

3.7. Bitrix. Если для работы необходимо скопировать шаблон компонента или сам компонент, то прежде чем вносить в копию изменения — необходимо оформить коммит

Введение

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

  • 1201: Исправил ошибку кэширования

  • правки стилей

  • 1240: Настроил порядок отображения товаров | Исправил баг с подключением стилей | шаблон для компонента

  • 1256 новый шаблон для компонента

  • Пофиксил баги

Похоже ли это на командную работу? Да, похоже, даже очень. Сразу заметно, что над проектом работало несколько людей. Но можно ли их назвать командой? Здесь нет никакой договоренности относительно того, как писать сообщения коммитов, каждый пишет в своём стиле. Кто-то указывает номер задачи а кто-то нет, кто-то пишет с большой буквы а кто-то нет, кто-то ставит символ двоеточия а кто-то нет. Командной работой это назвать сложно.

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

3.1. В начале коммита указывается номер задачи, над которой идет работа

Работа над каждой задачей ведется в отдельной ветке, которая и так уже содержит номер задачи. Зачем же его еще дублировать в сообщение коммита?

Иногда возникают ситуации, когда нужно найти все коммиты, которые были сделаны при решении той или иной задачи. Сделать это можно, если найти в центральном репозитории feature ветку, в которой выполнялась задача, по её номеру. Но есть одна проблема - feature ветки могут быть оттуда удалены. Например, при слиянии с master веткой (если установлена галочка "Delete source branch when merge request is accepted"), ветка также может быть удалена самим разработчиком, или же администратором репозитория. В такой ситуации найти нужные коммиты становится затруднительно.

Или другая ситуация. Как определить номер задачи по конкретному коммиту, если feature ветки уже нет?

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

3.2. Заголовок коммита должен отвечать на вопрос "Что делает этот коммит и где?"

Именно на вопрос "что делает коммит", а "не какие изменения я сделал" или "что было изменено".

Плохие примеры:

  • 5500 исправлен баг Какой баг? Где был баг? Не то склонение, вместо "исправлен" нужно "исправляет"

  • 5511 правки Правки чего? Скриптов? Стилей? Ошибок?

  • 5511 еще правки Понятно что правки, но какие?

  • 5511 правки 3 Такие коммиты никак не отражают историю разработки, указание версии правок тоже никак не помогает

  • 5522 поработал над компонентом Над каким компонентом? Какая именно работа была проведена?

  • 5533 исправление ссылок для catalog.item галереи в детальной карточке бренда Все указано верно, и что сделано (исправление ссылок) и где (в детальной карточке бренда), но не в том склонении. Нужно - исправляет ссылки для catalog.item в детальной карточке бренда

Хорошие примеры:

  • 5500 изменяет время кэширования компонентов на странице новостей Что делает этот коммит? Он изменяет время кэширования у компонентов. Где находятся эти компоненты? На странице новостей. А у каких именно компонентов изменялось время кэширования и на какое можно уже уточнить взглянув на код коммита.

  • 5511 исправляет ошибку сортировки товаров в каталоге Из этого сообщения сразу понятно, что в каталоге была ошибка с сортировкой товаров, и этот коммит исправляет данную ошибку

  • 5522 добавляет логирование ошибок в компоненте stmd:order.ajax

3.3. Если коммит вносит много изменений, то их лучше перечислить в теле сообщения коммита

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

  • Удалены уже ненужные, закомментированные участки кода

  • Код, который получает данные (программа), и код который их отображает (разметка) разнесены по отдельным файлам

  • Проведен рефакторинг и улучшение старого, очень древнего кода, чтобы с ним хоть как-то можно было работать

Было бы очень здорово, если бы каждое такое изменение было в своём отдельном коммите, чтобы глядя на историю коммитов можно было восстановить очередность действий. Но в реальности бывает очень много маленьких (или не очень) правок, связанных между собой, которые трудно отделить друг от друга. Или же просто разработчик забывает оформить отдельный коммит.

Когда один коммит вносит слишком много исправлений, и все изменения описываются в одной строке, то в общей истории он выглядит примерно так:

Часть сообщения, что было сделано видно, а часть скрыта, и отображается только при нажатии кнопки ... и точно так же, в одну строку

А ведь сообщение коммита может быть и многострочным, например:

Это заголовок коммита, он будет показан в общем логе

Через одну пустую стоку идет уже тело коммита.
- Здесь можно по пунктам
- перечислить всё, что было сделано
- в удобном для чтения формате

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

Поэтому, если один коммит вносит сразу несколько изменений, то лучше в заголовке коммита указать какое-то общее сообщение о том, какие изменения он вносит, а подробности расписать уже в теле коммита

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

3.4. В заголовке коммита используются только строчные буквы. После номера задачи не указываются тире, двоеточия, и другие пунктуационные знаки

Для того, чтобы все заголовки коммитов от разных разработчиков были оформлены в едином стиле, то следует писать их только строчными буквами. После номера задачи не стоит ставить знаки препинания, такие как двоеточие или тире.

Плохие примеры:

  • 5500: Изменяет отображение тарифов на странице с ценами Использовано двоеточие после номера задачи, Первая буква написана заглавной

  • 5511 - добавляет форматирование статей для блога Использовано тире после номера задачи

Хорошие примеры:

  • 5522 исправляет ошибку в обработчике на оформление заказа После номера задачи не используются никакие знаки препинания, все буквы являются строчными

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

5533 вносит изменения в страницу брендов

- Создан новый файл index.php в котором подключается компонент catalog
- Создан шаблон каталога для страницы брендов stmd_brands
- Реализовано добавление линеек брендов в массив родителя под ключом CHILDREN

3.5. Если коммит делается без поставленной задачи (например hotfix), то номер задачи не указывается, а сразу же пишется заголовок

Допустим, разработчик обнаружил свой-же баг и решил его поправить. Для этого разработчик создает hotfix ветку, и фиксирует в ней нужные правки коммитами. Так как отдельной задачи на исправление бага не ставилось, то и номер задачи в начале заголовка коммита указывать не нужно:

исправляет ошибку с кэшированием в компоненте stmd:gallery.video

3.6 Сообщение коммита не должно содержать жаргонной и ненормативной лексики (кроме технических жаргонов)

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

3.7 Bitrix. Если для работы необходимо скопировать шаблон компонента или сам компонент, то прежде чем вносить в копию изменения — необходимо оформить коммит

Допустим, разработчику поставлена задача: создать новый шаблон для компонента bitrix:catalog.section, который должен выводить список товаров.

Чтобы выполнить эту задачу, разработчик копирует старый шаблон со всеми файлами в другую папку, исправляет разметку, стили, код, и фиксирует все это в один единственный коммит — 5500 добавляет новый шаблон для компонента bitrix:catalog.section.

Внимание - вопрос: как проверяющему на code review определить, какие места в коде были затронуты разработчиком, какие файлы новые, а какие просто скопированы с другого шаблона? Проверяющий будет видеть все файлы как новые, как-будто они были созданы и написаны самим разработчиком. Или же если разработчику попадется похожая задача и он решит подглядеть, что он правил в прошлый раз, он не сможет увидеть точные строки.

Если сразу скопировать файлы, отредактировать из и закоммитить, а на Code Review обнаружится ошибка или недоработки, они будут отправлены разработчику на корректировки, даже не смотря на то, что эти участки кода были скопированы с другого шаблона, и разработчик их не правил.

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

  • 5500 копирует шаблон .default у bitrix:catalog.section в новый шаблон squared

  • 5500 изменяет разметку и стили шаблона squared у bitrix:catalog.section

Не забывайте переодически отправлять свои коммиты в центральный репозиторийgit push origin feature/xxxx. Иногда может потребоваться продолжить работу из другого места, например из дома. Если уже зафиксированные изменения будут в центральном репозитории, их можно будет получить себе на другом устройстве и продолжить работу.

Previous2. Работа с веткамиNext4. Merge Requests

Last updated