wpnext
github wpnext
Cover Image for Keep a Changelog: как вести понятный ченджлог и не превращать его в хаос git log

Keep a Changelog: как вести понятный ченджлог и не превращать его в хаос git log

9 декабря 2025

Ченджлог — это история изменений для людей. Разберём формат Keep a Changelog, семантическое версионирование и рабочие шаблоны для плагинов/тем WordPress и WooCommerce, включая автоматизацию и анти‑паттерны.

TL;DR

  • Не копируйте git log в ченджлог: пишите для людей, а не для машин.
  • Следуйте SemVer: MAJOR.MINOR.PATCH, фиксируйте дату в ISO 8601 (YYYY-MM-DD).
  • Используйте разделы: Added, Changed, Deprecated, Removed, Fixed, Security.
  • Держите вверху раздел Unreleased и переносите его в релиз при публикации.
  • Отмечайте breaking changes и депрекейшены явно и громко.
  • Для WordPress: синхронизируйте CHANGELOG.md и Changelog в readme.txt, превращайте записи в понятные Release notes.
  • Автоматизируйте сборку черновика ченджлога, но финальный текст редактируйте вручную.

Зачем нужен ченджлог

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

Почему не стоит «дампить» git log

Сырые коммиты полны шума: мержи, технические правки, краткие или внутренние сообщения. Цель коммита — зафиксировать шаг развития кода, часто мелкий и локальный. Цель ченджлога — передать смысловые изменения, часто объединяющие несколько коммитов, на языке пользователя. Поэтому: «Don’t let your friends dump git logs into changelogs.»

Принципы Keep a Changelog

  • Структура единообразна, по убыванию версий: последняя — сверху.
  • Каждая версия имеет дату в формате YYYY-MM-DD.
  • Одинаковые типы изменений группируются по разделам:
  • Added — новые возможности;
  • Changed — изменения текущего поведения;
  • Deprecated — то, что будет удалено позже;
  • Removed — то, что уже удалено;
  • Fixed — исправления ошибок;
  • Security — закрытые уязвимости.

Плюс постоянный раздел Unreleased — конвейер набора изменений, готовящихся к следующему релизу.

SemVer кратко

Используйте семантическое версионирование MAJOR.MINOR.PATCH:

  • MAJOR — несовместимые изменения (breaking changes);
  • MINOR — новые совместимые возможности;
  • PATCH — совместимые исправления ошибок.

Если меняете публичные PHP‑API, хелперы, JS‑события, REST‑эндпоинты, поведение шаблонов WooCommerce — подумайте о MINOR/MAJOR и чётком описании миграции.

Шаблон CHANGELOG.md

# Changelog

Все значимые изменения в этом проекте документируются здесь.
Формат вдохновлён практиками Keep a Changelog. Проект следует SemVer.

## [Unreleased]
### Added
- ...
### Changed
- ...
### Deprecated
- ...
### Removed
- ...
### Fixed
- ...
### Security
- ...

## [1.2.0] - 2025-12-08
### Added
- Совместимость с новым Checkout Block WooCommerce 9.0.
### Changed
- Изменена логика кэширования данных корзины для повышения производительности.
### Deprecated
- Фильтр `my_plugin_legacy_price` будет удалён в 2.0.0; используйте `my_plugin_price`.
### Removed
- Поддержка PHP 7.2.
### Fixed
- Исправлена ошибка округления при применении купонов.
### Security
- Закрыт XSS в параметре виджета поиска (CVE‑ID, при наличии).

## [1.1.3] - 2025-11-01
### Fixed
- Исправлен фатал при активации без WooCommerce.

Практики для WordPress и WooCommerce

  • Два источника правды. Храните детальный CHANGELOG.md в корне репозитория и синхронизируйте ключевые записи в разделе Changelog файла readme.txt для каталога плагинов. Для тем — в readme и карточке релиза.
  • Release notes без жаргона. Превращайте записи из разделов в понятный текст о выгодах: «Добавили поддержку мультивалютности», а не «refactor: split priceService».
  • Депрекейшены. ОтмечайтеDeprecated/Removed. В коде используйте _deprecated_function, _deprecated_hook и аналогичные нотификации, а в ченджлоге пишите куда мигрировать и в какой версии произойдёт удаление.
  • YANKED. Если релиз отозван из‑за критической ошибки или уязвимости — оставьте его в истории с заметной меткой [YANKED] и краткой причиной.
  • Даты. Придерживайтесь ISO 8601: 2025-12-08 — это однозначно и удобно сортируется.

Анти‑паттерны

  • Commit log diffs. Много шума, мало пользы.
  • Игнорирование депрекейшенов. Пользователь должен иметь «окно» для миграции.
  • Непоследовательность. Если из релиза в релиз то пишете, то забываете важные изменения — доверие к документу падает.
  • Неоднозначные даты. Избегайте местных форматов вроде 07/08/2025.

Как снизить трудозатраты

  • Ведите Unreleased. Добавляйте пункт при каждом PR, а в момент релиза переносите в новый раздел версии с датой.
  • Методика коммитов. Используйте соглашения о сообщениях (например, с типами feat/fix/breaking), чтобы автоматизировать черновик.
  • Инструменты. Подойдут генераторы черновиков: standard-version, release-please, release-it, git-cliff, towncrier. Пусть собирают «скелет», но смысловые формулировки шлифуйте вручную.
  • Шаблоны в репозитории. Добавьте ISSUE_TEMPLATE/PR_TEMPLATE с чек‑листом: «Добавлен пункт в Unreleased? Указаны Deprecated/Removed? Есть миграция?»
  • CI. Автоматизируйте: теги версии, публикацию релиза, обновление readme.txt и пакета для выгрузки.

Чек‑лист хорошего релиза

  • Версия по SemVer и дата в заголовке.
  • Все изменения распределены по разделам и кратко сформулированы на языке пользователя.
  • Breaking changes, Deprecated и Removed выделены и снабжены инструкцией миграции.
  • Security‑исправления отмечены отдельно.
  • Unreleased очищен после переноса пунктов в релиз.
  • CHANGELOG.md и Changelog в readme.txt синхронизированы.

Итог

Хороший ченджлог — это часть пользовательского опыта. Следуя Keep a Changelog и SemVer, вы снижаете риски обновлений, улучшаете саппорт и повышаете доверие к продукту. Не позволяйте друзьям превращать ченджлог в свалку git‑коммитов — пишите историю изменений для людей.

Источник: https://keepachangelog.com/ru/1.1.0/

Ещё почитать