Использование 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, я руками завожу аналогичное вида сообщение.

Удачных всем коммитов.