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 исправляет ошибку в обработчике на оформление заказаПосле номера задачи не используются никакие знаки препинания, все буквы являются строчными
Данный пункт регламента касается только заголовков коммита. Тело коммита можно писать в свободной форме. Там необязательно придерживаться того-же склонения, что и в заголовке коммита (добавляет, изменяет, удаляет...), можно использовать любые знаки препинания, любой регистр букв:
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 в новый шаблон squared5500 изменяет разметку и стили шаблона squared у bitrix:catalog.section
Не забывайте переодически отправлять свои коммиты в центральный репозиторийgit push origin feature/xxxx. Иногда может потребоваться продолжить работу из другого места, например из дома. Если уже зафиксированные изменения будут в центральном репозитории, их можно будет получить себе на другом устройстве и продолжить работу.
Last updated
