Релиз-ноты на практике

Changelog vs release notes: в чём разница?

5 мин чтения обновлено

Changelog ведётся как непрерывный, накопительный реестр всего, что изменилось, и пишется для того, кто что-то ищет. Release notes дают отобранное сообщение об одном релизе, написанное для того, кто решает, важно ли ему это. Разница в аудитории, а не в форматировании, и большинству команд нужны оба: один как справочник, другой как анонс, выведенные из одних и тех же записей.

Большинство команд заканчивают с одним из них случайно, а с другим по запросу. Вы начинаете с changelog, потому что разработчица хочет реестр того, что было выпущено. Месяцами позже кто-то из поддержки спрашивает, почему клиенты не знали о функции, которая живёт с апреля, и теперь вам нужны release notes.

Changelog vs release notes, рядом друг с другом

ChangelogRelease notes
ЧитательТот, кто что-то ищетТот, кто решает, важно ли это ему
ОхватВсё, что изменилосьТо, что стоит сказать об этом релизе
ПериодичностьНепрерывная, при каждом merge или релизеПри релизе, и только тех, что стоит анонсировать
ТонКраткий, фактический, часто повелительныйОбъясняющий, иногда убеждающий
Срок жизниПостоянный, читается и годы спустяЧитается первую неделю, потом архивируется
Живёт вРепо, сайте документации, странице /changelogПисьме, in-app, посте блога, странице релиза
Терпит неудачу из-заНеполнотыСкучности, или слишком позднего появления

Что такое changelog?

Changelog представляет собой хронологический, почти полный реестр того, что изменилось, самое новое первым, с каждой записью, типизированной (added, changed, deprecated, removed, fixed, security) и датированной. Его читатель уже решил, что ему важно. Он что-то ищет: когда изменилось поведение, исправлен ли баг, какая версия ввела флаг. Вся ценность в полноте, поэтому конвенция Keep a Changelog тратит большую часть своей единственной страницы на структуру и почти ничего на прозу. Полное определение, с примером записи и шаблоном, в статье что такое changelog.

Что такое release notes?

Release notes составляют избирательное сообщение, написанное прозой, об одном релизе. Его читатель ещё ничего не решил. Он решает, важен ли ему этот релиз, и нужно ли ему что-то с этим делать. Вся ценность в отборе: release note, перечисляющая всё, превращается в changelog с абзацами, и она подводит читателя так же, как changelog, пропускающий что-то, подводит своего. Release notes программного обеспечения разбирают, что это такое и что включать, с разобранным примером, а как писать release notes о том, как отбирать и формулировать.

Нужен ли вам и changelog, и release notes?

Вам нужны оба, как только ваши две аудитории начинают хотеть разного; до этого один артефакт, выполняющий обе работы, как раз то, что нужно. Маленькие команды публикуют одну страницу /changelog с коротким абзацем в начале каждой записи, и какое-то время это одинаково хорошо служит и разработчице, ищущей исправление, и клиентке, просматривающей новости. Разделение слишком рано даёт вам два дела для поддержки, и одно из них сгниёт.

Разделение оказывается стоящим, когда начинает происходить это:

  • Ваши записи changelog обросли объясняющими абзацами, которые разработчики пропускают.
  • Или наоборот: ваши анонсы релизов начали перечислять обновления зависимостей.
  • Поддержка копирует записи в письма и переписывает их по пути.
  • Кто-то просит «только breaking change», а вы не можете их отфильтровать.

Последнее служит настоящим признаком. Если никто не может ответить «что изменилось, что касается меня», не прочитав всё, у вас один артефакт, плохо выполняющий две работы.

Один источник, два представления

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

Пишите changelog по ходу дела, одна запись на значимое изменение, каждая помечена тем, что она есть: fixed, added, changed, removed, deprecated, security. Держите записи достаточно короткими, чтобы написание одной не было решением. Затем, в момент релиза, release notes сводятся к отбору и переписыванию: возьмите записи, важные для человека, сгруппируйте их по тому, что они позволяют кому-то сделать, и поставьте причину сверху.

У этого есть практическое следствие. Если changelog служит источником, он должен быть структурированными данными, а не страницей, поддерживаемой вручную. Записи нужен тип, дата, версия и способ сказать, для кого она. Как только это есть, публичная страница, in-app виджет и лента RSS или JSON образуют три отображения одной вещи, и никто ничего не переписывает по пути к клиенту. Письмо с release notes может цитировать ту же запись, из любого инструмента, которым вы отправляете почту. Автоматизация changelog разбирает, какой из этих шагов должен принадлежать машине. В этом весь аргумент в пользу того, чтобы относиться к changelog как к ленте, а не как к странице. Это также, с полной прозрачностью, то, что мы строим, так что читайте это как интерес, а не беспристрастный опрос.

Если у вас есть время только на одно

Пишите changelog. Он дешевле на запись, полезен в день, когда вы его пишете, и release notes можно потом вывести из него. Обратное неверно: вы не можете восстановить год изменений из двенадцати писем с анонсами, а люди попросят вас об этом.

Держите его в фиксированном формате, чтобы вывод оставался возможным. Наша страница примеры changelog собирает записи от команд, делающих это хорошо, а шаблон release notes даёт форму, которую мы используем, превращая набор записей во что-то, что стоит отправить.

Заметка об именовании

Ничто из этого не стандартизировано, и вы найдёте «release notes», используемое для непрерывного списка, и «changelog», используемый для квартального анонса. Спорить о словах не стоит. Решите, какую из двух работ выполняет каждый из ваших артефактов, называйте это так, как уже называет ваша команда, и убедитесь, что ни один из них молча не делает оба.

На какой поверхности окажется результат, решается отдельно, разобранное в как сделать страницу changelog.

FAQ

Одно ли и то же changelog и release notes? Нет. Changelog служит полным реестром, читаемым теми, кто что-то ищет; release notes дают отобранный анонс, читаемый теми, кто решает, важно ли это им. Одно и то же изменение появляется в обоих, сформулированное по-разному для каждого читателя.

Можно ли сгенерировать release notes из changelog? Да, и это правильное направление. Отберите записи, важные для человека, сгруппируйте по результату, перепишите заголовок. Обратное, восстановление changelog из анонсов, теряет всё, что анонсы опустили.

Где должен жить changelog? Где-то постоянном и ссылаемом, куда читатель может добраться без репозитория: странице /changelog, сайте документации, или ленте, отображаемой в нескольких местах. Один CHANGELOG.md достигает контрибьюторов, но не клиентов.

Должен ли changelog включать внутренние изменения? Да, внизу, по одной строке каждое. Changelog остаётся полным реестром. Release notes тоже могут их содержать, в короткой последней секции, если изменения, которые читатель заметит, идут первыми.


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

По теме на Changeloop: Примеры changelog, Шаблон релиз-нот

changeloop
Команда, которая делает changelog, замыкающий цикл. Пользователи о чём-то просят, ваша команда это делает, тот, кто просил, узнаёт об этом.