Release notes об исправлении багов: как писать записи

Хорошие release notes об исправлении багов описывают, что пользователь увидел сломанным, а не что было неправильно в коде. Каждая запись говорит, кого это задело, с какого момента, полностью ли исправлено и нужно ли читателю что-то делать, даже если это лишь «действий не требуется».

Большинство команд копирует строку из сообщения коммита. В таблице шесть переписанных примеров, а разделы после неё объясняют правила.

Как написать запись об исправлении бага в release notes?

Начните с симптома словами пользователя, затем скажите, кого это задело и с какого времени, затем в каком состоянии исправление, затем что делать. Обычно хватает одного-двух предложений. Причина в коде относится к pull request, где её будет искать инженер.

Читатель ищет одно: «это было со мной?» Почти любую запись закрывают четыре части:

1. Симптом. Что появилось на экране, в ответе API или в счёте. Процитируйте текст ошибки, если она была, потому что люди ищут по нему.
2. Охват. Какой план, платформа, версия API или вид данных. «Аккаунты с более чем 50 000 строк» можно проверить. «Некоторые пользователи» нельзя.
3. Период. С какого релиза или даты, чтобы читатель мог решить, был ли вчерашний странный результат этим багом.
4. Действие. Запустить заново, синхронизировать заново, обновиться, убрать обходной путь или ничего.

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

В чём разница между release note и changelog?

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

Опечатка во всплывающей подсказке относится только к changelog. Неверная ставка налога в счетах относится к обоим. Полное разделение описано в статье changelog vs release notes, а форма хорошего набора заметок в статье как писать release notes.

Keep a Changelog удобное соглашение для стороны журнала. Оно держит «Fixed» для любых исправлений багов и отдельный заголовок «Security» для уязвимостей, и это то же разделение, которое эта статья делает для читателя.

Является ли исправление бага обновлением?

Да. Исправление бага меняет продукт, так что его выпуск это обновление. По семантическому версионированию обратно совместимое исправление это патч-релиз, например с 4.2.0 до 4.2.1.

Нужно ли читателю что-то делать, это отдельный вопрос, и заметка должна на него отвечать. Исправление, меняющее то, что видит корректный вызывающий, близко к breaking change, а где проходит эта граница, объясняет статья breaking changes.

Когда исправлению нужна отдельная запись, а когда это мелкое исправление?

Давайте исправлению отдельную запись, когда пользователь мог заметить баг, потерять из-за него время или данные или построить вокруг него обходной путь. Группируйте его в короткий список «Мелкие исправления», когда никто вне команды не мог его увидеть. Судите по опыту читателя, а не по размеру диффа.

Каждая строка в группе всё равно должна что-то говорить: «Исправлены некоторые проблемы интерфейса» это заглушка.

Как писать о регрессии?

Назовите релиз, внёсший её, назовите это регрессией и назовите релиз, который её исправляет. Те, кто столкнулся с багом, и так знают, что что-то сломалось, поэтому короткое прямое признание служит им лучше расплывчатой формулировки.

Например: «В 4.1.0 поиск по запросам с дефисом возвращал пустой результат. Это исправлено в 4.1.1. Если вы меняли запросы, чтобы обойти дефисы, можно вернуть прежние».

«Улучшена надёжность поиска» читается как увёртка для всякого, кто потерял на этом баге вечер. Если причина ещё уточняется, скажите об этом, как советует руководство по экстренным release notes: заметка никогда не должна звучать увереннее, чем команда.

Как объявить об исправлении уязвимости?

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

Порядок важен: сообщивший пишет вам приватно, вы выпускаете исправление, а публичная заметка выходит, когда пользователи могут защититься. Процесс скоординированного раскрытия уязвимостей CISA координирует сообщение об уязвимости, её анализ и публичное раскрытие. Правила CVE Numbering Authority определяют, как записи CVE присваиваются и публикуются, а на GitHub repository security advisory позволяет приватно подготовить бюллетень и запросить идентификатор.

Запись о безопасности обычно несёт четыре факта:

• Что мог сделать атакующий, одним предложением и без proof of concept.
• Затронутые версии и версия, которая это исправляет.
• Насколько срочно: «обновитесь сегодня» или «обновитесь в следующем релизе».
• Видели ли вы эксплуатацию и благодарность сообщившему, если он согласился.

Шаги эксплуатации не публикуйте.

Что заметка должна сказать об исправлении потери данных?

Скажите, какие данные были затронуты, как понять, задело ли ваши, и можно ли их восстановить. «Действий не требуется» здесь редко бывает правдой, а первый вопрос читателя: «мои данные пропали?»

В полезной записи есть условие, при котором данные терялись («удаление папки во время работающей синхронизации»), период, когда это было возможно, способ проверки («откройте корзину и поищите элементы с датами с 3 по 9 сентября») и путь восстановления. Если данные восстановить нельзя, так и скажите. Свяжитесь с затронутыми клиентами ещё и напрямую: release note не должна быть единственным местом, где человек узнаёт, что его данные пострадали.

Почему «Исправления багов и улучшения производительности» плохая заметка?

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

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

До:
  Исправления багов и улучшения производительности.

После:
  Исправлено: экспорт CSV падал для проектов без тегов.
  Исправлено: в тёмной теме не был виден курсор в поле
  комментария.
  Быстрее: панель открывается быстрее для рабочих
  пространств со 100+ проектов.

Откуда берутся заметки об исправлении багов?

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

Почему правильная пометка сообщения решает, кому оно достанется, объясняет статья запрос на функцию или ошибка. В Changeloop баг, о котором сообщили через виджет, становится задачей GitHub с меткой bug, а запись в changelog составляется из влитого pull request и удерживается до одобрения человеком перед публикацией. Шаблон release notes даёт ту же форму записи для ручного письма: симптом, охват, период, действие.

FAQ

Что должны включать release notes об исправлении багов? Каждая запись должна называть симптом, который видел пользователь, кого это задело, с какого релиза или даты, полностью ли исправлено и что нужно сделать читателю, включая «ничего».

Нужно ли перечислять в release notes каждое исправление бага? Нет. Перечисляйте те, которые пользователь мог заметить, на которые потерял время или которые обходил, а косметические и внутренние группируйте в короткий список «Мелкие исправления». Changelog хранит каждое исправление для тех, кому нужно что-то найти.

Как писать release notes о баге, который внесли вы? Скажите, что это была регрессия, назовите релиз, который её внёс, и релиз, который исправляет, и сообщите читателям, могут ли они убрать обходной путь. Прямое утверждение читается лучше смягчённого.

Как найти release notes продукта, которым вы пользуетесь? Ищите страницу changelog или release notes по ссылке в меню помощи продукта, подвале или документации, а для проектов с открытым кодом на вкладке релизов репозитория.

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

По теме на changeloop: Шаблон релиз-нот