Changeloop

Блог changeloop

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

Две вещи, о которых мы много думаем: как писать релиз-ноты, которые кто-то прочтёт, и как перестать вести changelog вручную. Без рассылки и без регистрации. Только тексты.

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

    Release notes об исправлении багов работают, когда запись называет симптом, охват и действие. Примеры до и после, правила для безопасности и данных.

    Релиз-ноты на практике6 мин чтения

  • Как попросить обратную связь у клиентов в софтовом продукте

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

    Обратная связь6 мин чтения

  • Примеры product roadmap: шесть форматов и их слабые места

    Шесть примеров product roadmap с реалистичными пунктами: Now/Next/Later, квартальный, тематический, по результатам, публичный и релизный. Кому они нужны.

    Обратная связь6 мин чтения

  • Процесс управления релизами для частых выпусков

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

    Инженерия6 мин чтения

  • Примеры release notes для каждого вида изменений

    Примеры release notes для новой функции, исправления, breaking change, уязвимости, депрекации, заметки в сторе и внутренней заметки, с разбором слов.

    Релиз-ноты на практике6 мин чтения

  • Версионирование API Stripe: как оно работает и что перенять

    Версионирование API Stripe привязывает аккаунт к версии с датой и даёт переопределить её в запросе. Как это работает, чего стоит и что взять малому API.

    Изменения API6 мин чтения

  • Кто пишет changelog, а кто должен

    Кто пишет changelog? Автор PR знает, что изменилось, а PM знает, почему это важно. Ни один из них в одиночку не напишет запись, полезную клиентам.

    Инженерия5 мин чтения

  • Экстренные Release Notes: Под Давлением Реального Времени

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

    Релиз-ноты на практике4 мин чтения

  • Breaking changes в Protobuf: что выживает на проводе

    Breaking changes в Protobuf происходят на проводе, а не в URL. Одни правки полей gRPC безопасны, другие молча ломают клиентов, а в диффе неотличимы.

    Изменения API5 мин чтения

  • Форматы файлов changelog: JSON, YAML или просто Markdown

    Формат файла changelog решает, может ли он питать страницу и виджет сразу, или его читает только человек. Markdown, JSON и YAML стоят по-разному.

    Инженерия5 мин чтения

  • Дублирующиеся запросы: объединение без потери голоса

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

    Обратная связь5 мин чтения

  • Изменения схемы GraphQL: депрекация без номера версии

    У GraphQL нет v1 или v2 в URL. Поля депрекируются по одному директивой, на общей схеме, которую используют все клиенты, и это меняет, что должен changelog.

    Изменения API5 мин чтения

  • Как написать гайд по миграции API

    Гайд по миграции API превращает несовместимое изменение в чек-лист вместо сбоя. Что он должен содержать, и почему одной записи недостаточно.

    Изменения API5 мин чтения

  • Проверка changelog для GitHub Actions

    Проверка changelog в GitHub Actions не пускает merge без записи: шаг, который держится на памяти, обязательно забывают. Как её настроить и что она ломает.

    Инженерия5 мин чтения

  • Как отказать в запросе на функцию, не потеряв клиентку

    Замыкание цикла обычно означает сказать кому-то, что его запрос выпущен. Более трудная половина — сказать нет, не повредив отношения с клиенткой.

    Обратная связь4 мин чтения

  • Как отслеживать запросы на функции, не теряя их

    Отслеживание запросов обычно проваливается: запросы не доходят никуда, или доходят туда, куда никто не возвращается. Система, выдерживающая оба сбоя.

    Обратная связь5 мин чтения

  • Release notes для функции за флагом: что сказать и когда

    Release notes для функции за флагом различают merge и выпуск: с флагом это разные события. Закрыв петлю рано, вы сообщите о функции, которую ещё не видно.

    Обратная связь5 мин чтения

  • Когда запрос на функцию на самом деле — отчёт об ошибке

    Тикет поддержки с просьбой новой настройки может быть обходным путём для скрытой ошибки. Неверная метка отправляет его не той владелице и не в ту очередь.

    Обратная связь4 мин чтения

  • Тикеты Поддержки vs. Запросы Функций: Чему Доверять?

    Тикет поддержки и доска запросов на функции измеряют разное, и приравнивание всплеска в одном к всплеску в другом даёт уверенные, но неверные приоритеты.

    Обратная связь5 мин чтения

  • Git-теги, релизы и ваш changelog

    Git-тег, релиз и запись changelog — три записи одного события. Их смешивание заставляет changelog дрейфовать. Как трём этим вещам следует совпадать.

    Инженерия4 мин чтения

  • Внутренние changelog API: что меняется для другой команды

    У публичного changelog API аудитория, до которой не дотянуться напрямую. У внутреннего она сидит этажом ниже, и это меняет то, что changelog ей должен.

    Изменения API5 мин чтения

  • Внутренние release notes: кому ещё нужно знать, что вышло

    Саппорт и продажи обычно узнают о запуске от растерянного клиента. Внутренние release notes это решают — в форме, отличной от той, что видят клиенты.

    Релиз-ноты на практике4 мин чтения

  • Release notes для мобильных приложений: что режет лимит

    App Store и Play Store показывают пару строк и не дают ссылок. Приёмы веб-changelog там не работают, сокращать нужно намеренно. Разбираем, что убрать.

    Релиз-ноты на практике4 мин чтения

  • Changelog монорепозитория: один, или по одному на пакет?

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

    Инженерия4 мин чтения

  • Как анонсировать новую функцию (без тишины)

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

    Релиз-ноты на практике4 мин чтения

  • Как приоритизировать растущий поток запросов на функции

    Бэклог не отвечает на главный вопрос: какой запрос делать первым. Рабочие фреймворки приоритизации, где каждый ломается и что скрывает число голосов.

    Обратная связь5 мин чтения

  • Enterprise release notes: что меняется для одного аккаунта

    Enterprise release notes для клиента на приватной сборке нужно откалибровать под его инстанс. Ошибка в калибровке сливает roadmap или путает поддержку.

    Релиз-ноты на практике5 мин чтения

  • Semantic versioning и ваш changelog

    Semantic versioning ещё до чтения changelog говорит, насколько болезненным будет релиз. Что обещает каждая цифра версии и что должна сказать запись.

    Инженерия5 мин чтения

  • Заголовок Sunset у API и когда его отправлять

    Заголовок Sunset сообщает клиенту API, когда версия перестанет отвечать, в отличие от уведомления о депрекации. Что покрывает RFC 8594 и что даёт brownout.

    Изменения API5 мин чтения

  • Changelog вебхуков: breaking change, который никто не просил

    Изменение payload вебхука ломается тихо, потому что его некому отклонить. Что делает изменение payload breaking, и как его правильно версионировать.

    Изменения API5 мин чтения

  • Changelog: что это такое, с примером записи

    Changelog, или журнал изменений, это датированный список того, что изменилось в продукте. Пример записи, отличие от release notes и где его держать.

    Релиз-ноты на практике5 мин чтения

  • Changelog API: что публиковать и кто это читает

    Changelog API читают те, кто решает, будет ли их код работать через месяц. Что каждая запись им должна, где ей место, и как на неё подписаться.

    Изменения API6 мин чтения

  • Как сделать страницу changelog, за которой следят

    Страница changelog оправдывает себя, когда люди возвращаются на неё. Где ей место, что нужно каждой записи, потоки и разметка, и куда встроить виджет.

    Инженерия5 мин чтения

  • Шаблон письма об обновлении продукта, которое читают

    Письмо об обновлении продукта, которое читают, ушло тому, кто его попросил. Шаблон, четыре типа писем, рабочие темы, сегментация и согласие.

    Релиз-ноты на практике5 мин чтения

  • Как деприкейтить API, не теряя разработчиков

    Депрекация — это обещание с датой. Расписание, шаблон уведомления, заголовки ответа, и шаг, не дающий sunset превратиться в инцидент поддержки.

    Изменения API5 мин чтения

  • Лучшие практики версионирования API, ради вызывающих

    Версионируйте только то, что ломает совместимость, размещайте версию там, где её видят вызывающие, и держите старую до даты. Четыре схемы сравнены.

    Изменения API6 мин чтения

  • Breaking changes: что считается и как выпустить

    Breaking change это изменение, которое не пережил бы корректный вызывающий. Что считается, что нет, как поймать его в CI и безопасно выпустить.

    Изменения API8 мин чтения

  • Замыкание петли обратной связи со стороны changelog

    Петля обратной связи замыкается, когда запросивший знает: выпущено. Петля в четырёх шагах, где рвётся, и почему changelog — верное место для замыкания.

    Обратная связь6 мин чтения

  • Шаблон запроса функции, становящийся changelog

    Запрос функции полезен только тогда, когда его можно найти при выпуске. Шаблон, метки, которые его направляют, и поля, которые потом читает changelog.

    Обратная связь5 мин чтения

  • Публичная roadmap из вашего issue-трекера, три колонки

    Публичная roadmap это обещание о будущем. Держите её маленькой, питайте из уже отслеживаемых issue и перемещайте каждый элемент меткой на его issue.

    Обратная связь5 мин чтения

  • Автоматизация changelog и её пределы

    Автоматизируйте сбор, форматирование и публикацию. Не автоматизируйте отбор или формулировку. Где граница и что происходит, когда она сдвигается.

    Инженерия5 мин чтения

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

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

    Релиз-ноты на практике5 мин чтения

  • От conventional commits к changelog

    Conventional commits делают changelog выводимым из истории, но не делают его читаемым. Что даёт эта конвенция, где она заканчивается и как закрыть разрыв.

    Инженерия5 мин чтения

  • Как писать release notes, которые реально читают

    «Исправления багов и улучшения производительности» — это не release note. Вопрос, на который должна отвечать каждая запись, и переписанный реальный пример.

    Релиз-ноты на практике5 мин чтения

  • Keep a Changelog, реально внедрённый

    Спецификация Keep a Changelog занимает одну страницу, но команды сбиваются при внедрении. Что она требует, что оставляет на ваше усмотрение и где подводит.

    Инженерия5 мин чтения

  • Лучшие практики release notes, которые важны

    Большинство списков лучших практик — это советы по стилю. Эти меняют поведение читателя, плюс три популярных, которые оказываются карго-культом.

    Релиз-ноты на практике5 мин чтения