Использование git для 1с.
В своей работе я часто использую git для контроля версий продукта. Очень много времени и статей уделяется различным практикам работы с git: как именовать ветки, какое ветвление использовать, merge или rebase… Но мало внимания уделяют сообщениям коммитов. А ведь это основа – история разработки. Отсутствие соглашений о сообщениях затрудняет совместную работу.
Эволюция сообщений коммита.
Сначала коммиты у нас были вот такими:
Как видно, понять, что было сделано, зачем, на что это может повлиять – практически невозможно. Разбор полетов занимает много времени.
Потом чуть-чуть подумали, договорились. Стало лучше.
Более подробное описание и ссылка на задачу.
Но на просторах github встречались такие коммиты
И описания для контрибьютеров.
Такие правила называются «Conventional Commits».
Conventional Commits
Подробно описано вот здесь https://www.conventionalcommits.org/ru/v1.0.0-beta.2/
Коротко: каждое сообщение коммита должно содержать:
- указание на тип доработки;
- опциально указать изменяемую область;
- краткое описание коммита;
- опциально подробное описание;
- опциально номер решаемой задачи.
По такой истории сообщений можно автоматически генерировать CHANGELOG, для этого есть много библиотек. В том числе на OScript https://github.com/oscript-library/changelog-generate
Проблемы
Идея отличная. Проблема только в следовании схеме. Конечно, какие блоки использовать и как писать указано в документации к репозиторию. Но иногда забывается что именно писать. В одно проекте договорились писать feat, в другом feature; в каждом проекте свои блоки. Поэтому решили поискать пути автоматизации.
Commitizen
Нашелся классный пакет для node-js - commitizen. Он использует дополнительный пакет cz- customizable для вызова удобной формы ввода сообщения. А настройки соглашений хранит прямо в репозитории.
Установка и настройка
На компьютере должен быть установлен Node-js и npm. Через npm устанавливаем два пакета
npm install -g commitizen
npm install -g cz- customizable
Теперь надо сделать пару простых настроек.
Настроить package.
В корне репозитория добавляем файл package.json со следующим содержимым
{
"config": {
"commitizen": {
"path": "cz-customizable"
},
"cz-customizable": {
"config": "tools/js/commitizen.js"
}
},
"devDependencies": {
"cz-customizable": "^5.3.0"
}
}
В папке tools создаем файл commitizen.js, в котором описываем настройки договоренностей. Например, так:
"use strict";
module.exports = {
// Добавим описание на русском языке ко всем типам
types: [
{ value: "feature", name: "feature: Добавление нового функционала" },
{ value: "fix", name: "fix: Исправление ошибок" },
{ value: "docs", name: "docs: Обновление документации" },
{ value: "test", name: "test: Добавление тестов" },
{
value: "refactor",
name:
"refactor: Правки кода без исправления ошибок или добавления новых функций"
},
{
value: "perf",
name: "perf: Изменения направленные на улучшение производительности"
},
{
value: "style",
name:
"style: Правки по кодстайлу (табы, отступы, точки, запятые и т.д.)"
},
{
value: "build",
name: "build: Сборка проекта или изменения внешних зависимостей"
},
{ value: "ci", name: "ci: Настройка CI и работа со скриптами" },
{ value: "revert", name: "revert: Откат на предыдущие коммиты" }
],
// Область. Она характеризует фрагмент кода, которую затронули изменения
scopes: [
{ name: "Кэш" },
{ name: "ФормаОсновная" },
{ name: "Валидация" },
{ name: "АвтоматическоеТестирование"},
{ name: "Отчеты" },
{ name: "ПервыйЗапуск" },
{ name: "ЗащитаМодуля" },
{ name: "ТребованияКПроизводительности" },
{ name: "ХранениеДанных" },
{ name: "API" }
],
// Возможность задать спец ОБЛАСТЬ для определенного типа коммита (пример для 'fix')
/*
scopeOverrides: {
fix: [
{name: 'style'},
{name: 'e2eTest'},
{name: 'unitTest'}
]
},
*/
// Поменяем дефолтные вопросы
messages: {
type: "Какие изменения вы вносите?",
scope: "\nВыберите ОБЛАСТЬ, которую вы изменили (опционально):",
// Спросим если allowCustomScopes в true
customScope: "Укажите свою ОБЛАСТЬ:",
subject: "Напишите КОРОТКОЕ описание:\n",
body:
'Напишите ПОДРОБНОЕ описание (опционально). Используйте "|" для новой строки:\n',
breaking: "Список BREAKING CHANGES (опционально):\n",
footer:
"Место для мета данных (тикетов, ссылок и остального). Например: SECRETMRKT-700, SECRETMRKT-800:\n",
confirmCommit: "Вас устраивает получившийся коммит?"
},
// Разрешим собственную ОБЛАСТЬ
allowCustomScopes: true,
// Запрет на Breaking Changes
allowBreakingChanges: false,
// Префикс для нижнего колонтитула
footerPrefix: "YT:",
// limit subject length
subjectLimit: 72
};
В блоке types описываем префиксы изменений: feature, fix и т.д.
В блоке scope описываем блоки, с которыми будем работать. Есть возможность оставить пустым или указать собственный блок.
В поле footerPrefix можно задать префикс для системы учета задач.
В subjectLimit задается ограничение на длину короткого коммита. Часто звучит ограничение, что описание должно содержать глагол в повелительном наклонении, но у меня ни разу не получилось так написать.
При установке cz-customizable создается alias для гита: git cz. Индексируем изменения и выполним команду. Тогда откроется окно для ввода описания:
После выбор типа изменений:
Если нужна своя область
Описание коммита
Указываем номер задачи
В конце будет показан итоговый вид сообщения коммита. Можно отказаться или отредактировать.
Соглашаемся и смотрим что получилось.
Лайфхаки
Пара лайфхаков, которые я используются в работе.
Автодокументация
Мы создали документацию проекта на markdown. Разбили ее на значимые блоки. Добавили commit-msg hook(действие в гит, после изменения сообщения коммита) – сообщение коммита добавляется в историю изменений конкретного блока.
Smartgit
Перешли с SourceTree на SmartGIT. Главной киллфичей являлось то, что на дополнительные действия можно назначать хоткеи. Я добавил себе привычную комбинацию Ctrl-Shift-C и быстро вызываю окно для ввода сообщения коммита.
После всего недели использования, я уже не мог понять – как раньше жил без такого удобного инструмента. Более того, даже если в проекте не настроен commitizen, я руками завожу аналогичное вида сообщение.
Удачных всем коммитов.
