Перевод моей статьи на бразильский португальский.

Спасибо моему другу Guilherme Virtuoso за помощь в переводе статьи.

- Версия для португальского языка

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

Несколько месяцев назад я начал работать над множеством проектов параллельно, и мне нужно было найти способ автоматизировать и стандартизировать этот процесс документирования эпических моментов процесса разработки моего приложения, и именно тогда я обнаружил auto -changelog , которая соответствует моим потребностям.

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

Репозиторий со стартовым комплектом, включающим все конфигурации, сделанные при чтении этой статьи: https://github.com/tiagoboeing/auto-changelog-starter-kit

Угадайте, что будет на выходе?

Вот как выглядят сообщения фиксации: (Я взял первую фиксацию, чтобы объяснить)

В этой статье версии фиксации используют стандарт SEMVER:
Например: 1.0.0; 1.1.0; 2.0.0; 2.0.1 …….… 33.22.1

Давайте начнем!

Установите в свой проект зависимость auto-changelog.

npm install auto-changelog --save-dev
# or
yarn add auto-changelog --dev

В тестовых целях вы можете установить глобально:

npm install -g auto-changelog

Если вы не установили глобально, вам нужно настроить свой package.json файл для запуска auto-changelog скрипта:

scripts: {
   "changelog": "auto-changelog --template changelog-template.hbs -p -u --commit-limit false",
   "changelog-debug": "auto-changelog --template changelog-template.hbs -p --template json --output changelog-data.json"
}
...

В приведенном выше примере единственный требуемый сценарий - это changelog. changelog-debug не является обязательным, хотя он чрезвычайно интересен, если вы хотите проверить, как создается ваш журнал изменений.

Создание журнала изменений:

auto-changelog --template changelog-template.hbs -p -u --commit-limit false
  • auto-changelog - команда модуля узла
  • --template changelog-template.hbs - параметр для настройки файла шаблона для сообщений журнала изменений
  • -p - используйте версию SEMVER из package.json в качестве последней версии
  • -u - включить невыпущенные изменения в журнал изменений
  • --commit-limit false - снять ограничение на количество коммитов на выпуск в журнале изменений (по умолчанию: 3)

Имя файла журнала изменений по умолчанию - «CHANGELOG.md».

Вы можете изменить имя файла с помощью -o или --output (например: -o HISTORY.md)

Сторонние интеграции (ClickUp, Jira и т. Д.) И ограничивающие ветки

Этот шаг очень важен для правильной работы зависимости автоматического журнала изменений.
Если вы не интегрируетесь с другими сервисами, такими как ClickUp или Jira, вы можете удалить или просто инициализировать пустым объектом или пустой строкой ({} или "") следующие атрибуты:

  • replaceText
  • issueUrl

В вашем package.json создайте новое свойство, включая:

"auto-changelog": {
   "commitLimit": false,
   "unreleased": true,
   "issueUrl": "https://app.clickup.com/t/{id}",
   "replaceText": {
      "[Ff]eature:": "",
      "[Ff]ix:": "",
      "[Bb]reak:": "",
      "^ #(.{6})\\s": "[$1](https://app.clickup.com/t/$1) - "
   },
   "includeBranch": [
      "develop",
      "master"
   ]
}

Вы можете использовать свойства commitLimit и unreleased как резервные, даже перезаписанные командной строкой. Это необязательно.

Вы предпочитаете Jira?

Нет проблем, воспользуйтесь приведенным ниже примером:

"auto-changelog": {
    "commitLimit": false,
    "unreleased": true,
    "issueUrl": "https://jira.user.com.br/browse/{id}",
    "replaceText": {
      "[Ff]eature:": "",
      "[Ff]ix:": "",
      "[Bb]reak:": "",
      "([A-Z]+-\\d+)": "[$1](https://jira.user.com.br/browse/$1) - "
    },
    "includeBranch": [
      "develop",
      "master"
    ]
}

Настроить шаблон журнала изменений

В корневой папке вместе с вашим package.json файлом создайте файл с таким же значением, установленным в свойстве --template. В нашем примере это changelog-template.hbs

Вставьте это содержимое в файл:

Понимание шаблона

Вы должны использовать переменные журнала автоизменений с такой интерполяцией: {{var}}

  • {{#each releases}}: перебирает каждый выпуск, в нашем случае мы включаем еще не сгенерированный выпуск.
  • # {{title}}: мы создаем заголовок markdown уровня 1, который будет содержать название версии (например, 1.0.0). Чуть ниже мы добавляем дату версии в соответствии со стандартом ISO 2020–01–03.
  • Мы создаем три раздела в журнале изменений (новые функции, исправления (исправления, исправления и т. Д.) И нарушения совместимости).
  • Создайте три раздела в журнале изменений, один для новых функций, исправлений (исправлений, исправлений и т. Д.) И просто нарушения совместимости.
  • {{#commit-list}}: Обходит список фиксации, пытаясь сопоставить шаблон регулярного выражения сообщения. Он также исключит коммиты, соответствующие параметру «exclude».

Как пользоваться?

Если вы ничего не меняли, чтобы настроить по своему усмотрению, у нас будет три возможных раздела:

  • feature:
  • fix:
  • break:

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

feature: #1b1d0g Adiciona nova dependência

Нет задачи по ClickUp, Jira и т. Д.?

feature: Adiciona nova dependência

Создание журнала изменений

Мы сделали! Теперь просто запустите команду:

npm run changelog
# or
yarn changelog

Если вы хотите проверить в json-файле, что будет сгенерировано, запустите npm run changelog-debug, и в корневой папке вы найдете файл с именем «changelog-data.json». По этой причине мы создали тег с именем changelog-debug в разделе сценария в вашем package.json.

Конечным результатом будет файл с именем CHANGELOG.md. Будьте осторожны, если у вас уже есть файл с таким именем, он будет перезаписан.

Это хорошая идея реализовать этот шаг в конвейере CI ;-)

Дополнительный