Блог Changeloop
Релиз-ноты на практике
Две вещи, о которых мы много думаем: как писать релиз-ноты, которые кто-то прочтёт, и как перестать вести changelog вручную. Без рассылки и без регистрации. Только тексты.
Альфа- и бета-тестирование: отличия и когда что запускать
Альфа- и бета-тестирование: кто тестирует, насколько готова сборка, закрытая и открытая бета, критерии выхода и как собирать фидбэк бета-тестировщиков.
Обратная связь6 мин чтения
Что такое хотфикс: значение, хотфикс и патч, как выпустить
Хотфикс: срочное исправление вне обычного цикла релизов. Что означает термин, чем он отличается от патча и багфикса и как выпустить его безопасно.
Инженерия5 мин чтения
Модель Кано: сортировка запросов по реакции клиентов
Модель Кано делит функции на обязательные, линейные и восхищающие по двум вопросам анкеты. Как применить её к запросам на функции и прочитать результат.
Обратная связь5 мин чтения
Релиз-кандидат (RC): что это и как его провести
Релиз-кандидатом называют сборку, которая выходит финальной версией, если тесты не найдут блокер. Место RC после беты, версионирование и критерии выхода.
Инженерия4 мин чтения
RICE-приоритизация: формула, пример расчёта и ошибки
RICE-приоритизация ранжирует идеи по охвату, влиянию, уверенности и усилию. Формула, пример на четырёх функциях, шкалы и ошибки, которые искажают оценку.
Обратная связь4 мин чтения
CHANGELOG.md: что в него писать и как держать актуальным
CHANGELOG.md это читательская запись о том, что изменилось в каждой версии. Нужные разделы, полный пример и одна привычка, которая держит файл актуальным.
Инженерия5 мин чтения
Release notes на GitHub: сгенерировать и сделать читаемыми
GitHub пишет черновик release notes из влитых pull request в один клик. Что в нём есть, как его формирует release.yml и какая правка делает его читаемым.
Инженерия6 мин чтения
Как составить product roadmap по отзывам клиентов
Как составить product roadmap за шесть шагов, начав с запросов, которые у вас уже есть: сгруппировать, ранжировать, оценить уверенность и пересматривать.
Обратная связь5 мин чтения
Шаблон product roadmap: поля, которые стоит копировать
Шаблон product roadmap это таблица с фиксированными полями для каждой строки. Возьмите версию из шести полей, посмотрите пример и узнайте, что убрать.
Обратная связь5 мин чтения
Версионирование REST API: URL, заголовок или query
Версионирование REST API помещает версию в путь, заголовок или строку запроса. Что каждый вариант значит для вызывающих, кэшей и объявлений, с примерами.
Изменения API5 мин чтения
Release notes программного обеспечения: что включать
Release notes программного обеспечения говорят, что изменилось в версии, кого это касается и что делать. Четыре вида, состав записи и разобранный пример.
Релиз-ноты на практике4 мин чтения
Release notes об исправлении багов: как писать записи
Release notes об исправлении багов работают, когда запись называет симптом, охват и действие. Примеры до и после, правила для безопасности и данных.
Релиз-ноты на практике6 мин чтения
Как попросить обратную связь у клиентов в софтовом продукте
Задайте один конкретный вопрос сразу после действия пользователя, прямо там, где он работает. Готовые формулировки для каждого момента и плохие вопросы.
Обратная связь6 мин чтения
Примеры product roadmap: шесть форматов и их слабые места
Шесть примеров product roadmap с реалистичными пунктами: Now/Next/Later, квартальный, тематический, по результатам, публичный и релизный. Кому они нужны.
Обратная связь6 мин чтения
Процесс управления релизами для частых выпусков
Процесс управления релизами для софтверных команд в семь шагов, с владельцем и критерием выхода для каждого, плюс метрики DORA и ещё один показатель.
Инженерия7 мин чтения
Примеры release notes для каждого вида изменений
Примеры release notes для новой функции, исправления, breaking change, уязвимости, депрекации, заметки в сторе и внутренней заметки, с разбором слов.
Релиз-ноты на практике7 мин чтения
Версионирование 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 мин чтения
Release notes для функции за флагом: что сказать и когда
Release notes для функции за флагом различают merge и выпуск: с флагом это разные события. Закрыв петлю рано, вы сообщите о функции, которую ещё не видно.
Обратная связь5 мин чтения
Как отслеживать запросы на функции, не теряя их
Отслеживание запросов обычно проваливается: запросы не доходят никуда, или доходят туда, куда никто не возвращается. Система, выдерживающая оба сбоя.
Обратная связь5 мин чтения
Запрос на функцию или отчёт об ошибке: как отличить
Тикет поддержки с просьбой новой настройки может быть обходным путём для скрытой ошибки. Неверная метка отправляет его не той владелице и не в ту очередь.
Обратная связь5 мин чтения
Тикеты Поддержки vs. Запросы Функций: Чему Доверять?
Тикет поддержки и доска запросов на функции измеряют разное, и приравнивание всплеска в одном к всплеску в другом даёт уверенные, но неверные приоритеты.
Обратная связь4 мин чтения
Git-теги, релизы GitHub и changelog: в чём разница
Git-тег, релиз и запись changelog фиксируют одно событие трижды. Их смешивание заставляет changelog дрейфовать. Как трём этим вещам следует совпадать.
Инженерия5 мин чтения
Внутренние changelog API: что меняется для другой команды
У публичного changelog API аудитория, до которой не дотянуться напрямую. У внутреннего она сидит этажом ниже, и это меняет то, что changelog ей должен.
Изменения API5 мин чтения
Внутренние release notes: кому ещё нужно знать, что вышло
Саппорт и продажи узнают о запуске от растерянного клиента. Внутренние release notes решают эту проблему в форме, отличной от той, что видят клиенты.
Релиз-ноты на практике5 мин чтения
Release notes мобильных приложений: App Store и Google Play
App Store допускает 4000 символов, Google Play 500, и оба показывают пару строк без ссылок. Что режет лимит и как сократить текст намеренно.
Релиз-ноты на практике4 мин чтения
Changelog монорепозитория: один, или по одному на пакет?
Монорепозиторий может вести один changelog на весь репозиторий или по одному на пакет. Неверный выбор делает релиз либо слишком шумным, либо разрозненным.
Инженерия5 мин чтения
Анонс новой функции: шаблоны и как его написать
Большинство анонсов умирает в канале, который никто не читает дважды. Где анонсировать, что сказать первым, и до кого нужно достучаться в первую очередь.
Релиз-ноты на практике5 мин чтения
Enterprise release notes: что меняется для одного аккаунта
Enterprise release notes для клиента на приватной сборке нужно откалибровать под его инстанс. Ошибка в калибровке сливает roadmap или путает поддержку.
Релиз-ноты на практике4 мин чтения
Как приоритизировать растущий поток запросов на функции
Бэклог не отвечает на главный вопрос: какой запрос делать первым. Рабочие фреймворки приоритизации, где каждый ломается и что скрывает число голосов.
Обратная связь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, или журнал изменений, представляет собой датированную запись изменений продукта для его пользователей. Пример записи и шаблон для копирования.
Релиз-ноты на практике5 мин чтения
Changelog API: что публиковать и кто это читает
Changelog API читают те, кто решает, будет ли их код работать через месяц. Что каждая запись им должна, где ей место, и как на неё подписаться.
Изменения API6 мин чтения
Публичная страница changelog: как сделать, чтобы читали
Страница changelog оправдывает себя, когда люди возвращаются на неё. Где ей место, что нужно каждой записи, потоки и разметка, и куда встроить виджет.
Инженерия5 мин чтения
Шаблон письма об обновлении продукта, которое читают
Письмо об обновлении продукта, которое читают, ушло тому, кто его попросил. Шаблон, четыре типа писем, рабочие темы, сегментация и согласие.
Релиз-ноты на практике5 мин чтения
Депрекация API: сроки, уведомление и заголовки RFC 9745
Депрекация представляет собой обещание с датой. Расписание, шаблон уведомления, заголовки ответа и шаг, не дающий sunset стать инцидентом поддержки.
Изменения API5 мин чтения
Лучшие практики версионирования API, ради вызывающих
Версионируйте только то, что ломает совместимость, размещайте версию там, где её видят вызывающие, и держите старую до даты. Четыре схемы сравнены.
Изменения API6 мин чтения
Что такое breaking change? Что считается и как выпустить
Breaking change это изменение, которое не пережил бы корректный вызывающий. Что считается, что нет, как поймать его в CI и безопасно выпустить.
Изменения API9 мин чтения
Замыкание петли обратной связи со стороны changelog
Петля обратной связи замыкается, когда запросивший знает: выпущено. Петля в четырёх шагах, где рвётся, и почему замыкать её лучше всего из changelog.
Обратная связь7 мин чтения
Шаблон запроса функции, становящийся changelog
Запрос функции полезен только тогда, когда его можно найти при выпуске. Шаблон, метки, которые его направляют, и поля, которые потом читает changelog.
Обратная связь6 мин чтения
Публичная roadmap из вашего issue-трекера, три колонки
Публичная roadmap это обещание о будущем. Держите её маленькой, питайте из уже отслеживаемых issue и перемещайте каждый элемент меткой на его issue.
Обратная связь5 мин чтения
Автоматизация changelog: что автоматизировать, а что нет
Автоматизируйте сбор, форматирование и публикацию. Не автоматизируйте отбор или формулировку. Где граница и что происходит, когда она сдвигается.
Инженерия6 мин чтения
Changelog vs release notes: в чём разница?
Changelog служит непрерывным реестром для того, кто что-то ищет. Release notes дают отобранное сообщение тому, кто решает, важно ли это ему.
Релиз-ноты на практике5 мин чтения
От conventional commits к changelog
Conventional commits делают changelog выводимым из истории, но не делают его читаемым. Что даёт эта конвенция, где она заканчивается и как закрыть разрыв.
Инженерия5 мин чтения
Как писать release notes, которые реально читают
«Исправления багов и улучшения производительности» не годится как release note. Вопрос, на который должна отвечать каждая запись, и переписанный пример.
Релиз-ноты на практике6 мин чтения
Keep a Changelog: объяснение и шаблон CHANGELOG.md
Спецификация Keep a Changelog занимает одну страницу, но команды сбиваются при внедрении. Что она требует, что оставляет на ваше усмотрение и где подводит.
Инженерия5 мин чтения
Лучшие практики release notes, которые важны
Большинство списков лучших практик сводится к советам по стилю. Эти меняют поведение читателя, плюс три популярных, которые оказываются карго-культом.
Релиз-ноты на практике5 мин чтения