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

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

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

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

Что такое changelog?

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

Что такое release notes?

Release notes — это избирательное сообщение, написанное прозой, об одном релизе. Его читатель ещё ничего не решил. Он решает, важен ли ему этот релиз, и нужно ли ему что-то с этим делать. Отбор — вся ценность: release note, перечисляющая всё, — это changelog с абзацами, и она подводит читателя так же, как changelog, пропускающий что-то, подводит своего. Как писать 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, Шаблон релиз-нот