changeloop blog

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

Fri, 02 Oct 2026 00:00:00 GMT

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

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

До (сообщение коммита)	После (симптом)
Fixed null pointer in export handler	Экспорты больше не падают с «Что-то пошло не так», если в проекте нет тегов. Запустите заново экспорты, упавшие с 3 сентября.
Resolved race condition in sync worker	Правки, сделанные на двух устройствах с разницей в несколько секунд, больше не затирают друг друга. Делать ничего не нужно.
Fix timezone bug	Отчёты по расписанию снова идут в заданное время. Аккаунты восточнее UTC получали отчёты на целый день раньше с 12 августа. Менять ничего не нужно.
Patched XSS in comment renderer	Безопасность: специально составленный комментарий мог выполнить скрипт в браузере другого пользователя. Обновитесь до 4.2.1 сегодня. В наших логах следов эксплуатации нет.
Fixed regression from 4.1.0	Поиск снова работает для запросов с дефисом. Он сломался в 4.1.0 и исправлен в 4.1.1.
Bug fixes and performance improvements	Назовите, какие именно. См. последний раздел.

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

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

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

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

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

В чём разница между 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 по ссылке в меню помощи продукта, подвале или документации, а для проектов с открытым кодом на вкладке релизов репозитория.

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

Fri, 02 Oct 2026 00:00:00 GMT

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

Большинство советов на эту тему написано для магазинов и сервисных стоек. Команда, делающая софт, точно знает, что пользователь сделал секунду назад, поэтому вопрос можно задать именно об этом.

Момент	Где спрашивать	Готовая формулировка
Сразу после завершения задачи	В приложении, рядом с результатом	«Этот экспорт сделал то, что вам было нужно?»
После первого использования новой функции	В приложении, один раз	«Что вы пытались сделать с помощью массового редактирования?»
После закрытия обращения в поддержку	В переписке с поддержкой	«Это помогло или что-то всё ещё не так?»
Когда пользователь застрял или бросил сценарий	Письмо на следующий день	«Вы остановились на шаге 3 настройки. Что помешало?»
После 30 дней регулярной работы	Письмо от конкретного человека	«Что одно вы бы изменили?»
Когда пользователь отменяет подписку	В процессе отмены	«Почему вы решили уйти именно сегодня?»
После выпуска того, что они просили	Там, где они просили	«Вы просили импорт CSV. Он готов. Он закрывает ваш случай?»

Когда лучше всего просить обратную связь?

Лучшее время наступает сразу после того, как пользователь что-то закончил, пока детали ещё свежи в голове. Вопрос, идущий за действием, получает ответ об этом действии. Вопрос, пришедший ниоткуда, получает ответ о настроении человека в этот момент или не получает никакого.

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

Где спрашивать обратную связь у клиентов?

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

Каждый канал даёт ответы своего рода:

В приложении: коротко, сразу и конкретно, но только от тех, кто сейчас рядом. От ушедших пользователей вы не услышите ничего.
Переписка с поддержкой: от людей, которым уже было достаточно плохо, чтобы написать. Хорошо для поиска сломанного, плохо для оценки остального продукта.
Письмо: более длинные ответы от меньшего числа людей и единственный способ достучаться до замолчавших пользователей. Пишите его как короткую записку от человека с именем, с одним вопросом внутри.
Интервью: способ понять, почему люди делают то, что делают. Попросите показать, как они работают, и молчите, пока они показывают.

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

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

Будьте конкретны в предмете, объясните, зачем спрашиваете, и сделайте так, чтобы ответ занимал меньше минуты. Профессиональная просьба называет момент, даёт понять, что ответ прочтёт человек, и не извиняется за беспокойство.

Назовите точное действие («экспорт, который вы только что запустили»), просите об одном, дайте текстовое поле без обязательных полей и подпишитесь именем.

Какая фраза хороша для просьбы об обратной связи?

Хорошая фраза это вопрос о конкретном моменте, на который можно ответить несколькими словами. Сравните две колонки ниже. На левые можно ответить пожатием плеч. Правые требуют вспомнить что-то настоящее.

Слабый вопрос	Сильный вопрос
«Есть отзывы?»	«Что было самым трудным при настройке?»
«Как вам наш продукт?»	«Для чего вы использовали это на прошлой неделе?»
«Оцените впечатление от 1 до 10.»	«Вы сделали сегодня то, ради чего пришли?»
«Расскажите, как нам стать лучше.»	«Что одно замедлило вас на этой неделе?»
«Порекомендуете ли вы нас?»	«Кому вы показывали это в последний раз и что сказали?»

Ещё один вопрос, который работает почти везде: «Чем вы пользуетесь вместо этого, когда это вам не подходит?» Он выявляет настоящего конкурента, которым часто оказывается таблица.

Какие просьбы об обратной связи хуже всего?

Хуже всего просьбы слишком широкие, ранние, длинные или наводящие. У них общая проблема: человек не может ответить, не проделав мыслительную работу, которую должны были сделать вы.

«Пожалуйста, заполните наш опрос из 20 вопросов». Дойдут до конца те, у кого больше всего свободного времени или самые сильные мнения.
Всплывающее окно на первой странице после входа. Пользователь пришёл что-то сделать, а вы ему помешали. Единственный разумный ответ на него это закрыть окно.
«Мы будем рады вашему отзыву!» без вопроса. Это просит пользователя самого придумать тему.
Наводящий вопрос: «Насколько вам нравится новая панель?» Вы получите согласие и ничего не узнаете.
Оценка без уточняющего вопроса. Шесть из десяти говорят о настроении. Что менять, они не говорят.
Спросить и замолчать. Это стоит вам следующего раунда, о чём ниже.

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

Обратную связь о продукте обычно называют отзывами о продукте, и она делится на два вида. Сообщение об ошибке говорит, что что-то работает не так, как задумано. Запрос на функцию говорит, что чего-то не хватает. От различия зависит, кто посмотрит первым, и эту границу проводит статья запрос на функцию или ошибка. Третий вид, похвала, стоит сохранять и цитировать с разрешения.

Форма обратной связи, которая первым выбором предлагает «Ошибка» и «Запрос на функцию», делает эту первую сортировку за вас.

Что делать с ответами?

Складывайте каждый ответ туда, где команда уже работает, сохраняя слова человека. Одна строка цитаты лучше вашего пересказа. Пометьте её типом и примерной срочностью, объедините повторы и решите: делать, отложить или отказать.

Отказ тоже ответ. «Мы не будем это делать, и вот почему» заканчивает ожидание, а формулировки для него есть в статье отказ в запросах на функции. Про техническую сторону рассказывает отслеживание запросов на функции: как собрать запросы из пяти каналов в один список. Если вы принимаете запросы в письменном виде, шаблон запроса на функцию делает их сопоставимыми.

Виджет Changeloop заводит каждое обращение как GitHub issue, так что отзыв попадает рядом с кодом, который его исправит. С любым инструментом правило одно: один список, один владелец, ни одного ответа, забытого во входящих у кого-то в почте.

Зачем рассказывать о выпущенном?

Он показывает человеку, что ответ стоил его времени. Пользователь, который вам что-то сказал, а потом услышал «это выпущено, спасибо», получает причину ответить снова. Тот, кто не услышал ничего, делает вывод, что поле никто не читает.

Поэтому последний шаг в просьбе об обратной связи это ответ. Сообщите каждому, кто просил, когда его запрос выпущен, в его терминах и по тому каналу, которым он пользовался. Механизм описан в статье как замкнуть петлю обратной связи клиента: опубликованная запись в changelog запускает сообщение, поэтому автору запроса говорят только тогда, когда изменение уже работает. В Changeloop, если отзыв из виджета стал задачей GitHub, а влитый pull request её закрывает, одобрение записи оставляет комментарий «Shipped» на этой задаче и показывает автору запись в виджете; для задач, заведённых вручную, и для репозиториев GitLab или Bitbucket комментарий не оставляется. Наша документация описывает настройку виджета и ленты.

Ответ может быть коротким: «Вы просили импорт CSV в марте. Сегодня он готов, вот как он работает». Он же даёт лучший следующий вопрос: закрывает ли это то, что было нужно.

С чего начать

Выберите один момент из таблицы в начале, тот, где пользователи чаще всего добиваются цели или сдаются. Напишите для него один вопрос, поставьте его в один канал и две недели читайте каждый ответ, прежде чем добавлять второй. Отвечайте всем, кто дал вам что-то конкретное.

FAQ

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

Как просить обратную связь, не раздражая пользователей? Спрашивайте после задачи, а не посреди неё, ограничьтесь одним вопросом и дайте возможность легко отказаться. Уважайте отказ несколько недель.

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

Что делать, если никто не отвечает? Сузьте вопрос и приблизьте его к моменту, например один экран, вопрос сразу после его использования. Если тишина остаётся, напишите нескольким пользователям лично и используйте эти разговоры, чтобы составить вопросы получше.

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

Fri, 02 Oct 2026 00:00:00 GMT

Примеры product roadmap, которые стоит брать за образец, делятся на шесть форматов: Now/Next/Later, квартальный график, тематический roadmap, roadmap по результатам, публичный roadmap и внутренний релизный roadmap. Каждый отвечает на свой вопрос для своего читателя, поэтому подходящий пример тот, что совпадает с вашим читателем. Внешний вид выбирается в последнюю очередь.

Все примеры ниже относятся к выдуманному продукту, небольшому приложению для задач в команде, и все пункты придуманы. Важна форма: что стоит в каждой ячейке, как выглядит настоящая запись и из-за чего формат ломается через квартал.

Какие бывают хорошие примеры product roadmap?

Хороший пример roadmap короткий, адресован конкретному читателю и даёт обещание одного рода. Формат выбирают по тому обещанию, которое вы готовы выполнить: направление, дата, тема работ, результат, публичное обязательство или график поставки.

Формат	Для кого	Работает, когда	Ломается, когда
Now/Next/Later	Вся компания	Планы часто меняются	«Next» разрастается и превращается в очередь
Квартальный график	Продажи, поддержка, руководство	Даты действительно жёсткие	Даты сдвигаются, а их никто не обновляет
Тематический	Руководство, новички	Нужно объяснить, зачем это делается	Темы так широки, что подходит любой пункт
По результатам	Продукт и разработка	Цель можно измерить	У метрики нет владельца или данных
Публичный	Клиенты	Его удаётся держать небольшим	Он превращается в свалку бэклога
Внутренний релизный	Разработка, QA, поддержка	Несколько команд выпускают вместе	Его принимают за стратегию

Как выглядит каждый пример product roadmap?

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

Now/Next/Later

NOW (делаем в этом месяце)
  Сохранённые виды во входящих
  Экспорт CSV, который работает на больших аккаунтах
NEXT (решено, порядок не зафиксирован)
  SSO для плана Team
  Уведомления в Slack
LATER (направление, без обязательств)
  Мобильное приложение
  Журнал аудита

Этот формат подходит компании, которая не хочет обещать даты, а так живут многие команды на ранней стадии. Он держится потому, что три колонки описывают степень уверенности: «now» в работе, «next» решено, «later» надежда. Он ломается, когда «later» становится местом, куда складывают все идеи, которые жалко отклонить, и когда у «next» незаметно появляются порядок и дата, хотя вслух это никто не называет графиком.

Временная шкала, или квартальный roadmap

Q4 2026
  Окт   Сохранённые виды во входящих
  Ноя   SSO в бете с пятью партнёрами
  Дек   SSO, общий доступ
Q1 2027
  Янв   Уведомления в Slack
  Мар   Журнал аудита (только экспорт)

Он подходит продажам, поддержке и финансам, которым нужно во что-то упираться при планировании. Работает, когда даты действительно жёсткие: контракт, конференция, срок по комплаенсу. Ломается, когда даты взяты с потолка, потому что месяц в roadmap через несколько недель превращается в обещание в презентации отдела продаж. Если вы выбрали этот формат, помечайте каждый квартал как «обязательство» или «прогноз» и делайте второй квартал заметно менее определённым, чем первый.

Тематический roadmap

ТЕМА: Первая неделя в продукте
  Импорт из CSV и Trello
  Стартовые шаблоны
ТЕМА: Готовность к большим командам
  SSO
  Журнал аудита
  Права по ролям
ТЕМА: Меньше ручных действий
  Уведомления в Slack
  Повторяющиеся задачи

Подходит для отчётов руководству и для новых сотрудников, потому что сначала объясняет, зачем нужна работа, и только потом перечисляет её. Держится, когда каждая тема соответствует причине, по которой клиенту это важно. Ломается, когда темы слишком широкие («Рост», «Качество»), так что любой пункт подходит под любую из них, и тогда группировка ничего не объясняет.

Roadmap по результатам

ЦЕЛЬ: Больше новых команд завершают настройку
  Метрика: настройка за 7 дней, с 40% до 55%
  Ставки: импорт из CSV, стартовые шаблоны
ЦЕЛЬ: Меньше обращений по экспорту
  Метрика: обращений по экспорту в неделю, с 30 до 10
  Ставки: починка экспорта на больших аккаунтах,
  страница статуса экспорта

Цифры условные, а важна раскладка: цель, одна метрика с исходным и целевым значением и ставки, которые вы собираетесь проверить. Формат подходит командам продукта и разработки, которым доверяют выбор решения. Работает, когда метрика существует и у неё есть владелец. Ломается, когда цель нельзя измерить или когда «ставки» остаются прежним списком функций, к которому сверху приклеили предложение про результат.

Публичный roadmap для клиентов

ПЛАНИРУЕМ
  Сохранённые виды во входящих
В РАБОТЕ
  Уведомления в Slack
ВЫПУЩЕНО
  Экспорт CSV для больших аккаунтов

Это самый маленький формат и самое сильное обещание. Он подходит клиентам, которые хотят знать, услышали ли их запрос. Держится при очень малом числе пунктов, без дат и с названиями словами клиента. Ломается, когда превращается в свалку бэклога: каждое «может быть» в списке это обещание, о котором кто-нибудь спросит позже. Как вести такой roadmap из трекера задач, описано в статье публичная roadmap в трёх колонках, поэтому здесь это не повторяется.

Внутренний релизный roadmap

Релиз	Срок	Владелец	Зависит от	Статус
5.2	14 окт	Платформа	Обновление сервиса авторизации	Код готов
5.3	11 ноя	Входящие	API сохранённых видов	В работе
5.4	9 дек	Платформа	Контракт с поставщиком SSO	Заблокирован

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

Какой формат product roadmap выбрать?

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

Клиенты спрашивают: «вы меня услышали?» Берите публичный формат и ограничьтесь горсткой пунктов.
Продажи и поддержка спрашивают: «можно назвать клиенту дату?» Берите квартальный график, где обязательства и прогнозы чётко разделены.
Руководство спрашивает: «зачем эта работа?» Берите темы, а если есть данные, то результаты.
Команда меняет направление каждый месяц. Берите Now/Next/Later и не ставьте дат.
Инженеры спрашивают: «что и когда выходит?» Берите релизный roadmap и держите его отдельно от стратегического.

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

Как составить product roadmap?

Составляйте roadmap так: назовите читателя, выберите формат под его вопрос, внесите только пункты, которые вы готовы защищать на встрече, и дайте каждому статус и владельца. Затем решите, как часто его будут пересматривать, прежде чем публиковать.

Назовите читателя и решение. «Поддержка решает, что говорить клиентам про SSO» это причина. «Все должны видеть roadmap» не даёт ничего, под что можно проектировать.
Начните с того, что уже знаете. Открытые запросы, упорядоченные по понятному правилу, лучший материал, чем мозговой штурм.
Пишите каждый пункт как результат для клиента. «Сохранять фильтр, которым пользуешься часто» читается лучше, чем «Реализовать сохранение состояния видов», и сразу показывает клиенту, его ли это проблема.
Решите, чего в roadmap не будет. Обычно это даты, оценки и склад идей.
Назначьте дату пересмотра. У roadmap без запланированного пересмотра есть незапланированные похороны.

Как поддерживать product roadmap в актуальном состоянии?

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

Самый дешёвый источник правды это трекер задач. Если каждая колонка roadmap соответствует метке на задаче, roadmap меняется вместе с меткой, и ничего не набирается заново. В Changeloop это устроено через метки roadmap:planned, roadmap:building и roadmap:shipped, а когда на задаче две метки, побеждает самая продвинутая. Перенос карточки в «выпущено» остаётся отдельной сменой метки, поэтому сделайте его частью проверки, на которой вы одобряете запись в changelog.

Эта запись вторая половина дела. Когда пункт выпущен, changelog описывает изменение в терминах клиента, а тому, кто просил об этом, можно сообщить. Замкнуть эту петлю и есть смысл петли обратной связи клиента, а roadmap это отрезок этой петли, который клиент видит до того, как что-либо выпущено. Если вы отказались от пункта, скажите об этом; публичное «нет» закрывает и этот запрос, а как его сформулировать, описано в статье отказ в запросах на функции. Тем, кто хочет увидеть, как читаются готовые записи, пригодятся примеры changelog.

FAQ

Какой формат product roadmap самый простой? Now/Next/Later. В нём три колонки, не нужны даты, а пункты группируются по степени уверенности. Для небольшой команды, которая часто меняет направление, в нём ещё и труднее всего опозориться.

Сколько пунктов должно быть в product roadmap? Меньше, чем вам кажется. Публичному roadmap хватает менее десяти пунктов на все колонки, а внутреннему стратегическому редко нужно больше дюжины. Сверх этого получается бэклог с красивым заголовком.

Нужно ли указывать даты в product roadmap? Только если даты действительно жёсткие, и то лишь для ближайшего квартала. Дальше используйте колонки или темы. Дата в roadmap становится обязательством в разговоре с продажами, хотите вы этого или нет.

Чем product roadmap отличается от плана релизов? Roadmap говорит, что вы собираетесь строить и зачем. План релизов говорит, какая сборка выходит в какую дату и кто за неё отвечает. Roadmap меняется, когда меняется стратегия, а план релизов меняется, когда меняется работа.

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

Fri, 02 Oct 2026 00:00:00 GMT

Процесс управления релизами это набор шагов, который доводит изменение от состояния «влито» до состояния «работает в продакшене и объяснено тем, кого оно касается». Для команды, которая выпускает часто, он сводится к семи шагам: спланировать объём, изолировать изменение, собрать и протестировать, одобрить, выкатить и проверить, сообщить и разобрать итоги. У каждого шага должен быть один названный владелец и один критерий выхода, иначе шаг тихо перестаёт выполняться.

Это руководство рассчитано на команду из 5-50 инженеров, которая выкатывает раз в неделю или каждый день и хочет, чтобы процесс не мешал.

Шаг	Владелец	Критерий выхода
1. Спланировать объём	Продакт или техлид	Список изменений в этом релизе записан, рискованное отмечено
2. Ветка или флаг	Инженер, которому принадлежит изменение	Работа в короткоживущей ветке или за флагом, так что main остаётся готовым к выпуску
3. Сборка и тесты	CI, автор на связи при сбоях	Пайплайн зелёный на том самом коммите, который пойдёт в релиз
4. Одобрение	Ревьюер, а для рискованных изменений ещё и релиз-менеджер	Ревью пройдено, путь отката назван, решение «go» или «no-go» записано
5. Выкатка и проверка	Релиз-менеджер или дежурный инженер	Выкачено, smoke-проверки проходят, доля ошибок и задержка совпадают с уровнем до релиза
6. Сообщить	Тот, кто понимает изменение, с правкой от того, кто не понимает	Release notes опубликованы там, где их читают пользователи, поддержка и продажи в курсе
7. Разбор итогов	Релиз-менеджер	Метрики прочитаны, у всего, что пошло не так, есть владелец и исправление

Что такое процесс управления релизами?

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

Какие бывают типы управления релизами?

Есть три практических типа: непрерывная выкатка, релизы по расписанию и регулируемое управление изменениями. Они различаются тем, сколько происходит до релиза и сколько автоматизировано. Непрерывная выкатка выпускает каждое влитое изменение, релизы по расписанию собирают изменения в «поезд», а регулируемое управление изменениями добавляет формальное одобрение и журнал для аудита.

	Непрерывная выкатка	Релизы по расписанию	Регулируемое управление изменениями (ITIL)
Единица релиза	Один влитый pull request	Пакет, раз в неделю или две	Запрос на изменение
Шаг объёма	Неявный, объём это слияние	Встреча по планированию релиза	Запись об изменении с оценкой риска
Одобрение	Ревью кода и автоматические проверки	Релиз-менеджер подписывает пакет	Совет по изменениям или делегированный утверждающий
Контроль риска	Флаги функций, канарейки, быстрый откат	Выдержка на стенде, релиз-кандидат	Задокументированный план отката, окно обслуживания
Обычный ритм	Много раз в день	От раза в неделю до раза в месяц	Задаётся календарём изменений
Слабое место	Никто не говорит пользователям, что изменилось	Большие пакеты прячут изменение, которое всё сломало	Время на процесс превышает время самого изменения

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

Какие обязанности у релиз-менеджера?

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

Перед релизом он подтверждает объём и проверяет, что у каждого рискованного изменения есть путь отката. Во время релиза проходит по чек-листу выкатки, следит за метриками продакшена в первые минуты и откатывает без промедления. После релиза убеждается, что заметки вышли, и записывает, что исправить в процессе.

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

Какие ключевые KPI у управления релизами?

Отслеживайте метрики доставки ПО DORA и добавьте одну свою: сколько времени проходит, прежде чем пользователям сообщат. Исследование DORA выделяет пять метрик, разделённых на пропускную способность (время изменения до выкатки, частота выкатки, время восстановления после неудачной выкатки) и нестабильность (доля неудачных изменений, доля доработок после выкатки).

Руководство DORA определяет их простыми словами (dora.dev, software delivery metrics):

KPI	Что измеряет	На что смотреть
Время изменения (change lead time)	Время от коммита в системе контроля версий до выкатки в продакшен	Рост обычно означает очереди на ревью или одобрение
Частота выкатки	Как часто вы выкатываете или сколько проходит между выкатками	Падение частоты значит, что пакеты растут
Время восстановления после неудачной выкатки	Время восстановления после выкатки, которая требует немедленного вмешательства	Здесь видны проблемы с откатом и алертами
Доля неудачных изменений	Доля выкаток, которым нужен откат или хотфикс	Растёт, когда пакеты слишком велики или тестов мало
Доля доработок после выкатки	Доля незапланированных выкаток, вызванных инцидентом в продакшене	Признак того, что исправления выходят быстрее, чем усваиваются уроки
Время до уведомления пользователей	Минуты от выкатки в продакшен до опубликованной пользовательской заметки	Измеряйте сами, ни один фреймворк этого не даёт

В более старых материалах говорится о четырёх ключевых метриках, а восстановление называется «time to restore». В нынешнем руководстве используются пять метрик выше.

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

Как коммуникация о релизе вписывается в процесс управления релизами?

Это шаг шесть, и у него, как у любого другого, есть владелец и критерий выхода: заметки опубликованы там, где их читают пользователи, и внутренние команды в курсе. Чаще всего этот шаг пропускают, потому что инструменты выкатки сообщают об успехе в тот момент, когда код уже работает.

Самый дешёвый способ держать этот шаг в графике: писать запись, когда изменение вливается, а не когда релиз выходит. В pull request уже есть заголовок, автор, связанная задача и контекст. Черновик, собранный из него, правят, а не пишут по памяти неделю спустя. На этом строится идея автоматизации changelog: получить черновик при слиянии, удержать его до одобрения человеком и опубликовать везде из одного источника. Changeloop работает именно так: составляет записи из влитых pull request с помощью ИИ и удерживает их до одобрения, прежде чем что-либо публикуется.

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

Как сохранить процесс лёгким?

Автоматизируйте каждый критерий выхода, который может проверить машина, а людям оставьте суждения. Зелёный пайплайн, отметка выкатки на дашбордах и черновик записи в changelog на каждый влитый pull request проверяются машиной. Убедителен ли план отката и понятны ли заметки клиенту, решает человек.

Чтобы проверить процесс, возьмите релиз прошлого месяца и спросите, мог ли человек вне команды по одной только письменной записи понять, что выпущено, кто одобрил, как проверено и когда пользователям сообщили. Любой пробел это ваше следующее улучшение.

FAQ

Чем управление релизами отличается от управления изменениями? Управление релизами собирает, тестирует, выкатывает и объявляет набор изменений. Управление изменениями в смысле ITIL это процесс одобрения и оценки риска вокруг каждого изменения. Команды, которые выпускают часто, вносят одобрение в ревью кода и автоматические проверки.

Как часто нужно выпускать релизы? Так часто, как позволяют ваши тесты и путь отката, а для многих веб-команд это ежедневно и чаще. Совет DORA: уменьшать размер каждого изменения, потому что мелкие изменения легче проверять и откатывать.

Нужен ли небольшим командам релиз-менеджер? Им нужны обязанности, но не обязательно должность. Меняйте роль между инженерами, дайте дежурному письменный чек-лист и убедитесь, что у каждого из семи шагов есть владелец.

Что должен включать чек-лист релиза? Подтверждённый объём, зелёный пайплайн на выпускаемом коммите, названный путь отката, записанное одобрение, smoke-проверки после выкатки, сравнение метрик с исходным уровнем, опубликованные release notes, уведомлённая поддержка и назначенный разбор. Умещайте на одной странице.

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

Fri, 02 Oct 2026 00:00:00 GMT

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

Все примеры выдуманы, для вымышленного приложения для выставления счетов Tidepool.

Что общего у хороших примеров release notes?

Они говорят пользователям, что изменилось и что им с этим делать, если нужно что-то делать, и говорят это словами пользователей. У каждого вида изменений своя задача, поэтому форма записи от вида к виду меняется.

Вид изменения	Запись должна сказать	Где размещать
Новая функция	Что читатель теперь может и у кого это есть	Начало заметок
Улучшение	Что стало быстрее или проще, с цифрой, если она есть	После функций
Исправление бага	Симптом, который видел читатель, и что он исправлен	После улучшений
Breaking change	Кого касается, дата, миграция	Всегда первым
Исправление уязвимости	Что было открыто, использовали ли это, что делать	Первым
Депрекация	Что исчезает, дата окончания, замена	Ближе к началу
Заметка в сторе	Одно простое предложение на изменение, в пределах лимита символов	Страница в сторе
Внутренняя заметка	Что изменилось и что говорить клиентам	Каналы поддержки и продаж

Как выглядит хорошая заметка о новой функции?

Хорошая заметка о функции начинается с того, что читатель теперь может сделать, и называет планы или роли, которым это доступно. Реализацию она пропускает.

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

Заголовок это фраза, которую читатель сказал бы вслух, а текст даёт охват и место настройки. Читатель, пробежавший глазами только жирную строку, всё равно знает, что выпущено. Общий метод разобран в статье как писать release notes.

Как выглядит хорошая заметка об улучшении?

Заметка об улучшении описывает изменение, которое читатель почувствует, и ставит измеренную цифру, если она есть. Если цифры нет, скажите, что читателю больше не нужно делать.

Список счетов загружается примерно в три раза быстрее. Аккаунты с более чем 5 000 счетов раньше ждали список около девяти секунд. Теперь он открывается примерно за три. Действий не требуется.

«Улучшения производительности» ничего не говорят читателю, а девять секунд против трёх это утверждение, которое он проверит в понедельник утром. Завершающее «Действий не требуется» отвечает на вопрос, который есть у каждого читателя.

Как выглядит хорошая заметка об исправлении бага?

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

Исправлено: напоминания уходили дважды в день оплаты. Некоторые клиенты получали по два одинаковых напоминания, если срок счёта выпадал на последний день месяца. Это исправлено. Уже отправленные напоминания не затронуты, и повторно отправлять ничего не нужно.

Заголовок начинается со слова «Исправлено», чтобы пробегающий глазами мог отсортировать запись с первого взгляда, а настоящее условие (последний день месяца) идёт сразу следом.

Как писать release notes о breaking change?

Заметка о breaking change начинается с даты и затронутой группы, а затем в той же записи даёт миграцию. В release notes она идёт первой, потому что это единственная запись, которую читатель не должен пропустить.

Подписи вебхуков станут обязательными с 1 декабря 2026 года. С этой даты Tidepool перестаёт отправлять неподписанные payload вебхуков. Это касается всех, кто принимает вебхуки без проверки заголовка Tidepool-Signature. Для миграции проверяйте заголовок с помощью секрета в разделе «Настройки, Разработчикам». Если вы уже проверяете подписи, действий не требуется.

Дата стоит в заголовке, поэтому переживает беглое чтение. Затронутая группа названа по тому, что она делает, а последнее предложение отпускает тех, у кого всё в порядке, и это снижает нагрузку на поддержку. Руководство по breaking changes объясняет, как решить, считается ли изменение таковым.

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

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

Безопасность: ссылки для сброса пароля можно было использовать повторно. С 3 по 17 сентября 2026 года ссылка для сброса пароля оставалась действительной после первого использования. Признаков того, что этим пользовались, мы не нашли. Это исправлено, а все неиспользованные ссылки аннулированы. Если вы запрашивали сброс в этот период, запросите новую ссылку.

Точный период позволяет читателю оценить собственный риск, а фраза об использовании отвечает на первый вопрос, который задаёт любой. «Потенциальная проблема» выглядит как сокрытие, поэтому пишите то, что вам известно.

Как написать уведомление о депрекации?

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

Endpoint счетов v1 объявлен устаревшим и перестанет работать 1 марта 2027 года. GET /v1/invoices продолжает работать до 1 марта 2027 года, после чего будет возвращать 410 Gone. Используйте GET /v2/invoices, который возвращает те же поля плюс currency. Ответы v1 теперь содержат заголовок Sunset с датой окончания. Руководство по миграции с примерами рядом есть в документации.

Название endpoint стоит в заголовке, потому что те, кого это касается, ищут именно его, а замена стоит рядом с удалением. Заголовок Sunset показывает разработчикам, какие вызовы всё ещё идут на старую версию. Более подробно это разобрано в статье депрекация API.

Как выглядит заметка о релизе в сторе приложений?

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

Сфотографируйте бумажный чек, и Tidepool сам заполнит сумму, дату и поставщика. Тёмная тема теперь следует настройке телефона. Ещё мы исправили падение при открытии счёта из уведомления.

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

Что должна включать внутренняя заметка о релизе?

Внутренняя заметка это версия для поддержки и продаж. Она добавляет то, что публичная заметка опускает: что говорить и что не обещать.

Счета на нескольких языках выпущены сегодня (все планы). Поддержка: клиенты задают язык в «Настройках оплаты», а уже выставленные счета сохраняют исходный язык. Итальянского пока нет. Продажи: функция открыта на всех планах, так что не подавайте её как повод для апгрейда.

У каждой аудитории своя подписанная строка, а заметка проводит границу («Итальянского пока нет») раньше, чем клиент спросит. Формат и каналы разобраны в статье внутренние release notes.

Как выглядит плохая заметка о релизе после переписывания?

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

До:

v3.8.1 Рефакторинг планировщика напоминаний. Исправлено состояние гонки в ReminderJob. Обновлён bull до 4.12. Прочие улучшения.

После:

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

Также в 3.8.1: bull обновлён до 4.12.

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

Как сохранять единообразие release notes от релиза к релизу?

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

Changeloop работает именно так: он составляет запись из каждого влитого pull request с помощью ИИ и удерживает её до одобрения человеком. На шаге одобрения редактор применяет правила выше. Чтобы сначала определиться с форматом, начните с шаблона release notes, а как выглядят готовые страницы, смотрите в примерах changelog.

FAQ

Что такое новые release notes? Новые release notes это сообщение, которое публикуется вместе с последним релизом продукта и описывает, что изменилось и что нужно сделать пользователям. Они охватывают функции, улучшения, исправления и breaking changes.

Чем release note отличается от changelog? Changelog хранит всё, для всех, кому нужна вся история. Release note выбирает из него: один релиз, написанный для читателей, которые решают, важен ли он им. Полное сравнение есть в статье changelog vs release notes.

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

Какой длины должна быть каждая запись в release notes? Для большинства записей хватает двух-четырёх предложений: результат, кого это касается и что делать. Breaking change или исправление уязвимости могут быть длиннее, потому что им нужны дата или миграция.

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

Fri, 02 Oct 2026 00:00:00 GMT

Версионирование API Stripe устроено по датам. Каждый аккаунт привязан к версии API, названной по дате релиза, а любой отдельный запрос может переопределить эту привязку заголовком Stripe-Version. На момент написания (октябрь 2026 года) текущая версия в документации Stripe это 2026-09-30.endive, и ту же схему гораздо меньший API может повторить за выходные.

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

Механизм	Что делает Stripe	Источник
Название версии	Дата, а с 2024 года ещё и название релиза (`2026-09-30.endive`)	Versioning
Версия по умолчанию	Закреплена за аккаунтом, меняется в Workbench	Versioning
Переопределение в запросе	Заголовок `Stripe-Version` или параметр SDK	Upgrades
Вебхуки	Формируются в версии, заданной для endpoint	Upgrades
Ритм	Ежемесячные релизы без breaking changes, мажорный релиз дважды в год	Versioning
Старые версии	Продолжают работать благодаря внутренним модулям изменения версии	Engineering post

Как работает версионирование API Stripe?

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

В инженерной статье Stripe сказано, что аккаунт закрепляется при первом запросе к API: он «автоматически закрепляется за самой свежей доступной версией», и с тех пор каждому вызову неявно присваивается эта версия.

Строка версии это дата. Начиная с релиза 2024-09-30.acacia в ней есть ещё и название, как в 2026-09-30.endive. Дата упорядочивает версии, а название показывает, к какому семейству мажорных релизов версия относится.

Как выбрать версию для отдельного запроса?

Отправьте в запросе заголовок Stripe-Version или задайте версию в SDK. Руководство Stripe по обновлению показывает форму с заголовком, и тот же вызов работает и в боевой, и в тестовой среде.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

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

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

SDK закрепляют версию по-разному в зависимости от языка. В документации сказано, что свежие версии библиотек для динамически типизированных языков используют ту версию API, которая была последней на момент выхода релиза SDK, а строго типизированные (Java, Go и .NET) жёстко к ней привязаны. Установить версию библиотеки значит, по сути, выбрать версию API.

Что происходит с вебхуками при смене версии?

Событие вебхука формируется в версии API, привязанной к его endpoint, а не в той, которую использует код вашего сервера. В документации Stripe сказано, что события используют версию, заданную при создании endpoint, а если её нет, то версию аккаунта по умолчанию. Смена версии SDK не меняет то, что получает ваш обработчик вебхуков.

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

Путь обновления у Stripe для этого такой: параллельный запуск. Создайте новый endpoint с целевой версией, отправляйте одни и те же события на оба, научите обработчик обрабатывать один и игнорировать другой, затем переключитесь и отключите старый endpoint. Поскольку в период перекрытия каждое событие приходит дважды, обработчик должен быть идемпотентным. Это хороший приём для любого API, которое рассылает события, а changelog вебхуков это место, где вы объявляете изменения payload, делающие его необходимым.

Что такое ежемесячные и мажорные релизы?

Начиная с релиза 2024-09-30.acacia Stripe выпускает новую версию API ежемесячно без breaking changes и дважды в год выпускает новый мажорный релиз, который начинается с версии с breaking changes. На странице версионирования сказано, что перейти на любой ежемесячный релиз можно без изменения кода, а мажорный релиз может потребовать правок.

У мажорных релизов есть названия. Страница версионирования приводит пример Basil, а в анонсе процесса Stripe сказано, что названия берутся из растений, начиная с Acacia, и что ежемесячные релизы сохраняют название предшествующего мажорного, чтобы название сигнализировало: на них безопасно переходить. В changelog Stripe перечислены используемые названия, и на момент написания самая новая запись это 2026-09-30.endive.

Так что дата отвечает на вопрос «насколько свежая», а название на вопрос «это граница breaking changes?». Анонс Stripe оставляет место и для исключений: компания оставляет за собой право выпустить внеплановое breaking change, если без него интеграция серьёзно пострадает. Анонс находится по адресу Stripe's new API release process.

Какая последняя версия API Stripe?

На момент написания (октябрь 2026 года) на странице версионирования Stripe указано, что текущая версия это 2026-09-30.endive, и в его changelog та же версия значится самой новой. Stripe публикует новую версию ежемесячно, поэтому любая строка в статье быстро стареет. Прочитайте живой changelog, прежде чем что-то закреплять, и закрепляйте ту версию, на которой тестировали.

Как Stripe сохраняет работу старых версий?

Stripe держит старые версии живыми, записывая каждое breaking change как самостоятельный модуль изменения версии и применяя модули в обратном порядке, от самой новой формы данных. Механизм описан в инженерной статье о версионировании API.

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

Из такой конструкции вытекают два побочных эффекта, и оба названы в статье. Поскольку модули объявляют поля и ресурсы, которых касаются, Stripe может генерировать свой changelog API из них при деплое. А поскольку версия аккаунта известна, документация может подстраиваться под неё и предупреждать об обратно несовместимых изменениях, появившихся с этой версии.

Чего это стоит и что взять небольшому API?

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

Небольшой API не может позволить себе цепочку модулей на каждую старую версию и не нуждается в ней. Берите части, в которых вся ценность:

Версии с датой. Дате не нужно суждение о том, что считать «мажорным», и вызывающие её читают. Статья лучшие практики версионирования API сравнивает это со схемами через URL и заголовок.
Закреплённая версия по умолчанию. Закрепите аккаунт или ключ за версией при первом использовании, чтобы API никогда не менялось под работающей интеграцией.
Переопределение в запросе. Заголовок, позволяющий вызывающему проверить новую версию на одном вызове, в боевой среде, до того как переходить.
Версия на endpoint вебхука. Payload событий это то место, где вызывающих чаще всего ждёт сюрприз.
Одна запись changelog на версию. Пусть в ней будут версия, дата, кого это касается и что делать. Что считается breaking это проверка того, что вообще принадлежит новой версии, а саму запись разбирает статья changelog API.

Цепочку модулей пропустите, пока число поддерживаемых версий этого не потребует. Две-три живые версии можно держать несколькими ветвлениями и датой sunset, о чём рассказывает статья вывод версии API из эксплуатации.

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

FAQ

Какая последняя версия API Stripe? На момент написания (октябрь 2026 года) на странице версионирования Stripe указано, что текущая версия это 2026-09-30.endive. Stripe выпускает новую версию ежемесячно, так что проверьте его changelog перед закреплением и впишите версию в код, а не полагайтесь на версию аккаунта по умолчанию.

Как задать версию API Stripe в запросе? Отправьте заголовок Stripe-Version, например Stripe-Version: 2026-09-30.endive, или задайте версию в серверном SDK глобально либо для запроса. Без того и другого запрос использует версию вашего аккаунта по умолчанию, которую вы задаёте в Workbench.

Используют ли вебхуки ту же версию API Stripe, что и мои запросы? Не обязательно. События вебхуков используют версию, заданную при создании endpoint, а если её нет, версию аккаунта по умолчанию. Обновление SDK не меняет payload, который получает ваш обработчик, поэтому обновляйте endpoint отдельно и тестируйте их параллельно.

Подходит ли небольшому API версионирование по датам в стиле Stripe? Версии с датой, закреплённая версия по умолчанию, заголовок в запросе и одна запись changelog на версию дёшевы и их стоит перенять. Внутренняя цепочка модулей изменения версии не стоит усилий, пока вы не поддерживаете много старых версий одновременно. Начните с двух живых версий и даты sunset для старшей.

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

Tue, 22 Sep 2026 00:00:00 GMT

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

Почему автор PR не автоматически лучший автор changelog?

Потому что он знает реализацию, не обязательно влияние, а это разные виды знания. Где останавливаются conventional commits разбирает этот разрыв со стороны сообщения коммита: fix(auth): reject expired refresh tokens корректно и не говорит клиентке ничего, а тот, кто написал это исправление, часто наименее готов его перевести, потому что думал в терминах бага часами и потерял внешний взгляд на то, что на самом деле испытала пользовательница. Та же причина, по которой технические писательницы существуют как профессия: перевод реализации в её влияние — отдельный навык от того, чтобы построить саму вещь, и он требует практики независимо от того, насколько разработчик хорош в самом коде.

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

Нет, потому что у них противоположный разрыв: они знают, что важно пользовательницам, но не всегда что на самом деле было выпущено, что производит записи читаемые, но иногда неверные по охвату, утверждение «теперь поддерживает X» для функции, всё ещё скрытой за флагом, или исправление, описанное как полное, когда покрывает только один из трёх случаев. Режим сбоя записей, написанных разработчицами, — нечитаемо-но-точно; режим сбоя записей, написанных PM-ками, — читаемо-но-непроверено. Ни одна роль не владеет обеими половинами того, что нужно хорошей записи.

Роль	Обычно точна в	Обычно ошибается в
Разработчица, написавшая код	Точный охват изменения	Формулировке для того, кто это не строил
PM или лидер поддержки	Почему это важно пользовательнице	Точных границах того, что реально выпущено
Выделенная владелица changelog	Согласованном голосе, сверяет охват	Нужны обе роли выше, чтобы было с чем сверять

Как на самом деле выглядит рабочая модель ответственности?

Черновик от того, кто ближе всего к изменению, проверенный тем, кто ближе всего к пользовательнице, с одним названным человеком, ответственным за финальную формулировку, вместо того чтобы все предполагали, что кто-то другой поймает проблемы. Черновику важнее существовать и быть точным, чем быть хорошим; грубое предложение, написанное разработчицей, которое верно говорит, что изменилось, — лучшая отправная точка, чем отполированное, но непроверенное, потому что переписать ради ясности легче, чем переписать ради правильности. Шаг review — там, где PM или лидер поддержки читает черновик и задаёт единственный вопрос, ловящий разрыв читаемости: поняла бы я это, если бы не видела код.

Должен ли всегда отвечать один и тот же человек, или это ротируется?

Названная и стабильная роль побеждает ротирующуюся, по крайней мере для финального одобрения. Ротирующаяся владелица означает, что каждую запись проверяет кто-то, заново выводящий соглашения команды с нуля, что ровно то, как голос дрейфует от записи к записи, и читательница начинает замечать, что changelog написан комитетом. Один человек, или очень маленькая стабильная группа, накапливает суждения со временем, когда говорить «улучшено» против называть конкретное число, когда исправлению нужна собственная запись против сворачивания в пакет, и это суждение стоит больше, чем равномерное распределение работы.

Черновик (разработчица, из PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Проверено (владелица changelog, сверено с реальным PR):
"Исправлено: экспорт, отсортированный по дате, мог
возвращать результаты не по порядку после первой
страницы. Теперь согласовано на всех страницах."

Нужно ли маленькой команде столько процесса ради одной строки текста?

Не роли как отдельные люди, но два шага всё равно важны даже соло. Команда из одного человека — и разработчица, и ревьюер одновременно, и дисциплина, выживающая на таком масштабе, — делать review отдельным ментальным проходом, не прыгая прямо от написания исправления к публикации его описания на одном дыхании. Ловушка на малом масштабе — в полном пропуске второго прохода, а не в отсутствии второго человека, потому что никто извне его не требует, а разрыв точности, который этот проход призван поймать, не исчезает только потому, что тот же человек теоретически мог бы заметить собственное слепое пятно.

Что происходит, когда никто не отвечает за финальную запись?

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

FAQ

Должна ли владелица changelog быть инженерной ролью или продуктовой? Любая может работать, если у человека есть и техническая беглость, чтобы проверять охват, и достаточная дистанция от реализации, чтобы писать для внешней читательницы; должность важна меньше, чем то, может ли она делать обе половины, или знает, у кого спросить о половине, которую не может сделать сама.

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

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

Уменьшает ли автоматизация то, насколько важна ответственность? Она уменьшает объём необходимого письма, а не объём необходимого суждения. Автоматизация changelog разбирает, что pipeline может безопасно генерировать, форматирование, публикацию, кросс-постинг; формулировка, группировка и что считается достойным упоминания остаются человеческими решениями независимо от того, насколько автоматизирован pipeline.

Что если автор PR и ревьюер расходятся во мнении о формулировке? Решает ревьюер, потому что вопрос, на который он отвечает, поймёт ли это внешняя читательница, — именно тот, ради которого существует роль. Это не делает мнение разработчика бесполезным: если разногласие о точности, а не о формулировке, ревьюер уступает, потому что охват — половина автора, за которую отвечает он. Разделение двух видов разногласий, формулировка против точности, останавливает большинство из них до того, как они превратятся в противостояние.

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

Tue, 22 Sep 2026 00:00:00 GMT

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

Что одно должны сделать правильно экстренные release notes, даже если больше ничего?

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

Применимо ли обычное редактирование, когда нет времени его применять?

Инстинкт сжимать сохраняется, даже когда многопроходный процесс, который его обычно производит, — нет. Переписывание описывает урезание многословного первого черновика до его сути; под временным давлением часто нет первого черновика для урезания, что значит дисциплина должна работать в голове по мере написания, а не отдельным шагом после. Самый быстрый подход: напишите предложение, которое произнесли бы вслух тому, кто спрашивает «что мне нужно знать», и остановитесь, потому что это предложение обычно и самое быстрое в производстве, и единственное, которое читательница реально обработает в таком состоянии.

Обычная release note	Экстренная release note
Написана после code review, до публикации	Часто пишется параллельно с исправлением, до полного review
Оптимизирована для лёгкого сканирования множества записей	Оптимизирована для одной записи, читаемой изолированно, под стрессом
Может отложить детали в связанный changelog	Должна поставить один самый важный факт первым
Обрамление и контекст уместны	Обрамление перед пунктом действия читается как проволочка

Бывает ли нормально публиковать заметку до того, как вы действительно уверены в причине проблемы?

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

Слишком уверенно, не проверено:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Честно под давлением времени:
"Исправлено: с некоторых клиентов дважды списывалась
оплата за один заказ. Мы остановили новые случаи и
вернули средства пострадавшим аккаунтам в течение
24 часов. Расследуем первопричину."

Должна ли экстренная заметка упоминать причину проблемы, или только то, что она исправлена?

Скажите, что исправлено и что должна сделать читательница; приберегите первопричину для последующей заметки, когда она реально известна, а не предполагается. Читательница в разгар инцидента хочет ровно два факта: закрыто ли это и затрагивает ли это меня, а объяснение первопричины, даже точное, соревнуется с этими двумя фактами за внимание в худший момент для его потери. Постмортем, опубликованный отдельно по завершении расследования, — вот где должна быть первопричина; смешивание обоих документов под временным давлением производит заметку, которая пишется медленнее и читается медленнее — противоположность тому, что нужно экстренной ситуации.

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

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

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

Опишите исправление и его эффект, а не ошибку, и сдержите порыв извиняться чрезмерно, что читается как наполнитель для читательницы, желающей двух фактов выше. «Мы нашли и исправили баг, затронувший некоторые экспорты» заявляет, что произошло, без добавления к этому драмы; «Нам очень жаль за это серьёзное неудобство, затронувшее наших ценных клиентов» откладывает полезную информацию на целое предложение, чтобы передать эмоциональный момент, о котором читательница не просила. Краткая, фактическая заметка — не холодность, это уважение к реальному состоянию читательницы, которое под настоящим давлением — нетерпение, а не потребность в утешении.

FAQ

Должны ли экстренные release notes проходить тот же процесс review, что и обычные? Более лёгкий, но не никакой: одна быстрая проверка, что заметка не завышает определённость, стоит нескольких минут, которые требует, потому что риск непроверенного технического утверждения оказаться неверным выше именно потому, что оно написано быстро.

Нормально ли публиковать экстренную заметку без ссылки на дальнейшие детали? Только ненадолго. Заметка без ссылки годится как первое, что публикуется; добавьте одну на страницу статуса или последующую заметку, как только любая из них появится, потому что читательнице, желающей больше того единственного предложения, нужно куда пойти, даже если это место говорит «дальнейшие детали скоро».

Должна ли экстренная заметка когда-либо полностью пропускаться, позволяя исправлению выйти тихо? Только для проблем, которые ни одна читательница не могла заметить или которых не затрагивала; если есть шанс, что читательница столкнулась с проблемой, заметка — это то, что сообщает ей, что она закончилась, а тишина читается так, будто проблема всё ещё может быть активной.

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

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

Tue, 22 Sep 2026 00:00:00 GMT

REST API меняется, когда меняется форма JSON, и большая часть этой формы видна в ответе, который можно прочитать в браузере. gRPC API меняется, когда меняется файл .proto, а бинарный формат провода Protocol Buffers имеет собственные правила о том, что может стерпеть клиент, не имеющие никакого отношения к тому, что говорят имена полей. Два изменения, выглядящие одинаково мелкими в диффе, перенумерация поля против добавления нового, попадают по разные стороны черты, которую breaking changes проводит в общем: одно невидимо для каждого существующего клиента, другое ломает их все разом.

Отличить breaking changes Protobuf от безопасных значит читать собственные правила формата провода, а не гадать по тому, как изменение выглядит в диффе .proto.

Почему нумерация полей важнее имени поля в Protobuf?

Потому что формат провода кодирует поля по номеру, а не по имени. Сгенерированный код на каждом языке читает и пишет эти номера; имя поля email в вашем файле .proto — удобство для людей, которое никогда не касается двоичных байтов, отправляемых по сети. Переименование поля, email в email_address, безопасно в двоичном формате провода, пока номер остаётся тем же, что удивляет инженерок, привыкших к REST, где переименованный JSON-ключ — именно тот тип изменения, что ломает клиента. Исключение составляет тот же случай, что и в REST: форматы ProtoJSON и text сериализуют имя, поэтому переименование ломает JSON-транскодирование (например, grpc-gateway), файлы в text-формате и field mask. Перенумерация того же поля, с сохранением имени но изменением 1 на 7, — ровно наоборот: невидимо в code review, показывающем только имена, и портит каждое сообщение, которое клиент отправляет или получает с этого момента.

Изменение	Безопасно на проводе	Почему
Переименовать поле, сохранить номер	В двоичном да, в JSON и text нет	Двоичное кодирование использует номер; ProtoJSON и text-формат используют имя
Изменить номер поля	Нет	Каждое существующее сообщение теперь читается как неверное поле
Добавить новое поле с новым номером	Да	Старые клиенты игнорируют незнакомые им поля
Удалить поле, повторно использовать его старый номер для чего-то другого	Нет	Старые данные декодируются в неверное новое поле
Несовместимо изменить тип поля (напр. `int32` в `string`)	Нет	Кодирование провода отличается по типам

Что делает удаление поля другим, чем то же в ответе REST JSON?

Номер становится радиоактивным. Собственное руководство Protobuf рекомендует помечать номер удалённого поля как reserved, а не позволять его повторное использование, потому что именно в повторном использовании и происходит настоящий ущерб: клиент, всё ещё работающий на сгенерированном коде месячной давности, отправляет сообщение, используя старый номер поля для старого значения, а сервер, теперь ожидающий, что этот номер означает что-то другое, молча неверно интерпретирует данные вместо того, чтобы прямо их отклонить. У REST нет эквивалентной ловушки, потому что удалённый JSON-ключ просто перестаёт появляться; нет способа, чтобы запрос старого клиента был тихо переинтерпретирован как что-то другое. Файл .proto с reserved 4, 9, 12; в начале сообщения — это постоянный шрам, и в этом весь смысл: он не даёт номеру достаться новому полю от того, кто не знал его истории.

message Invoice {
  reserved 4; // было `legacy_customer_id`, удалено 2026-06-01
  reserved "legacy_customer_id"; // и имя тоже, для JSON/text
  string customer_id = 5;
  string status = 6;
}

Требует ли добавление поля вообще записи в changelog?

Обычно не запись о breaking change, но часто обычную, потому что «безопасно на проводе» и «невидимо для читательницы, которой это важно» — два разных утверждения. Добавление поля в сообщение ответа структурно ничего не стоит, старые клиенты декодируют сообщение и автоматически игнорируют новое поле. Но у того, кто строит новую интеграцию против этого сервиса, нет способа узнать, что поле существует, если кто-то ему не скажет, потому что ничто в успешной сборке или пройденном тесте не делает новое опциональное поле видимым. Changelog API разбирает в общем, чем аддитивная запись обязана читателям; специфичная для gRPC причина всё же её написать в том, что нет эквивалента просмотру ответа REST в отладчике, чтобы заметить появление нового ключа.

Чем это отличается от того, с чем сталкиваются вызывающие GraphQL?

Правила для добавлений совпадают, но степень видимости разная. Депрекация схемы GraphQL разбирает модель, где клиент получает только те поля, которые явно запрашивает, что делает аддитивные изменения по сути безрисковыми, а удаления — единственной реальной опасностью. Клиенты gRPC, напротив, получают всё, что отправляет сервер, и декодируют всё против собственной скомпилированной копии схемы; экспозиция клиента ограничена не тем, что он запросил, а только тем, что умеет читать его сгенерированный код. Эта разница важна для написания changelog: запись GraphQL может разумно предполагать, что клиенты защищены от полей, которые они не запрашивали, а запись gRPC не может предполагать это вовсе.

Работает ли версионирование сервиса gRPC так же, как `/v1/`, `/v2/` в REST?

Механизм отличается, даже когда намерение то же. Что такое v1 и v2 в REST API разбирает версионирование как параллельные пути URL, обслуживающие разные контракты; сервисы gRPC обычно версионируются через имя пакета в самом файле .proto, payments.v1.InvoiceService становится payments.v2.InvoiceService, что меняет полностью квалифицированное имя сервиса, которое набирает клиент, вместо сегмента URL, который он запрашивает. Оба подхода решают одну и ту же проблему, позволяя старому контракту продолжать работать, пока существует новый, но команда с бэкграундом REST часто ищет номер версии не в том месте и упускает, что эту работу выполняет объявление пакета.

Что на самом деле должна называть запись changelog gRPC?

Сообщение, номер поля, и является ли изменение аддитивным или удалением, требующим миграции, в этом порядке важности для читательницы, решающей, действовать ли. «Добавлено shipping_address (поле 8) в Order» говорит интегратору всё необходимое, чтобы обновить сгенерированный код и начать его использовать. «Зарезервировано поле 4 в Invoice, legacy_customer_id исчезло» говорит ей проверить, не читает ли что-то в её кодовой базе всё ещё это поле, что заметка в стиле REST «удалено поле из ответа» не сообщает с той же срочностью, потому что удаления REST просто возвращают меньше данных, а повторное использование полей Protobuf активно их портит.

FAQ

Может ли тип поля быть когда-либо изменён без поломки формата провода? Только в рамках конкретных совместимых групп, которые документирует Protobuf, вроде расширения int32 до int64 в некоторых случаях. Относитесь к любому изменению типа как к breaking, если не проверили его против собственной таблицы совместимости Protobuf; предположение совместимости по аналогии с системой типов языка — как это идёт не так.

Работает ли депрекация поля в Protobuf как директива @deprecated в GraphQL? Похожим образом: Protobuf поддерживает опцию поля [deprecated = true], которую могут показывать инструменты. Ни то, ни другое не принуждается: сервер GraphQL всё равно отвечает на запрос депрекированного поля, а клиент protobuf всё равно его кодирует. Оба механизма рекомендательные и требуют той же поддержки changelog.

Безопасна ли перенумерация, если вы контролируете каждый клиент? В полностью закрытой системе, в принципе, но это устраняет всё свойство безопасности, ради которого существуют номера полей, а «мы контролируем каждый клиент» — утверждение, которое перестаёт быть верным в момент, когда сборка кешируется, деплой откладывается, или добавляется клиент, о котором никто не помнил. Резервируйте номер вместо повторного использования, даже внутри компании.

Нужна ли сервисам gRPC страница changelog, как публичному REST API? Только если внешние команды потребляют их, не читая диффы .proto напрямую, тот же тест «кто на другой стороне», который в общем применяют changelog внутренних API. Сервис gRPC, потребляемый только другими сервисами той же команды, часто может обойтись без формального changelog в пользу истории коммитов, потому что у любого, кто его читает, схема уже открыта.

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

Thu, 17 Sep 2026 00:00:00 GMT

Большинство команд начинают changelog как файл Markdown, потому что это путь наименьшего сопротивления: читаемо в diff pull request'а, читаемо на GitHub без какого-либо рендеринга, и знакомо любому, кто когда-либо писал README. Этот выбор работает нормально ровно до того момента, когда файл нужно прочитать чему-то, кроме человека, странице, виджету, сводке по email, и тогда формат перестаёт быть бесплатным. Автоматизация changelog разбирает структурное требование в общем, тип, дата, тело и ссылка; это про то, какой формат файла реально доставляет эту структуру и сколько стоит до неё добраться с каждым.

Что не так с простым changelog в Markdown?

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

Что структурированный формат реально даёт?

Гарантию, что каждая запись имеет одну и ту же форму, проверенную при написании записи, а не угаданную при чтении. Файл JSON или YAML с определённой схемой, тип, дата, версия, аудитория, тело, ссылка, падает громко, если отсутствует обязательное поле, точно так же, как это сделал бы строгий ответ API; файл Markdown просто рендерит то, что там есть, правильно это или нет. Эта разница невидима до дня, когда скрипту нужна дата каждой записи, чтобы отсортировать поток, а у половины записей она в другом месте.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Значит ли это, что читаемый человеком файл должен исчезнуть?

Нет, и попытка заставить файл YAML или JSON служить одновременно тем, что человек читает в pull request, обычно ошибка в обратную сторону: ревью diff вложенного JSON хуже, чем ревью предложения прозы, а ревьюер, которому нужно мысленно распарсить структуру данных, чтобы поймать ошибку формулировки, — это ревьюер, который в конце концов перестанет ловить ошибки формулировки. Два формата могут сосуществовать: структурированные данные — источник истины, который читает пайплайн автоматизации, а сгенерированный рендер в Markdown или HTML — то, что человек реально ревьюит и читает, произведённое из структурированного файла вместо того, чтобы поддерживаться вручную рядом с ним.

Формат	Читаем человеком как есть	Парсится машиной без кастомного кода	Частый режим отказа
Markdown	Да	Нет	Непоследовательная форма записей ломает наивные парсеры
JSON	Плохо	Да	Многословный; легко вручную отредактировать в невалидный JSON
YAML	Терпимо	Да	Чувствителен к пробелам; неверный отступ — тихая, не громкая ошибка парсинга

Какой структурированный формат реально легче редактировать вручную, JSON или YAML?

YAML, для тех, кто пишет записи вручную, а не через генератор, потому что он убирает кавычки и сопоставление скобок, которые JSON требует для каждой строки и вложенного объекта. Компромисс в том, что чувствительность YAML к пробелам ломается молча так, как обычно не ломаются несовпадения скобок в JSON: парсер JSON прямо отклоняет некорректный ввод, тогда как парсер YAML может принять файл с неверными отступами и просто распарсить его в неверную структуру, что худший отказ, потому что ничто не говорит вам, что это произошло. Если записи всегда пишет только скрипт, этот компромисс в основном исчезает, и более строгий парсинг JSON становится более безопасным выбором по умолчанию.

Нужен ли странице changelog собственный структурированный формат, отдельный от файла, который её питает?

Не отдельный, тот же самый, отрендеренный иначе. Страница changelog разбирает, как сделать саму страницу машиночитаемой через JSON-поток и разметку schema.org; этот поток — сгенерированный вывод, а не второй источник истины, который нужно держать синхронизированным с исходным файлом. Поддержка структурированных данных вручную в двух местах, исходном файле и потоке страницы, это то, как эти два расходятся, так что решение о формате файла, принятое здесь, должно быть единственным, из чего генерируется всё дальше по цепочке, страница, виджет, email, а не копироваться вручную.

Стоит ли затрат на миграцию переводить существующий changelog в Markdown в структурированный формат?

Обычно только когда автоматизация — реальная цель, не раньше. Проект одного человека, публикующий файл Markdown в README на GitHub, не имеет реальной потребности в автоматизации, и преобразование его в YAML не покупает ничего, кроме церемонии. Конверсия окупает себя в момент, когда больше одного потребителя дальше по цепочке, страница, письмо со сводкой, публичный поток, должны читать одни и те же данные, потому что это ровно та точка, где несогласованности парсера Markdown начинают производить заметно неправильный вывод вместо того, чтобы просто быть раздражающими в поддержке.

FAQ

Можно ли сделать changelog в Markdown парсимым без полной смены формата? Частично, с frontmatter: небольшой блок YAML в начале каждой записи (дата, тип, версия) рядом с телом на Markdown для прозы. Это даёт структурированные поля, которые нужны парсеру, не заставляя всю запись в JSON или YAML, и это разумная середина для команды, ещё не готовой к полной миграции.

Важен ли формат файла для SEO или для того, как ранжируется страница changelog? Не напрямую. Поисковики читают отрендеренную страницу, не исходный файл, так что формат файла для них невидим; важно для самой страницы то, машиночитаема ли она сама по себе, что отдельный вопрос от того, что её генерирует.

Должна ли каждая запись changelog проходить через один и тот же файл, или типы можно разделить по файлам? Один файл проще, пока объём записей не сделает его неудобным для diff'ов или ревью; разделение по году или категории — разумный клапан сброса давления, как только diff'ы одного файла становятся слишком большими, чтобы их разумно ревьюить, но это добавляет шаг слияния прежде, чем что-либо дальше по цепочке сможет прочитать «все записи» как один список.

Существует ли стандартный формат файла changelog, как существует стандарт для RSS? Не широко принятый. Keep a Changelog предлагает конвенцию Markdown, а несколько инструментов имеют собственный; changeset это файл Markdown с frontmatter на YAML, где названы пакет и тип повышения версии, то есть тот же паттерн с frontmatter, описанный выше. Ни один из них не формат, который другие инструменты читают из коробки так, как читатели RSS универсально понимают RSS.

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

Thu, 17 Sep 2026 00:00:00 GMT

Три клиентки просят одну и ту же возможность в три разные недели, сформулированную тремя разными способами, и процесс триажа, построенный ловить дубли, делает свою работу: группирует их, считает как один запрос с тремя голосами, и бэклог остаётся чистым. Это лёгкая часть. Какие метки того стоят разбирает группировку по базовой возможности перед триажем по формулировке как механическое решение для дублей; чего не разбирает — что происходит со словами самими по себе, как только три запроса становятся одной строкой, и эта потеря обычно больше проблемы подсчёта дублей, которую она решила.

Что реально теряется, когда дубли объединяются?

Конкретная формулировка, которую использовала каждая просительница, часто более информативная, чем счёт голосов, в который она схлопывается. Одна клиентка может попросить «способ экспортировать отфильтрованные результаты», другая «экспорт CSV, уважающий мои сохранённые фильтры», а третья «экспорт без скрытых колонок». Все три — один и тот же базовый запрос, правильно сгруппированный, но каждая формулировка несёт слегка иной акцент на том, что важно этому человеку, и объединение, сохраняющее только формулировку первой подачи, полностью отбрасывает две другие. Счёт выживает; текстура, которая помогла бы кому-то построить правильную версию функции, нет.

Почему текстура важна, если счёт голосов уже говорит, что спрос существует?

Потому что спрос и дизайн — разные вопросы, и только конкретная формулировка отвечает на второй. Десять голосов за «экспорт» говорят команде, что функцию стоит строить; они ничего не говорят о том, означает ли «экспорт» CSV, PDF, запланированное письмо или endpoint API, и объединение, отбрасывающее девять из десяти оригинальных подач в пользу формулировки первой, может тихо сузить спецификацию до того, что случайно попросила первая просительница, даже если остальные девять хотели чего-то тонко отличающегося. Что на самом деле должен фиксировать запрос на функцию разбирает именно этот пробел со стороны приёма; объединение дублей — это место, где он снова всплывает после приёма, ровно в той точке, где команде больше всего нужен диапазон того, что действительно просили.

Как выглядит процесс объединения, сохраняющий формулировку вместо того, чтобы её отбрасывать?

Добавление вместо замены. Канонический элемент сохраняет один заголовок для вида бэклога, но оригинальная формулировка каждой объединённой подачи остаётся прикреплённой к нему, либо как список цитат, либо как связанные исходные тикеты, так что любой, кто позже просматривает элемент, может увидеть реальный диапазон того, что просили люди, вместо резюме одного члена команды. Это стоит почти ничего построить, поле в тикете вместо новой системы, и это разница между объединением, сжимающим информацию, и тем, что сжимает только её отображение.

Функция: Отфильтрованный экспорт CSV
Голоса: 12
Объединённые запросы:
  - «способ экспортировать отфильтрованные результаты» (acct_4421)
  - «экспорт CSV, уважающий мои сохранённые фильтры» (acct_8832)
  - «экспорт без скрытых колонок» (acct_1097)
  ...

Заслуживает ли каждый дубль объединения, или бывают ложные совпадения?

Некоторые — ложные совпадения, и обращение с «звучит похоже» как с «это тот же запрос» — свой собственный режим отказа. «Дайте мне экспортировать мои данные» и «дайте мне экспортировать только отфильтрованный вид» могут быть сгруппированы совпадением ключевого слова на «экспорт», хотя на самом деле описывают два разных объёма одной и той же общей возможности; объединение их либо раздувает счёт голосов не за то, либо, хуже, доставляет более узкую версию, потому что она случайно пришла первой. Человеческий проход по группировке, даже быстрый, ловит это до накопления; автоматическое совпадение по сходству само по себе переобъединит по словарю и недообъединит по намерению.

Когда проверку на дубли на самом деле стоит запускать — при приёме или позже?

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

Должна ли просительница знать, что её подача объединена с существующим элементом?

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

Меняет ли объединение, кому засчитывается заслуга, когда функция выпущена?

Должно включать всех, не только того, кто подал первым. Закрытие цикла обратной связи разбирает уведомление просительниц, когда их желание выпущено; для объединённого элемента это значит каждый аккаунт, привязанный к объединению, не только тот, чья формулировка стала каноническим заголовком, потому что с точки зрения каждой просительницы она попросила это, и это выпустили, независимо от того, чью формулировку случайно сохранил процесс триажа. В Changeloop это значит, что pull request называет каждый связанный issue (Fixes #142, fixes #187); issue, который он не называет, не получает комментария.

FAQ

Сколько формулировки стоит сохранять на объединённый запрос, цитату или полную ссылку на тикет? Короткой цитаты обычно достаточно для обычного случая, поскольку её цель — дать ревьюеру увидеть диапазон формулировок с одного взгляда; сохраняйте и полную ссылку на тикет, когда в оригинале был значительный дополнительный контекст, вроде скриншота или подробного описания рабочего процесса, которое однострочная цитата бы сгладила.

Делает ли сохранение формулировки каждого дубля бэклог труднее для сканирования? Нет, если это свёрнуто по умолчанию. Канонический заголовок — то, что видит бегло сканирующий ревьюер; объединённая формулировка на клик или разворот дальше, присутствует для того, кто делает более глубокое исследование, но не загромождает вид для того, кто просто считает голоса.

Что если два запроса выглядят идентичными, но оказывается, что хотят разного после постройки? Разделите их снова, как только это станет ясно, и относитесь к оригинальному объединению как к разумному решению, принятому с доступной на тот момент информацией, а не как к ошибке, повторения которой нужно избегать. Система группировки, которая никогда ничего не разъединяет, в итоге будет иметь несколько неверных объединений, навсегда запечённых.

Есть ли порог голосов, после которого объединённый запрос должен получить человеческий обзор базовой формулировки? Не фиксированное число, но любой запрос, приближающийся к решению о постройке, заслуживает этого независимо от счёта голосов, потому что это точка, где разница между «экспорт» и «экспорт как CSV с сохранёнными фильтрами» перестаёт быть нюансом и становится спецификацией.

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

Thu, 17 Sep 2026 00:00:00 GMT

Changelog REST API существует, потому что вызывающий может отклонить ответ, которого не понимает, или хотя бы залогировать ошибку достаточно громко, чтобы кто-то заметил. GraphQL имеет одну схему на одном endpoint, и каждый клиент, мобильное приложение на прошлогодней сборке и внутренний дашборд, развёрнутый сегодня утром, запрашивает один и тот же граф. Нет URL, который можно было бы разветвить. Депрекация поля означает пометку его как депрекированного на месте, в схеме, от которой уже все зависят, что делает дисциплину другой, чем в REST, хотя базовая проблема, сказать вызывающим, что что-то исчезнет, та же самая, что в общем разбирает депрекация API.

Как GraphQL помечает поле как депрекированное, если нет версии для повышения?

Директивой @deprecated, применённой прямо к полю:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

Поле остаётся доступным для запроса. Оно не исчезает, не возвращает 404, не меняет поведение; оно просто несёт машиночитаемую заметку, которую большинство инструментов GraphQL, GraphiQL, Apollo Studio, линтеры схем, покажут любому, кто просматривает схему или пишет запрос против неё. Это весь механизм. Нет отдельного endpoint для депрекации, никакого заголовка, никакого сопутствующего документа, требуемого спецификацией, что одновременно и привлекательность, и ловушка: директиву легко добавить и легко проигнорировать, потому что ничто не заставляет клиента на неё смотреть.

Видит ли кто-то вообще причину депрекации?

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

Механизм	Кого достигает
Директива `@deprecated`	Разработчицы, просматривающие схему или пишущие новые запросы
Сбои CI линтера схемы	Команда, владеющая клиентской кодовой базой, если она такой запускает
Запись в changelog	Кто угодно, кто её читает, включая клиентскую команду без линтера
Ничего (поле просто работает)	Уже построенный клиент, использующий старое поле

Должно ли депрекированное поле всё равно получить запись в changelog?

Да, и она делает больше работы, чем одна директива, потому что changelog достигает людей, которых директива достичь не может: команду-партнёра, которая потребляет граф, не просматривая его схему, клиент, построенный против закешированной месяцы назад копии схемы, любого, кто заметил бы это только прочитав прозу. Changelog API в общем разбирает, что запись должна вызывающему; запись GraphQL должна одну вещь, которую REST редко приходится проговаривать явно, потому что вызывающие REST выводят её из номера версии: работает ли старое поле сегодня всё ещё, работает ли ещё с предупреждением, или фактически перестало возвращать данные. Одна директива не отвечает ни на что из этого для читательницы, которая никогда не открывала схему.

Когда на самом деле безопасно удалять поле из схемы?

Только когда логи запросов показывают, что его больше никто не запрашивает, что вопрос использования, а не календаря. Поле может нести @deprecated год и всё ещё быть несущим для одного клиента, который никогда не пересобирался; удаление его по фиксированному расписанию, как часто делает REST-овый Sunset, ломает этого клиента без какого-либо предупреждения, на которое он мог бы среагировать, потому что GraphQL не даёт ему ничего, на что реагировать, кроме директивы, которую он никогда не читал. Логируйте использование на уровне поля прежде чем обязываться на дату удаления, и относитесь к любому ненулевому счётчику запросов как к паузе, а не отсчёту.

Несёт ли добавление поля тот же риск, что и в API REST?

Меньше, для нового поля, потому что клиент GraphQL получает только те поля, о которых явно просит. Добавление priceV2 рядом с price не может сломать существующий запрос так, как добавление поля в JSON-ответ REST может сломать строгий десериализатор, потому что ничто не заставляет клиента запрашивать новое поле. Добавление значения в существующий enum стоит назвать в том же дыхании как исключение: клиент, исчерпывающе переключающийся по каждому значению enum, к чему поощряют строго типизированные языки, ломается в момент появления нового значения, независимо от того, запрашивал ли его какой-либо запрос. Эта безопасность держится только для полей и членов union, в которые клиент сам решает войти; она не держится для закрытого множества, которое код клиента перечисляет вручную.

Что нужно записи changelog GraphQL, чего не нужно записи REST?

Форма запроса, а не только имя поля, потому что «поле price депрекировано» не хватает именно той части, которая на самом деле нужна вызывающему: какие типы и какие запросы его касаются. Полезная запись называет тип, поле, поле-замену и, если можете это сгенерировать, реальные запросы в продакшене, которые всё ещё запрашивают старую форму. Этот последний кусок, привязка уведомления о депрекации к реальному использованию, это то, что вызывающие REST получают бесплатно из логов сервера на URL, а вызывающие GraphQL нет, потому что каждый запрос попадает в один и тот же endpoint независимо от того, что он запрашивает.

Может ли что-то, кроме поля, нести директиву `@deprecated`?

Значения enum, той же директивой на определении самого значения, а не поля:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

Спецификация определяет @deprecated ровно для двух мест, определения поля или значения enum, и больше ни для чего по состоянию на стабильный релиз; депрекация на уровне аргумента и input-поля существует только в более поздних черновых формулировках, не в том, что реализует большинство серверов сегодня. Значение enum, помеченное так, остаётся допустимым значением, которое сервер всё ещё может вернуть или принять, то же самое не-ломающее обещание, что даёт депрекированное поле, и именно это делает безопасным выпустить пометку до того, как значение будет удалено по-настоящему.

FAQ

Поддерживает ли GraphQL что-то вроде заголовка Sunset для целого endpoint? Нет, потому что обычно есть только один endpoint. Тайминг депрекации живёт на уровне поля, в тексте причины директивы @deprecated и в любом changelog или руководстве по миграции, которое команда публикует рядом, а не в заголовке ответа, который клиент мог бы прочитать программно.

Можно ли удалить депрекированное поле и позже добавить снова с другим типом? Только под новым именем поля. Повторное введение того же имени поля с изменённым типом — это именно тот breaking change, который цикл депрекации существует, чтобы избежать; дайте замене собственное имя, как делает priceV2, и дайте старому полностью угаснуть, прежде чем имя освободится для повторного использования.

Должен ли текст причины @deprecated вести на запись changelog? Да, когда инструменты схемы это поддерживают. Поле причины принимает обычную строку, и URL внутри этой строки — кратчайший путь от разработчицы, смотрящей на вывод интроспекции, к более полному объяснению, которое может дать запись changelog.

Бывает ли изменение схемы GraphQL когда-либо обратно совместимым так, как REST не бывает? Аддитивные изменения полей, да, по причине выше: клиенты получают только то, что запрашивают. Новые значения enum — исключение, потому что клиент, перечисляющий закрытое множество, может сломаться на значении, которого не ожидал. Удаления и изменения типов ровно так же ломающие, как их REST-эквиваленты.

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

Mon, 07 Sep 2026 00:00:00 GMT

Гайд по миграции API — это документ, который превращает несовместимое изменение в чек-лист вместо сбоя: что изменилось, что с этим делать и к какому сроку. Запись changelog может назвать несовместимое изменение в двух предложениях; гайд по миграции — это то, что вызывающая сторона реально открывает, когда эти два предложения говорят «это тебя ломает», и ей нужно точно знать, что редактировать. Публикация записи без гайда — это способ, которым вызывающая сторона узнаёт о несовместимом изменении из тикета поддержки вместо документа, написанного, чтобы этого не случилось.

Что такое гайд по миграции API?

Пошаговый документ, который переводит вызывающую сторону от старой формы API к новой, написанный для того, у кого есть код для изменения, а не для того, кто ещё решает, использовать ли API вообще. Это различие важно: гайд по миграции предполагает существующую интеграцию и существующий production-трафик, поэтому он должен покрывать откат, частичную миграцию и то, как понять, сработала ли миграция — ничего из этого не нужно гайду для первой интеграции.

Документ	Предполагает	Отвечает на
Гайд по миграции	Существующую интеграцию	Как перейти от старой формы к новой?
Запись changelog	Ничего, только что читательница проверяет	Что изменилось, и когда?
Референс API	Ничего, или первую интеграцию	Что делает этот endpoint?
Уведомление о депрекейшене	Интеграцию, использующую старое	Когда это перестанет работать?

Гайд по миграции обычно стоит между последними двумя: уведомление о депрекейшене запускает часы, а гайд по миграции — то, чему следует вызывающая сторона до того, как эти часы истекут.

Когда изменению нужен гайд по миграции, а не просто запись changelog?

Когда между старым и новым поведением больше одного шага, или когда изменение затрагивает достаточно точек вызова, чтобы вызывающей стороне было полезнее проработанный пример, чем описание. Что такое несовместимое изменение, и как его выпустить разбирает тест на то, является ли изменение несовместимым; если ответ да, второй вопрос — это однострочная правка или настоящая миграция. С переименованным полем вызывающая сторона может справиться просто по записи changelog. Изменение в аутентификации, пагинации или обработке ошибок почти всегда заслуживает гайда, потому что правильный замещающий код не очевиден из однопредложенческого описания.

Что должен содержать гайд по миграции?

Пять вещей, и пропуск любой из них — это то, как гайд превращается в страницу, которую вызывающая сторона читает один раз, а потом возвращается к методу проб и ошибок. Старый код, показанный так, как он реально выглядел бы в проекте. Новый код, показанный так же, а не как абстрактное описание разницы. Что сломается, если ничего не менять — сказано прямо, потому что «ничего» — валидный и частый ответ, который вызывающая сторона всё равно должна услышать явно. Способ проверить, что миграция сработала — например, поле ответа или код статуса для проверки. И график: когда старое поведение перестаёт работать, и доступны ли обе формы тем временем.

## Миграция полей валюты с float на integer (v3.0.0)

До:
  { "amount": 19.99 }

После:
  { "amount": 1999 }  // наименьшая единица валюты (центы)

Что меняется: `amount` теперь целое число в наименьшей единице
валюты аккаунта. Код, читающий `amount` как float, будет читать
значение в 100 раз больше начиная с 1 октября 2026 года.

Проверка: после миграции списание $19.99 должно читаться как
`amount: 1999`, а не как `amount: 19.99`.

График: v2 продолжает возвращать float до 15 января 2027 года. v3
возвращает целые числа с момента запуска. Обе версии сейчас активны.

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

Кто должен его писать, и когда?

Тот, кто спроектировал изменение, в тот же момент, когда оно выходит — а не команда поддержки, восстанавливающая его позже из тикетов. Тот, кто принял решение, знает, на какие части старого поведения никто не должен был полагаться, а какие были случайным контрактом; гайд, написанный позже кем-то без этого контекста, склонен либо слишком объяснять очевидное, либо упускать тот единственный крайний случай, который реально ломает людей. Гайд и запись changelog, объявляющая несовместимое изменение, должны выходить вместе, а запись должна ссылаться на гайд, а не повторять его.

Как это связано с версионированием и changelog API?

Напрямую: гайд по миграции — это подробная версия того, что запись MAJOR в semantic versioning и вашем changelog только резюмирует в одном предложении. Запись changelog говорит, что изменение несовместимо, и примерно что изменилось; гайд по миграции — это ссылка, которую должна нести эта запись. Changelog API: что публиковать и кто это читает перечисляет гайд по миграции как один из пяти документов, которые ведёт API, каждый отвечает на свой вопрос; это тот, что отвечает на «как реально перейти от A к B», и он заслуживает собственной страницы именно потому, что этот ответ обычно слишком длинный для записи changelog.

Как долго гайд по миграции должен оставаться опубликованным?

Как минимум пока старое поведение остаётся доступным, а в идеале и после. Вызывающей стороне, мигрирующей на восемнадцать месяцев позже, проигнорировав три уведомления о депрекейшене, гайд всё ещё нужен, и удаление его в день отключения старого поведения только гарантирует, что вызывающая сторона, которой он нужнее всего, его не найдёт. Держите его по стабильному URL и обновляйте раздел графика, а не отзывайте страницу. Собственный гайд по апгрейдам Stripe служит публичным примером этого паттерна: одна страница, которая остаётся актуальной от релиза к релизу, а не новый документ на каждую версию, устаревающий в момент выхода следующей. Ваш собственный гайд заслуживает такого же легко находимого места, рядом с документацией, которую вызывающая сторона уже читает, а не спрятанным в архиве блога.

FAQ

Нужен ли каждому несовместимому изменению гайд по миграции? Нет. Изменение, которое вызывающая сторона может решить просто по записи changelog — например, одно переименованное поле с очевидной заменой — не нуждается в отдельном гайде. Изменение, затрагивающее несколько точек вызова или требующее проработанного примера — нуждается.

Должен ли гайд по миграции жить с документацией API или в changelog? С документацией, со ссылкой из записи changelog. Запись — это то, что подписчица видит первым; гайд — это то, что нужно, как только она решила действовать, и место ему рядом с справочными материалами, которые вызывающая сторона уже использует.

В чём разница между гайдом по миграции и уведомлением о депрекейшене? Уведомление о депрекейшене заявляет, что что-то исчезнет, и к какому сроку. Гайд по миграции — это инструкции о том, что с этим делать. Уведомление о депрекейшене без привязанного гайда по миграции даёт вызывающей стороне срок, не говоря, как его соблюсти.

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

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

Mon, 07 Sep 2026 00:00:00 GMT

У каждой команды, которая ведёт changelog вручную, был один и тот же разговор после одного и того же инцидента: релиз вышел без записи, кто-то спрашивает почему, и честный ответ — человек, который бы её написал, спешил, и шаг changelog жил только в памяти. Автоматизация changelog разбирает, что pipeline может безопасно автоматизировать, а что всё ещё требует человека; проверка changelog в CI — вторая половина этой проблемы, потому что автоматизация написания не помогает, если никто не обязан вообще её запускать. GitHub Actions — это то место, где большинство команд уже запускают свои проверки pull request'ов, так что и эта проверка живёт там же.

Почему «мы просим людей добавлять запись» проваливается по предсказуемой схеме?

Потому что это конкурирует за внимание со всем остальным в pull request'е, и это единственная часть без немедленного последствия за пропуск. Тесты проваливаются громко и блокируют merge. Отсутствующая запись changelog не блокирует ничего, поэтому она проигрывает, как только кто-то торопится, что на практике большую часть времени. Политика, поддерживаемая памятью, деградирует именно с той скоростью, которую можно ожидать: хорошо первые несколько недель после согласия всех, потом тихо заброшена, как только человек, которому было не всё равно, уходит в отпуск или меняет команду.

Что на самом деле проверяет CI-check для записи changelog?

Не качество написанного, только то, что запись существует и правильно оформлена, что является правильным объёмом для проверки changelog, работающей в CI, а не в голове человека. Распространённая форма: check смотрит на diff PR и требует либо новый файл в директории changeset'ов (шаблон, который используют Changesets и похожие инструменты), либо изменённую строку в файле changelog, и проваливает build, если ни того ни другого нет. Проверка того, что запись на самом деле говорит, по-прежнему происходит там, где она всегда происходила, в code review, потому что это суждение не место в скрипте.

Что проверяет CI-check	Что не проверяет
Есть changeset или строка changelog в diff	Ясна ли формулировка
Запись ссылается на правильный пакет, в monorepo	Заслуживает ли изменение записи вообще
Файл синтаксически валиден (frontmatter, форма JSON)	Честна ли запись о влиянии

Нужна ли она каждому PR, или некоторые изменения освобождены?

Некоторые освобождены, и список исключений — то место, где такие системы на самом деле строятся или забрасываются. Обновление зависимости без видимого эффекта, изменение только тестов, внутренний рефакторинг без изменения поведения: ни одно из этого не должно заставлять контрибьюторку выдумывать запись changelog для того, до чего никому, читающему changelog, нет дела. Работающий шаблон — метка или флаг, которую контрибьюторка может применить (no-changelog-needed) и которая удовлетворяет CI-check без файла, проверяемый тем, кто одобряет PR, так что само исключение проходит ту же проверку, через которую прошла бы запись.

Что происходит с законными исключениями, вроде срочного хотфикса?

Gate относится к merge, а не к деплою: хотфикс под реальным временным давлением может смержиться с записью-заполнителем или тикетом на доработку, при условии что CI-check удовлетворяется намерением, а не только законченным абзацем; некоторые команды принимают однострочный stub, который мейнтейнерша шлифует перед следующим релизным срезом. Чего gate никогда не должен позволять — тихо пропустить шаг, потому что забытый stub — меньший провал, чем запись, которой никогда не существовало, а stub хотя бы оставляет след, который кто-то может найти позже.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # нужна базовая ветка
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Как убедиться, что сама проверка корректна, прежде чем она начнёт блокировать реальные PR?

Сначала откройте черновой pull request в одноразовую ветку: один с changeset'ом, один без него и один с меткой исключения, и убедитесь, что все три получают ожидаемый результат, прежде чем проверка начнёт применяться к чужой работе. Проверка changelog, которая проваливается открыто, пропуская каждый PR из-за условия, написанного задом наперёд, хуже, чем отсутствие проверки вообще, потому что выглядит как покрытие, которого на самом деле нет. workflow_dispatch на том же файле, запущенный вручную на паре недавно смерженных PR, ловит большинство таких ошибок без необходимости в живом pull request.

Работает ли та же идея вне GitHub Actions?

Форма переносится, меняется только синтаксис. GitLab CI выражает то же правило как блок rules джобы, проверяющий $CI_MERGE_REQUEST_LABELS вместо if в GitHub Actions, а обязательное одобрение merge request может заменить собой шаг проверки исключения. Проверка, описанная в этой статье, сделана на GitHub Actions, потому что это платформа, на которой уже находится большинство команд, читающих её, но лежащее в основе требование — gate, проверяемый машиной, а не соглашение, о котором просто попросили, — одинаково везде, где CI запускается перед merge.

Работает ли это так же в monorepo?

Нужна ещё одна часть: для какого пакета эта запись. Changelog в monorepo разбирает, почему единый общерепозиторный файл перестаёт работать, как только пакеты выпускаются независимо; CI-check наследует то же требование; changeset, не называющий пакет, не является полезным доказательством того, что нужный changelog обновится, только того, что какой-то файл где-то изменился в diff. Инструменты, построенные для этого (Changesets — распространённый в экосистеме JavaScript), просят контрибьюторку выбрать затронутый пакет и semver-приращение в тот же момент, когда создаётся changeset, так что CI-check получает обе части бесплатно вместо того, чтобы выводить их позже.

FAQ

Должен ли CI-check блокировать merge, или только предупреждать? Блокировать. Предупреждение функционально идентично вежливой просьбе, которая уже провалилась. Метка исключения существует именно для того, чтобы у настоящего случая «только предупреждение» всё равно был законный путь через тот же строгий gate.

Кто проверяет, правильно ли применена метка исключения? Тот, кто одобряет pull request, как часть проверки, которую он и так уже делает. Метка никогда не должна применяться самостоятельно и без проверки, иначе она становится той же тихой лазейкой, которую gate должен был закрыть.

Заменяет ли принуждение в CI необходимость pipeline автоматизации changelog? Нет, оно его питает. Автоматизация changelog разбирает превращение структурированных записей в страницу, ленту и письмо; CI-check — то, что гарантирует существование этих структурированных записей, чтобы их вообще было что автоматизировать.

Какая самая маленькая версия этого стоит того, чтобы построить первой? Один check, который проваливается, если не изменился ни один файл под назначенной директорией changelog, с одной меткой исключения. Маршрутизация по пакетам и вывод semver для monorepo могут прийти позже; главная привычка — запись существует, или кто-то явно сказал, что она не нужна, — то, что стоит иметь с первого дня.

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

Mon, 07 Sep 2026 00:00:00 GMT

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

Почему хороший отказ важен не меньше, чем хороший релиз?

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

Ответ	Что узнаёт попросившая	Стоимость для отношений
Молчание	Никто не прочитал, или никому не важно	Высокая, и растёт с каждым будущим запросом
Автоответ без причины	Где-то в очереди, бессрочно	Средняя; покупает время, но не доверие
Отказ с причиной	Прочитан, рассмотрен и получил ответ	Низкая, если причина честная
Отказ с альтернативой	Реальная потребность действительно услышана	Самая низкая; часто строит доверие

Что заставляет отказ приземлиться плохо?

Почти всегда три вещи в сочетании. Шаблонность: заготовленное «спасибо за фидбек», не упоминающее, о чём реально просили, читается так, будто его вообще не читали, даже если читали. Задержка: отказ, приходящий через шесть месяцев после запроса, когда попросившая уже забыла, что спрашивала, ощущается хуже, чем быстрое нет, потому что подразумевает, что запрос лежал нетронутым вместо того, чтобы быть рассмотренным и отклонённым. И причина, которая не выдерживает проверки: «не в нашем roadmap» не отвечает ни на что, в то время как «это потребовало бы редизайна того, как работают права доступа, а мы не планируем трогать это в этом году» даёт попросившей то, что она реально может оценить и, если это достаточно важно, эскалировать или обойти.

Что реально должен говорить хороший отказ?

Четыре вещи, в этом порядке: подтверждение, называющее конкретный запрос, а не общий пересказ; реальную причину, честно сформулированную даже когда честная причина — «это не вписывается в то, куда движется продукт» вместо более мягкой отговорки; закрыта ли дверь или просто сейчас не открыта, потому что это требует очень разного тона; и, когда она есть, альтернативу, отвечающую на лежащую в основе потребность, даже если это не буквально запрошенная функция.

Привет, Джейми,

Спасибо за запрос добавить массовый импорт CSV для приглашений в
команду. Мы посмотрели, и не будем это строить: наш поток
приглашений построен вокруг индивидуальной проверки каждого нового
участника из соображений безопасности, и массовый импорт шёл бы
против этого намеренно, а не по недосмотру.

Если реальная боль — быстро пригласить большую команду, API
поддерживает скриптованные индивидуальные приглашения, что даёт
почти всю скорость без обхода проверки: [ссылка]. Дайте знать, если
нужна помощь это настроить.

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

Чем это отличается от замыкания цикла на выпущенной функции?

Механика похожа, тон — нет. Замыкание цикла обратной связи с клиентом разбирает выпущенный случай, где сообщение — хорошая новость, а главный риск — забыть его отправить. Отказ — плохая новость, или как минимум нежеланная новость, и требует больше внимания к данной причине и меньше автоматизации в доставке: уведомление о выпущенной функции может быть шаблонным комментарием, запущенным изменением статуса, но отказ, читающийся как шаблонный — именно тот провал, которого пытается избежать весь этот подход. Оба всё же разделяют одно требование: исходный запрос должен оставаться связанным с попросившей, та же дисциплина отслеживания, которую разбирает отслеживание запросов на функции, иначе нет способа отправить любое из этих двух сообщений индивидуально.

Должен ли отказ быть публичным, как статус на публичном roadmap?

Обычно не конкретная причина, хотя статус — да. Публичный roadmap разбирает метки статуса, которые попросившая может проверить, не спрашивая снова, и статус «отклонено» или «не планируется» может быть частью этой системы. Но подробная причина, особенно когда она затрагивает внутренние приоритеты или неловкий контекст, обычно стоит больше в индивидуальном ответе, чем на публичной странице статуса, где та же формулировка должна работать для каждой читательницы вместо единственного человека, который реально спрашивал.

Заслуживает ли каждый отклонённый запрос индивидуального ответа?

Каждый запрос от названного, доступного человека — да, хотя бы короткого. Запросы с большим объёмом, дубликаты или анонимные — исключение: группировка похожих запросов и ответ раз на группу, или обновление общей метки статуса, разумны, когда индивидуальные ответы реально не масштабируются. Границу, которую нужно держать — «мы не можем ответить всем индивидуально» должно быть реальным операционным ограничением, проверенным против фактического объёма, а не отговоркой по умолчанию, чтобы пропустить ответ, который занял бы две минуты.

FAQ

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

Должен ли отказ когда-либо обещать пересмотреть запрос позже? Только если это реально вероятно и есть механизм реально его пересмотреть — например, метка, поднимающая его снова на цикле планирования. Расплывчатое «будем иметь в виду» без такого механизма функционально то же самое, что молчание, только сформулированное добрее.

Что если честная причина — то, чем компания не может поделиться, например конкурентная озабоченность? Скажите это прямо, вместо того чтобы придумывать более мягкую причину. «Мы не можем поделиться конкретным обоснованием здесь, но это не то, что мы планируем строить» честнее, и вызывает больше уважения, чем выдуманное объяснение, разваливающееся при уточняющем вопросе.

Означает ли отказ в запросе, что его нужно удалить из отслеживания? Нет. Сохраните его, помеченным как отклонённый с причиной, чтобы он был частью паттерна, против которого группируется следующий похожий запрос, и чтобы изменившийся позже контекст (новая интеграция, новый приоритет команды) мог поднять его снова, а не начинать оценку с нуля.

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

Mon, 07 Sep 2026 00:00:00 GMT

Отслеживание запросов на функции почти всегда проваливается одним из двух способов. Либо запросам некуда деваться, и они живут в почтовых ящиках и тредах Slack, где их забывают по одному, либо у них есть место, куда деваться, но туда никто не возвращается, и их забывают все разом. Работающая система должна выдерживать оба сбоя: нужно одно место, куда попадает каждый запрос, и причина открыть это место снова в следующем месяце.

Откуда на самом деле берутся запросы на функции?

Из большего числа каналов, чем учитывает большинство систем отслеживания. Тикет поддержки с «было бы неплохо, если». Комментарий на публичном roadmap. Звонок продажников, где потенциальный клиент называет ту самую вещь, которая блокирует сделку. Виджет в продукте. У каждого канала своя владелица и свои инструменты, и именно поэтому запросы рассеиваются: очередь тикетов поддержки и бэклог продуктовой команды редко бывают одной и той же системой, а запрос, дошедший только до одного из них, на практике дошёл только до одного отдела.

Источник	Типичная владелица	Где обычно теряется
Тикеты поддержки	Команда поддержки	Закрыт как решённый, больше не пересматривается
Звонки продажников	Продажи / управление аккаунтами	Поле CRM, которое никто в продукте не читает
Виджет в продукте	Продукт	Отправленная форма без последующих действий
Комментарии на roadmap	Кто бы ни строил roadmap	Сам тред комментариев
Соцсети / отзывы	Маркетинг или никто	Один раз заскриншотили, потом пропало

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

Что на самом деле ломает отслеживание запросов на функции?

Почти всегда две вещи. Первая — отсутствующее место назначения: на запросы отвечают в том канале, куда они пришли, и нигде не фиксируют надолго, так что один и тот же запрос от трёх разных клиентов выглядит как три изолированных, несвязанных ответа вместо одного сигнала. Вторая, более частая — место назначения, которое заполняется и перестаёт читаться. Таблица с 400 строками без фильтрации — уже не система отслеживания; это архив, который случайно можно редактировать.

Второй сбой опаснее, потому что кажется, будто отслеживание работает. Запросы регистрируются. Ничего не выглядит сломанным, пока кто-нибудь не спросит «сколько людей просили X», и честный ответ — «нам пришлось бы прочитать все 400 строк, чтобы узнать».

Что на самом деле должен фиксировать запрос на функцию?

Достаточно, чтобы позже ответить на три вопроса, не перечитывая исходное сообщение: что было запрошено, по возможности собственными словами того, кто попросил; кто попросил, и как с ним связаться, если ответ в итоге — «мы это построили»; и что нужно знать, чтобы понять, обычный это запрос или единичный случай. Дословная цитата ценнее пересказа, потому что пересказ, написанный тем, кто триажировал запрос, уже несёт в себе его собственное прочтение — и именно это прочтение второй человек не сможет проверить шесть месяцев спустя.

Какие метки того стоят?

Две, и они отвечают на разные вопросы. Метка типа отделяет запрос на функцию от отчёта об ошибке, потому что обоим нужны разные владелицы и сроки, а смешивание их в одной очереди даёт самым громким жалобам обгонять запросы. Метка приоритета, ограниченная небольшим набором вроде low, medium и high, отделяет «блокирует кому-то использование продукта» от «было бы приятно», потому что оба заслуживают очень разного времени ответа, и ни один не должен наследовать темп другого. Правильная установка метки типа предполагает, что запрос — то, чем он себя называет; когда запрос на функцию на самом деле — отчёт об ошибке разбирает случай, когда собственные слова клиентки направляют эту метку в неверную сторону.

Автоматизированный триаж может применить обе в момент прихода запроса. В changeloop отправка через виджет получает метку feature-request или bug и метку priority:low|medium|high за один проход, плюс тег from-widget, чтобы источник был виден без открытия элемента. Этого достаточно, чтобы фильтровать бэклог за минуту вместо целого дня: покажи мне каждый высокоприоритетный запрос на функцию, пришедший через виджет в этом месяце.

Третья метка стоит того, как только появляется публичный roadmap: статус, который тот, кто попросил, может проверить сам. Публичный roadmap целиком разбирает статусы planned, building и shipped; коротко — эта метка превращает приватную очередь в то, что попросивший может посмотреть, не спрашивая снова.

Как решить, что строить дальше?

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

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

Каждое решение здесь также порождает запросы, которые проигрывают, и они тоже заслуживают ответа; как отказать в запросе на функцию разбирает, что говорить тем, чей запрос не прошёл. Группировка и взвешивание — только половина ответа на "что строить дальше"; приоритизация запросов на функции разбирает реальные фреймворки, RICE, взвешивание по доходу и грубые счета, и где каждый из них ломается.

Как замкнуть цикл, когда что-то выпущено?

Это шаг, который системы отслеживания пропускают чаще всего, и тот, что попросившие действительно замечают. Замыкание цикла обратной связи с клиентом целиком разбирает механику; здесь важно то, что замыкание цикла работает только если исходный запрос остался связан с тем, кто его сделал. Шаблон запроса на функцию, построенный из GitHub issue, с привязкой личности попросившего к самому issue, а не спрятанной в комментарии — вот что делает возможным автоматическое уведомление «выпущено» вместо того, которое кто-то должен вспомнить отправить. Шаблон запроса на функцию показывает конкретный шаблон и назначение каждого поля.

FAQ

Каким инструментом отслеживать запросы на функции? То, что команда уже проверяет ежедневно, побеждает любой выделенный инструмент, который никто не открывает. Трекер issues на GitHub хорошо работает, если инженерия уже живёт там; лёгкая доска хорошо работает, если продукт живёт там. Инструмент важен меньше, чем то, открывают ли его снова.

Как избежать дублирования запросов на функции? Группировать по базовой возможности перед триажем по формулировке. Поиск среди существующих запросов перед созданием нового ловит большинство дублей; ежемесячный проход группировки ловит остальное. Объединение дублей без потери оригинального голоса разбирает, что делать с формулировкой, как только сама группировка сделана, чтобы объединение тихо не сужало запрос до того, что попросила подача, пришедшая первой.

Должен ли каждый запрос на функцию получать ответ? Каждый должен получить подтверждение, пусть и короткое, но не каждому нужно немедленное решение. Видимый статус, вроде метки roadmap, которую попросивший может проверить сам, заменяет большинство индивидуальных ответов, которые команде иначе пришлось бы давать.

В чём разница между отслеживанием запросов и публичным roadmap? Отслеживание — это внутренняя запись каждого запроса, включая те, что никогда не будут выпущены. Публичный roadmap — подмножество, на которое команда публично берёт обязательство, со статусом, который попросивший может увидеть, не спрашивая снова.

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

Mon, 07 Sep 2026 00:00:00 GMT

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

Почему флаг ломает обычную последовательность «выпустить, уведомить»?

Потому что он разделяет одно событие как минимум на два: код, становящийся живым, и флаг, включаемый для конкретного аккаунта. Любой процесс закрытия петли обратной связи предполагает, что эти два события происходят вместе, что верно для большинства релизов и неверно для всего, что находится за флагом, используемым для поэтапного раскатывания, таргетинга или как аварийный выключатель. Закрытие петли обратной связи клиента описывает уведомление запросившего ровно в тот момент, когда запись changelog одобрена и опубликована; этот шаг написан для случая, когда публикация записи и пригодность функции к использованию — один и тот же момент, а флаг — это как раз случай, когда это не так.

Момент	Что верно	Нужно ли уже уведомлять запросившего
Код смёржен, флаг выключен везде	Функция существует, никто не может её использовать	Нет
Флаг включён для аккаунта запросившего	Функция существует, конкретно этот человек может её использовать	Да
Флаг включён для процента раскатывания, который его исключает	Функция существует, этот человек всё ещё не может её использовать	Нет
Флаг полностью убран, функция просто включена	Функция существует для всех	Да, если ещё не уведомлён

Какое реальное правило для того, когда уведомлять кого-то?

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

Значит ли это, что запросившему нужен ранний или особый доступ?

Не обязательно, и принуждение к этому создаёт собственную проблему. Если флаг раскатывается постепенно по причинам нагрузки или стабильности, перемещение одного аккаунта в начало очереди только ради более быстрого закрытия петли подрывает саму причину, по которой раскатывание поэтапно. Честные варианты: подождать, пока аккаунт запросившего естественным образом дойдёт до раскатывания, и уведомить тогда, либо, если срочность это оправдывает, намеренно включить флаг для него раньше — как реальное решение того, кто владеет раскатыванием, а не как побочный эффект желания отправить уведомление.

А если флаг — это аварийный выключатель, а не механизм раскатывания?

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

Меняет ли флаг то, что должны говорить release notes о функции за флагом?

Он меняет, когда запись публикуется, а не что она содержит. Запись, опубликованная ровно в момент, когда флаг включён для 100% аккаунтов, читается точно как обычная запись changelog, и так и должно быть; читатель, находящий её позже, не имеет причин знать, что флаг вообще когда-либо был задействован. Чего она не должна делать — публиковаться, пока флаг включён лишь для малого процента раскатывания, потому что публичная запись changelog отправляет всех, кто её читает, включая аккаунты без флага, искать функцию, которую они не найдут, что является худшей версией той же проблемы, но в масштабе всего продукта вместо масштаба одного запросившего. Это правило про тайминг — вся разница между release notes о функции за флагом и обычной записью: содержание то же, меняется только дата публикации. Как писать release notes разбирает дисциплину «действие не требуется», которая применима и здесь: читателям нужно знать, касается ли это их, а не просто что это где-то существует.

Должны ли письма об обновлении продукта иначе обращаться с функцией за флагом?

Да, в основном откладывая, а не переписывая. Шаблон письма об обновлении продукта разбирает целевые уведомления против широких дайджестов; функция за флагом — случай, когда таймингом целевого уведомления нужно проверять против собственного состояния флага получателя перед отправкой, чего широкий дайджест вообще не может сделать легко, что ещё одна причина, почему дайджест — неверный канал для всего, что всё ещё посреди раскатывания.

FAQ

Стоит ли говорить запросившему, что его функция «скоро появится», когда флаг существует, но ещё не включён для него? Только если к этому привязана реальная, близкая дата, и даже тогда экономно. «Скоро» без даты читается, спустя достаточно времени, точно так же как молчание, и создаёт второе обещание, которое тоже нужно отслеживать и выполнять.

Кто решает, когда флаг зашёл достаточно далеко, чтобы закрыть петлю? Тот, кто владеет раскатыванием, а не тот, кто владеет уведомлением. Владелец раскатывания знает, близки ли «100% аккаунтов» или всё ещё в неделях; привязка шага закрытия петли к его состоянию, а не к фиксированной календарной дате, сохраняет уведомление честным.

Получает ли функция за постоянным флагом (никогда полностью не убираемым) когда-либо публичную запись changelog? Да, как только она достигает того, что означает «общая доступность» для этого продукта, даже если сам флаг остаётся в коде навсегда по операционным причинам. Запись changelog — о доступности для читателя, а не о деталях реализации того, как эта доступность достигается.

А если флаг убирают, и функцию убивают вместо выпуска? Это отказ, а не уведомление о выпуске, и он заслуживает той же заботы, что и любой другой отказ. Как отказать в запросе на функцию разбирает, что должно говорить это сообщение; честное закрытие петли иногда означает закрыть её отказом.

Нужен ли release notes о функции за флагом отдельный шаблон, отличный от обычной записи? Шаблон не меняется, нужен только шаг проверки перед публикацией: сверить состояние флага для аккаунта, который спрашивал, а не только то, что код смёржен, и придержать запись, пока эта проверка не пройдена. Всё остальное в записи — формулировка, длина, дисциплина FAQ — остаётся таким же, как в любой другой release note.

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

Mon, 07 Sep 2026 00:00:00 GMT

«Можете добавить настройку, увеличивающую лимит экспорта?» читается как запрос на функцию, и большинство систем триажа сразу так его помечают. Иногда так и есть. Иногда экспорт падает на числе ниже документированного лимита из-за ошибки, и клиентка, не видя код, придумала самое правдоподобное решение, какое может описать: дайте мне число побольше, и, может, заработает. Какие метки того стоят разбирает метку типа, которая делит бэклог на запросы на функции и ошибки; это случай, когда собственные слова клиентки направляют метку в неверную сторону, а цена ошибки — медленный дрейф к бэклогу, полному запросов, которых никто на самом деле не хочет, стоит только заглянуть под них.

Как выглядит запрос на функцию, который на самом деле — ошибка?

Он называет обходной путь вместо проблемы. Настоящий запрос на функцию обычно описывает результат, который продукт вообще не поддерживает: «дайте мне запланировать это на потом», «добавьте тёмный режим». Неверно классифицированная ошибка описывает конкретное число, порог или поведение, которое звучит как отсутствующая настройка, но на самом деле является симптомом: «увеличьте timeout», «добавьте опцию повторной попытки», «дайте мне экспортировать больше строк за раз». Признак в том, что просительница предлагает реализацию, настройку, переключатель, переопределение, вместо того чтобы описать цель, потому что она уже попробовала функцию как документировано, и та не сделала того, что документация обещает.

Сигнал	Запрос на функцию	Ошибка, замаскированная под запрос на функцию
Что описывает просительница	Результат, которого продукт не может дать	Параметр, который она хочет изменить
Покрывает ли это уже документированное поведение	Нет, действительно отсутствует	Да, но работает не так, как документировано
Исчезает ли запрос при больших усилиях	Нет	Иногда, если ошибка зависит от порога
Куда должно направляться	Бэклог продукта	Очередь ошибок

Почему это важнее, чем кажется?

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

Как отличить, когда собственные слова клиентки указывают в неверную сторону?

Спросите, чего она ожидала, а не что хочет, чтобы вы добавили. «Экспорт упёрся в 500 строк, а мне нужно 2000, можете поднять лимит» звучит как запрос на функцию повышения лимита, пока уточняющий вопрос, «500 — это документированный лимит», не раскрывает, что документированное число было 5000, и экспорт падает раньше времени. Только этот один вопрос, чего она ожидала против того, что произошло, выполняет большую часть работы по сортировке, потому что у настоящего запроса на функцию нет документированного поведения, которому он не соответствует; нечего ожидать, потому что возможности ещё не существует.

Должны ли это решать агенты поддержки или инженерки?

Агенты поддержки делают первый проход, потому что видят тикет первыми, но метка должна быть легко изменяемой и дёшево ошибочной, а не разовым решением, которое навсегда закрепляет элемент в неверной очереди. Лёгкая вторая проверка, инженерка, еженедельно просматривающая новые метки «запрос на функцию» на предмет всего, что пахнет замаскированной ошибкой, ловит те случаи, которые агент поддержки без контекста кодовой базы не смог бы распознать. Это не обязательно формально; это скорее пятиминутный взгляд, чем процесс ревью.

Меняется ли закрытие цикла после нахождения настоящей ошибки?

Да, и это улучшает сообщение, которое вы можете отправить. Закрытие цикла обратной связи с клиентом разбирает уведомление просительницы, когда её просьба выполнена; переклассифицированная ошибка получает лучшую версию этого сообщения, потому что «мы нашли и исправили ошибку за этим» звучит как компетентность, тогда как «мы построили функцию, которую вы просили» было бы правдой только случайно, потому что настоящий запрос на функцию, действительно более высокий лимит экспорта, может никогда не быть построен, как только ошибка исчезнет, а исходного лимита в 5000 строк окажется достаточно.

Что происходит, если неверная классификация никогда не замечена?

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

FAQ

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

Что если клиентка настаивает, что это запрос на функцию, даже после того как ошибка найдена? Объясните, что вы нашли и почему предложенная ею настройка больше не понадобится, как только ошибка исправлена. Большинство клиенток просят обходной путь, потому что предполагали, что настоящее исправление недоступно, а не потому что конкретно хотели эту настройку.

Теряет ли переклассифицированный элемент голоса или комментарии, собранные как запрос на функцию? Он должен сохранить их, видимыми, потому что эти голоса — доказательство, которое привело к нахождению ошибки в первую очередь, а скрытие этого следа затрудняет обнаружение той же неверной классификации в следующий раз, на другом тикете.

Может ли это случиться наоборот, отчёт об ошибке, который на самом деле является запросом на функцию? Реже, но да: «это сломано» иногда означает «это не делает того, что я предполагала, что оно будет делать», что является отсутствующей возможностью, а не дефектом. Тот же вопрос, чего ожидала против того, что документировано, сортирует и в эту сторону.

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

Mon, 07 Sep 2026 00:00:00 GMT

Доска запросов на функции фиксирует то, что пользователи просят, когда у них есть время сесть и описать, чего они хотят. Тикет поддержки фиксирует, на чём пользователи застряли прямо сейчас, часто раздражённые, часто без словаря, чтобы аккуратно описать лежащий в основе запрос. Оба — реальный сигнал, и команды, смотрящие только на один из двух, в итоге уверенно решают не ту проблему, потому что каждый канал систематически перепредставляет разный тип пользователя и разный тип потребности. Приоритизация запросов на функции разбирает ранжирование уже стоящего на доске; это о разрыве между тем, что вообще доходит до доски, и тем, что появляется только как тикет поддержки.

Почему одна и та же лежащая в основе проблема появилась бы в одном канале и не в другом?

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

Означает ли объём тикетов для отсутствующей функции то же самое, что счёт голосов за неё?

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

Доска запросов на функции	Тикеты поддержки
Требует инициативы для подачи	Требует почти никакой
Фиксирует продуманный, устойчивый спрос	Фиксирует фрустрацию в момент
Склоняется к вовлечённым, терпеливым пользователям	Фиксирует пользователей, которые никогда бы не использовали доску
Счёт голосов — реальный сигнал приверженности	Счёт тикетов отражает трение, не всегда желание

Что значит, когда у функции есть тикеты поддержки, но почти нет голосов на доске?

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

Доска читается как низкий приоритет:
"Export to CSV": 4 голоса за 6 месяцев

Поддержка рассказывает другую историю:
"Export to CSV": 31 тикет за тот же период, каждый с
другого аккаунта, каждый закрыт с «сейчас не
поддерживается, передадим обратную связь»

Всегда ли всплеск тикетов поддержки означает, что лежащая в основе проблема — отсутствующая функция?

Нет, и здесь два канала могут вводить в заблуждение в противоположную сторону. Всплеск тикетов так же часто вызван запутанным интерфейсом вокруг уже существующей функции, багом, или изменением, вышедшим без адекватного объяснения, ничто из которого не решается постройкой чего-то нового. Чтение каждого всплеска тикетов как «пользователи хотят функцию, которой у нас нет» производит roadmap, забитую вещами, на самом деле бывшими пробелами документации или замаскированными проблемами юзабилити. Тикет поддержки говорит вам, где трение; он сам по себе не говорит вам, является ли решением новая функция, изменение интерфейса, или лучшая статья помощи, и путаница этого тратит инженерное время на неверное решение.

Как два сигнала реально должны комбинироваться при решении, что строить?

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

Должны ли агенты поддержки сами регистрировать тикеты как запросы на функции?

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

FAQ

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

Стоит ли строить функцию, сильно представленную в тикетах, но почти без голосов? Часто да, при условии, что объём тикетов реально идёт с отдельных аккаунтов, а лежащая в основе потребность подтверждена, а не предположена; относитесь к низкому счёту голосов как к артефакту измерения стоимости активации доски, не как к доказательству, что спрос нереален.

Как отличить с первого взгляда тикет о путанице интерфейса от подлинного тикета об отсутствующей функции? Смотрите, состоит ли решение в объяснении существующей возможности или извинении за отсутствующую. Паттерн решений «о, это на самом деле прямо там» указывает на проблему интерфейса или обнаруживаемости; паттерн «мы это ещё не поддерживаем» указывает на реальный разрыв.

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

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

Mon, 07 Sep 2026 00:00:00 GMT

Git-тег, релиз и запись changelog — три разные записи одного и того же события, и их смешивание заставляет changelog тихо отклоняться от того, что реально было выпущено. Тег отмечает коммит. Релиз упаковывает этот тег с артефактами и описанием. Запись changelog объясняет — терминами, которыми может пользоваться читательница вне репозитория — что изменилось. Обычно они происходят близко по времени, и именно поэтому легко относиться к ним как к одному шагу вместо трёх, и именно поэтому разрыв становится видимым только месяцы спустя, когда кто-то спрашивает «что вышло в v2.4», и честный ответ требует настоящих раскопок.

В чём реальная разница между этими тремя?

Запись	Живёт в	Написана для
Git-тег	Репозитории, как ссылка	Тех, кто делает checkout именно этого коммита
Релиз	Хостинге кода (GitHub, GitLab)	Тех, кто скачивает сборку
Запись changelog	Собственном changelog продукта	Тех, кто пользуется продуктом, не только репо

Тег — самая механическая из трёх: git tag v2.4.0 и готово, без требования, чтобы что-то объясняло, что в нём. Релиз добавляет описание и обычно скачиваемые артефакты, и его аудитория — всё ещё разработчицы, знающие, что такое страница релиза. Запись changelog — единственная из трёх, написанная для читательницы, которая может никогда не открыть репозиторий, поэтому именно она требует больше всего редакторского внимания и чаще всего пропускается под давлением дедлайнов.

Нужна ли каждому git-тегу запись changelog?

Нет, и относиться к ним один к одному — частая ошибка. Тег может отмечать внутреннюю веху, release candidate, или hotfix, который никогда не доходит до большинства пользовательниц; ни одному из них необязательно нужна публичная запись. Тест тот же, что решает, принадлежит ли что-то changelog вообще: заметила бы это пользовательница или вызывающая сторона, важно ли ей это. Большинство тегов проходят этот тест. Некоторые — например, тег, созданный только для запуска CI-пайплайна — никогда.

Нужен ли каждой записи changelog свой тег?

Не всегда, и здесь расходятся команды с непрерывным деплоем и команды, выпускающие версионированные пакеты. SaaS-продукт, деплоящийся несколько раз в день, может группировать несколько деплоев под одной датированной записью changelog без тега 1:1 на деплой; библиотека, публикуемая в реестре пакетов, обычно нуждается в теге на каждую опубликованную версию. Go modules и Swift Package Manager резолвят версии из самих тегов; в npm или PyPI опубликованную версию хранит реестр, а тег позволяет любому сопоставить эту версию с её исходным кодом. Репозиторию с несколькими независимо версионируемыми пакетами нужно решать это по пакету, а не один раз для всего репо; changelog монорепозитория разбирает, как префиксы тегов и область changelog должны следовать границам пакетов, а не папок. Semantic versioning и ваш changelog разбирает, как сам номер версии должен маппиться на категории changelog; теги — механизм, делающий номер версии проверяемым против реального кода.

Как описание релиза должно относиться к записи changelog?

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

# Релиз v2.4.0 (GitHub, для разработчиц)
Поднимает пайплайн отчётов до нового движка агрегации. Смотрите
changelog для резюме, ориентированного на клиента:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, ориентирован на клиента)
### Added
- Отчёты теперь загружаются меньше чем за секунду, даже для аккаунтов
  с более чем миллионом строк.

Один и тот же релиз, два документа, каждый со своей формулировкой для своей читательницы.

Откуда на самом деле берётся запись changelog?

Из двух отправных точек, и большинство реальных пайплайнов — смесь обеих. Она может генерироваться из commit-сообщений в момент тега, что быстро и никогда не пропускает смёрженный pull request; от conventional commits к changelog разбирает этот пайплайн целиком. Или она может писаться вручную, совершенно отдельно от тега, синхронизированная с моментом, когда фича считается готовой, а не с моментом, когда мёрджится код. Сгенерированные записи консистентны, но наследуют каждое расплывчатое commit-сообщение; написанные вручную — понятнее, но нужен кто-то, кто их реально напишет. Большинство команд, которые автоматизируют, всё равно оставляют лёгкий проход редактуры по сгенерированному тексту перед тем, как он станет публичной записью — та же дисциплина, что рекомендует Keep a Changelog на практике, независимо от того, откуда изначально пришёл сырой текст.

Что ломается, когда эти три расходятся?

Доверие к тому, что читательница проверила первым. Тег, существующий без соответствующей записи changelog, выглядит со стороны читательницы changelog так, будто на той неделе ничего не произошло. Запись changelog без соответствующего тега или релиза делает невозможным для того, кто отлаживает проблему в production, сделать checkout именно того кода, который был live, когда запись публиковалась. Решение — не идеальная автоматизация, а единый источник истины для этого соответствия: одно место, пусть даже это просто собственный чек-лист процесса релиза, говорящее, что выпускаемое изменение получает все три, в том же коммите или pull request, который его вводит.

FAQ

Должны ли записи changelog генерироваться автоматически из git-тегов? Они могут быть отправной точкой, но сам по себе тег не несёт никакого описания, ориентированного на читательницу — только диапазон коммитов. Автоматизированная генерация должна читать commit-сообщения внутри этого диапазона, а не просто факт существования тега, чтобы произвести что-то пригодное для использования.

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

Должны ли pre-release-теги (вроде v2.4.0-rc.1) иметь записи changelog? В общем случае нет. Release candidate предназначен для внутреннего или бета-тестирования, и запись changelog для него учит читательниц ожидать записи для версий, которые могут никогда не выйти так, как описано. Оставляйте записи для тегов, достигающих общей доступности.

Может ли одна запись changelog покрывать несколько git-тегов? Да, и часто должна для команд, тегирующих часто. Группируйте связанные теги под одной датированной записью, описывающей чистое изменение, вместо публикации тонкой записи на тег, фрагментирующей фичу на несколько прочтений.

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

Mon, 07 Sep 2026 00:00:00 GMT

Все остальные статьи в этом хабе предполагают, что вызывающий API находится вне компании: инженер клиента, партнёр, кто-то, кто сам нашёл документацию. У многих API совсем другой тип вызывающего — команда в соседней комнате или в двух этажах, — и это меняет расчёт того, чем changelog ей обязан, потому что сообщение в Slack её достигнет, а тикет в поддержку обычно вообще никогда не заводится. Большинство команд заключают из этого, что внутренним API changelog не нужен. На самом деле им нужен другой.

Чем changelog внутреннего API отличается от публичного?

У аудитории есть прямая досягаемость, что убирает главную причину существования большинства публичных changelog API — вещание на вызывающих, с которыми нельзя связаться индивидуально. Команда-владелец внутреннего API обычно точно знает, какие другие команды его вызывают, иногда вплоть до конкретного сервиса. Это делает целевое сообщение, а не публичную ленту, естественным выбором по умолчанию, и именно поэтому внутренние API так часто остаются вовсе без changelog: команда-владелец предупреждает те две-три команды, которые помнит, предполагая, что этим всё покрыто.

	Публичный changelog API	Внутренний changelog API
Кто читает	Любой внешний вызывающий, обычно недосягаемый напрямую	Небольшой, обычно известный набор внутренних команд
Канал по умолчанию	Страница и лента	Сообщение вызывающим командам, в идеале тоже со страницей
Главный риск	Вызывающий полностью пропускает запись	Команда-владелец забывает вызывающего, о существовании которого не помнит
Что заменяет «мы не знаем, кто нас вызывает»	Ничего; публиковать широко	Реальный, поддерживаемый в актуальном состоянии реестр вызывающих

Почему «мы просто предупредим команды, которые нас вызывают» проваливается?

Потому что набор вызывающих никогда не бывает таким маленьким или статичным, каким его помнит команда-владелец. Сервис, построенный для одного потребителя, обретает второго вызывающего через шесть месяцев, через интеграцию, которую никто не анонсировал, и мысленный список «кто нас вызывает» команды-владельца теперь неверен, а никто этого не замечает. Этот провал обычен и распространён, это результат по умолчанию, когда полагаются на память вместо реестра, а не признак чьей-то небрежности. Что такое breaking change разбирает, как решить, считается ли изменение API ломающим вообще; внутренний случай добавляет сверху второй, более трудный вопрос — знать, кого предупреждать.

Нужна ли внутреннему API вообще страница changelog в публичном стиле?

Обычно да, даже если основной канал — прямой. Страница даёт прямому сообщению на что сослаться, так что уведомление может оставаться коротким («breaking change в /v2/accounts, детали здесь») вместо попытки уместить всё объяснение в сообщение чата, которое уедет со скроллом. Она также становится тем, что новая команда, или та, что пропустила прямое сообщение, может проверить, когда её интеграция ломается и она пытается понять почему. Страница не обязана быть отполирована или публична; она должна быть доступна по ссылке и пережить Slack-тред, который её анонсировал.

Кто на самом деле ведёт список вызывающих?

Команда-владелец, и к этому нужно относиться как к реальному артефакту, а не как к племенному знанию. Самый дешёвый вариант — файл прямо в репозитории самого API, короткий список потребляющих сервисов с ответственным на каждую запись, обновляемый каждый раз, когда строится новая интеграция, — та же дисциплина, что и при любом объявлении зависимости. Альтернатива, спрашивать вокруг перед каждым breaking change, работает до того единственного раза, когда кто-то забывает спросить нужного человека, и внутренний API, тихо сломавшийся для одной команды, — инцидент меньше публичного, но всё равно инцидент, обычно обнаруживаемый собственным дежурным этой команды, а не владельцем API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Такой файл превращает «кого нам нужно предупредить» из вопроса в поиск. Инструменты, построенные именно для этой задачи, вроде сервисного каталога Backstage, моделируют API как полноценные сущности с объявленными потребителями по той же причине: как только в организации становится достаточно внутренних сервисов, ничья память о том, кто что вызывает, сама по себе больше не остаётся точной, и что-то должно вести реестр вместо неё. Документация того инструмента, который вы уже используете внутри, — обычно правильное место, куда стоит заглянуть перед тем, как строить собственный.

Что принадлежит внутренней записи changelog, чего не понадобилось бы публичной?

Больше операционной конкретики, потому что читатель — другой инженер, который будет действовать на основе этого в той же инфраструктуре, а не читать это как резюме. В каких окружениях изменение живо и когда, потому что внутренние сервисы часто продвигаются через стадии, которые публичный вызывающий никогда не видит. Требует ли изменение обновления конфигурации или клиентской библиотеки на стороне потребителя, сформулированного как команда, если такая есть. И, поскольку внутренние вызывающие часто могут согласовать исправление напрямую с командой-владельцем, — названный контакт вместо канала поддержки: «напишите @maria, если это что-то сломает» — это совершенно разумная строка во внутренней записи и странная в публичном changelog API.

Применимо ли это так же к changelog внутри монорепозитория?

Это обостряет ту же проблему, а не заменяет её. Changelog монорепозитория разбирает, когда пакету нужен собственный changelog; внутреннему API, являющемуся одним из нескольких пакетов в монорепозитории, всё равно нужно, чтобы его потребители отслеживались явно, потому что общий репозиторий с теми, кто его вызывает, не означает, что они заметят изменение, если что-то не укажет им посмотреть. Близость в репо — не то же самое, что близость во внимании.

FAQ

Нужен ли changelog чисто внутреннему API, если у него один вызывающий? Едва ли, и прямого сообщения этой единственной команде обычно достаточно. Changelog оправдывает себя, как только вызывающих становится больше одного, или как только список вызывающих однажды удивил команду-владельца, потому что это сигнал, что одной памяти больше не хватает.

Должны ли внутренние изменения API проходить ту же проверку, что и публичные? Формулировки могут быть легче, поскольку читатель — коллега, а не внешний вызывающий, но решение, является ли изменение ломающим, заслуживает той же тщательности в обоих случаях. У внутреннего вызывающего всё равно есть продакшен-код, зависящий от старого поведения.

Как узнать, кто вызывает внутренний API, если это никогда не отслеживалось? Логи сервера или данные трафика service mesh — честный ответ, если реестр потребителей никогда не велся; относитесь к этому открытию как к моменту начать его вести, а не как к разовой уборке.

Достаточно ли сообщения в Slack, или внутреннему изменению всё равно нужна формальная запись в changelog? И то, и другое, для всего, что не является чисто аддитивным. Сообщение — это то, что читают вовремя; запись — это то, что команда, расследующая проблему недели спустя и никогда не видевшая сообщения, всё равно сможет найти.

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

Mon, 07 Sep 2026 00:00:00 GMT

Каждая другая статья в этом хабе предполагает, что читатель release note — клиент. Саппорт, продажи и customer success тоже читают, или пытаются, и большинство узнаёт, что вышло, потому что клиент спрашивает первым. Этот порядок перевёрнут, и он же принят по умолчанию в большинстве компаний, потому что процесс релиза заканчивается в момент выхода заметки для клиентов, и никто не выстроил второй, меньший шаг для людей, которым час спустя нужно отвечать на вопросы о ней.

Что такое внутренняя release note, и чем она отличается от заметки для клиентов?

Это более короткий документ, написанный для людей, уже глубоко знающих продукт, который говорит им, что изменилось и что с этим делать в их конкретной работе. Агенту саппорта не нужно отполированное оформление, которое использует анонс для клиентов; ему нужно знать, как изменение выглядит в продукте прямо сейчас, каким будет самый вероятный вопрос о нём, и затронуты ли открытые тикеты. Заметка для клиентов продаёт изменение. Внутренняя вооружает кого-то, чтобы с ним справиться.

Аудитория	Что ей нужно знать	Где ей это нужно
Саппорт	Что изменилось в интерфейсе, вероятные вопросы, затронутые открытые тикеты	Там, где он уже ищет ответы
Продажи	Что это открывает для сделки, чего оно ещё не делает	Там, где готовятся к звонкам
Customer success	Что сказать существующим клиентам, и кто это просил	Там, где планируют контакт
Руководство	Что вышло относительно обещанного, и когда	Короткая, повторяющаяся сводка, не на каждый релиз

Почему внутренние команды узнают о запусках с опозданием?

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

Что внутренняя release note должна говорить такого, чего не говорит заметка для клиентов?

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

Внутренняя заметка: массовый экспорт CSV (выходит 08.09.2026)

- Доступно только на планах Team и Enterprise. На Free и Pro без
  изменений.
- Частая ошибка: экспорт свыше 50 тысяч строк уходит в таймаут;
  известная проблема, фикс отслеживается отдельно. Сказать
  клиенту фильтровать по диапазону дат.
- Закрывает 14 открытых запросов с меткой `bulk-export`. Шаблон
  ответа в общем документе.
- Ответственный: команда platform, #platform-eng по всему, что
  выходит за рамки этой заметки.

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

Кто должен её писать, и когда?

Тот, кто пишет заметку для клиентов, обычно и есть подходящий человек, потому что у него уже есть весь контекст, но это должен быть отдельный, короткий проход, а не попытка заставить один документ обслуживать обе аудитории. Их объединение производит либо заметку для клиентов, перегруженную внутренними деталями, либо внутреннюю заметку, слишком отполированную, чтобы быть действительно полезной, и на практике быстрее написать два коротких документа, чем договариваться об одном документе, обслуживающем две аудитории сразу. Время важнее авторства: внутренняя заметка должна выходить раньше заметки для клиентов, хотя бы на несколько часов, чтобы саппорт никогда не узнавал об изменении из того же места, что и клиент.

Где ей нужно жить, чтобы саппорт действительно находил её в момент тикета?

Там, где команда уже ищет вещи, когда приходит тикет, а не в отдельном changelog, который никому не приходит в голову открывать по собственной инициативе. Команде саппорта, использующей общую базу знаний, нужна заметка там, связанная с местом, где тикеты об этой части продукта уже помечены. Команде, живущей в общем канале, нужно, чтобы она была опубликована там, доступна для поиска, в момент, когда она актуальна, а не похоронена в ежедневной сводке, которую они просматривают один раз. Паттерн для клиентов из целевого уведомления против дайджеста применим и здесь: внутренняя заметка о конкретном, предстоящем изменении должна достигать команды напрямую, а не ждать еженедельной сводки, приходящей после того, как первый тикет уже существует.

Нужна ли ей та же строгость проверки, что и внешней?

Меньше, и это осознанно. Заметка для клиентов представляет компанию публично и заслуживает внимательного прохода редактирования; внутренняя заметка существует, чтобы быть быстрой и конкретной, и удерживать её на том же уровне полировки — обычно именно то, что заставляет команды вовсе перестать её писать. Быстрая, слегка сыроватая внутренняя заметка, выходящая за час до запуска, бьёт отполированную, приходящую на следующий день, когда первый тикет саппорта уже пришёл в растерянности.

FAQ

Должны ли внутренние release notes проходить тот же процесс утверждения, что и заметки для клиентов? Нет. Более лёгкий, быстрый проход — и есть смысл. Требование той же проверки превращает внутреннюю заметку того же дня в заметку следующей недели, к которой саппорт уже ответил на вопрос без неё.

Кто отвечает за внутренние release notes, если нет выделенной роли внутренних коммуникаций? Тот, кто пишет заметку для клиентов, — как второй, короткий проход сразу после. Отдельный ответственный не нужен, нужна только привычка не относиться к заметке для клиентов как к единственному артефакту, который производит релиз.

Нужен ли внутренним release notes собственный changelog или архив? Место с поиском лучше хронологического архива, который никто не пролистывает. Если у саппорта уже есть база знаний, заметка принадлежит туда, помеченная функцией, а не в отдельный внутренний changelog, который помогает только тому, кто уже знает дату выхода.

В чём риск пропускать внутренние release notes для маленьких изменений? Маленькие изменения — как раз те, по которым саппорт получает вопросы без предупреждения, потому что маленькое изменение редко получает анонс на уровне компании. Размер release note должен масштабироваться с размером изменения; он никогда не должен опускаться до нуля просто потому, что изменение было незначительным.

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

Mon, 07 Sep 2026 00:00:00 GMT

Всё в этом хабе о написании release notes предполагает страницу, которую вы полностью контролируете: любая длина, работающие ссылки, отображаемое форматирование. Release notes мобильного приложения живут в чужой коробке. Apple даёт примерно 4000 символов, но показывает только первые строки, пока не нажато «ещё»; Google даёт похожий объём с той же эффективной проблемой предпросмотра, и ни одна из платформ не отображает кликабельную ссылку в тексте. Правила из как писать release notes, которые люди реально читают всё ещё действуют: сказать, что изменилось, и что должен сделать читатель, но места для этого — доля того, что позволяет страница changelog, и урезания должны быть намеренными, а не случайными.

Что реально помещается в видимый предпросмотр?

Первые одна-две строки, примерно 80-170 символов в зависимости от устройства и размера шрифта, прежде чем читателю придётся нажать, чтобы развернуть. Это весь бюджет для той части release note, которая решает, будет ли кто-то читать остальное, и это значит, что самое важное предложение должно идти первым — не номер версии, не приветствие, не заголовок категории. Release note, начинающаяся с «Новое в этой версии:», уже потратила треть видимого пространства на четыре слова, которые ничего не говорят читателю.

Платформа	Примерный общий лимит	Эффективный предпросмотр до «ещё»
App Store (iOS)	~4000 символов	2-3 строки, примерно 80-170 символов
Google Play	~500 символов на язык, некоторые поля короче	2-3 строки, похоже на iOS
Обе	Нет кликабельных ссылок в поле release notes	Не применимо

Работает ли правило «что можно сделать сейчас, что вам обязаны» на этой длине?

Да, и оно становится строже, а не иным. Одно предложение на запись, глагол первым, без вступления: «Экспортируйте данные как CSV из Настроек.» побеждает «Мы добавили возможность для пользователей теперь экспортировать свои данные в формате CSV», используя треть слов, чтобы сказать то же самое. На длине страницы changelog чуть многословное предложение стоит читателю полсекунды. На длине мобильной release note та же многословность может вытолкнуть предложение целиком за пределы видимого предпросмотра, так что читатель никогда не увидит глагол, который сказал бы, что изменилось.

Плохо, тратит предпросмотр на обрамление:
«Мы рады представить вам новое обновление, полное
улучшений! Читайте дальше для подробностей».

Хорошо, вся ценность в первой строке:
«Экспортируйте данные как CSV. Тёмная тема теперь
следует системной настройке. Исправлен сбой при
открытии общих ссылок».

Что нужно урезать из того, что обычно сохранила бы запись веб-changelog?

Ссылки, во-первых, потому что ни один из двух магазинов не делает их кликабельными, так что URL в тексте — мёртвый груз, который читателю пришлось бы перепечатывать. Если записи нужен пункт назначения, скажите вместо этого, что нажать в приложении: «Смотрите новые фильтры в Настройках > Поиск» работает; «Подробнее на example.com/blog/filters» — нет, на этой поверхности. Во-вторых, всё условное или специфичное для аудитории: веб-changelog может сказать «если вы используете API, это вас касается», но листинг магазина достигает каждого установившего приложение пользователя одновременно, так что условная строка читается как шум для тех 95%, к кому она не относится. Поместите условную деталь вместо этого во внутриприложенческое сообщение, срабатывающее для аккаунтов, которых это реально касается.

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

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

Влияют ли release notes на то, обновляют ли люди приложение вообще?

Косвенно, через видимость, а не убеждение. Большинство пользователей обновляются автоматически и никогда не читают заметки перед обновлением; заметки важнее всего для меньшинства, которое проверяет обновления вручную, и для рецензентов или прессы, просматривающих историю листинга магазина. Писать для этой меньшей аудитории всё равно окупается, потому что листинг с реальной историей конкретных, датированных записей читается как активно поддерживаемое приложение, а листинг с годом «исправлений ошибок и улучшений производительности» — нет, независимо от того, сколько реально было выпущено за это время.

А как насчёт принудительного обновления, где заметка должна объяснить, почему у пользователя нет выбора?

Укажите причину и срок в первой строке, прежде всего остального, потому что принудительное обновление — единственный случай, когда читатель уже раздражён до того, как начал читать. «Это обновление необходимо для продолжения синхронизации ваших данных. Обновите до [дата], чтобы избежать перебоев» говорит, что делать и почему, в одном предложении; похоронить эту причину под тремя строками несвязанных заметок о функциях читается так, будто приложение прячет неудобную часть.

FAQ

Должны ли мобильные release notes совпадать с веб-changelog того же релиза? Покрывать те же лежащие в основе изменения, но не слово в слово. Веб-changelog может позволить себе полное объяснение; мобильной заметке нужны те же факты, сжатые в предложение с глаголом первым, что обычно означает переписывание, а не копирование.

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

Какой длины должна быть мобильная release note, если нет лимита, вынуждающего к краткости? Всё равно короткой. Потолок в 4000 символов на iOS редко бывает реальным ограничением; им является предпросмотр в 2-3 строки, и писать дальше того, что показывает этот предпросмотр, просто значит, что меньше людей прочитают ту часть, которая имела значение.

Нужен ли release notes номер версии в видимом тексте? Нет. Магазин уже показывает номер версии рядом с заметками. Повторение его в тексте тратит видимые символы на информацию, которая у читателя уже перед глазами.

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

Mon, 07 Sep 2026 00:00:00 GMT

Монорепозиторий вмещает несколько отдельно выпускаемых вещей в одном репозитории, и changelog должен сначала ответить на вопрос: читателю важен репозиторий или конкретный пакет внутри него? Большинство команд никогда не решают это осознанно. Они начинают с одного changelog, потому что есть один репозиторий, добавляют пакеты со временем и заканчивают журналом, где пользователю CLI приходится пролистывать сорок несвязанных записей бэкенда, чтобы найти ту, что выпустила его исправление. Правильную форму определяет не структура репозитория, а то, кто читает журнал и что он уже знает искать.

Чем changelog монорепозитория отличается от changelog единого репозитория?

У changelog единого репозитория есть подразумеваемая аудитория — все, кто пользуется единственной вещью, которую строит этот репозиторий. Аудитория монорепозитория делится по пакетам, и пакеты в одном репозитории часто выпускаются по разным графикам, для разных потребителей, на разных уровнях стабильности. Библиотека, опубликованная в реестре, и внутренний административный инструмент могут жить в одном монорепозитории и почти не иметь ничего общего для читателя changelog.

Форма репозитория	Типичный читатель	Подходящий changelog
Одно выпускаемое приложение	Все, кто пользуется продуктом	Один журнал, для всего репо
Workspace библиотек (несколько публикуемых пакетов)	Кто зависит от конкретного пакета	Один журнал на пакет
Приложение плюс внутренние инструменты	Две разные аудитории без пересечения	Разделено по аудитории, не по папке
Приложение плюс собственный SDK	Пользователи продукта и интеграторы SDK	Два журнала: для продукта, для SDK

Нужен ли каждому пакету собственный changelog?

Только тем, у кого независимая аудитория. Пакету, публикуемому в реестре, нужен собственный журнал, потому что у устанавливающего его человека нет причин читать что-то ещё в репозитории, а инструменты релиза для монорепозиториев, такие как Lerna и Changesets, пишут CHANGELOG.md для каждого пакета рядом с его package.json. Внутренней утилите с одним потребителем — приложением, уже живущим в том же репозитории, — отдельный журнал не нужен; включение её изменений в записи этого приложения полезнее второго файла, который никто за пределами команды не открывает.

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

Как узнать, какой пакет вызвал какую запись changelog?

Помечай каждую запись её пакетом в момент написания, а не позже, изучая, какие файлы затронул коммит. Коммит, исправляющий общую внутреннюю библиотеку, может породить запись changelog в каждом пакете, зависящем от неё, и одни пути файлов не скажут, какую из этих нижестоящих записей читателю действительно нужно увидеть; это может решить только человек, определяющий "это видно пользователю пакета A и не видно пользователю пакета B". Conventional commits помогают здесь механически, называя пакет в каждом коммите, но scope всё равно даёт лишь черновик. То же правило двух слоёв из той статьи применяется по пакету: черновик с правильным scope всё равно нуждается в человеческом проходе, прежде чем он сформулирован для реального читателя этого пакета.

Что нужно общему changelog, чего не нужно changelog единого репозитория?

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

## 2026-09-07

### [cli] Добавлено
- `acme push --dry-run` показывает, что было бы отправлено,
  не отправляя это на самом деле.

### [core] Исправлено
- Backoff повторных попыток больше не сбрасывается при успешном
  запросе, возвращающем пустое тело.

Две записи, две аудитории, один взгляд, чтобы их различить. Рабочий процесс в стиле Changesets встраивает эту маркировку прямо в процесс релиза: контрибьютор пишет короткую заметку со scope пакета рядом со своим изменением, а инструмент собирает changelog по пакетам и скачки версий из этих заметок в момент релиза, вместо попытки восстановить границы пакетов постфактум из объединённой истории коммитов.

Как версионирование связано с changelog монорепозитория?

Независимо версионируемым пакетам нужен собственный changelog, потому что у них собственный номер версии, и общий changelog не может выразить "пакет A перешёл с 2.1 на 2.2, пока пакет B остался на 1.4", не превратившись в два журнала внутри одного файла. Semantic versioning и ваш changelog разбирает, как номер версии должен маппиться на категории changelog; в монорепозитории это соответствие нужно применять по пакету, потому что breaking change в одном пакете не является breaking change для соседнего пакета, который от него не зависит.

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

Как git-теги вписываются в монорепозиторий?

То же правило из git-тегов, релизов и вашего changelog применяется по пакету: пакету с собственной версией нужен собственный префикс тега, обычно имя-пакета@1.4.0 вместо голого v1.4.0, который не может сказать, какому пакету он принадлежит. Монорепозиторий, помеченный только голыми номерами версий, не может позже ответить "что было в core, когда cli выпустил 2.2", потому что ничто на диске не фиксирует, какому пакету на самом деле принадлежал этот тег.

FAQ

Нужен ли отдельный changelog для каждого пакета в монорепозитории? Только для пакетов с независимой аудиторией, обычно для всего, что публикуется в реестре. Пакет с одним внутренним потребителем, уже живущим в том же репозитории, может войти в журнал этого потребителя вместо ведения собственного.

Что помечает запись changelog правильным пакетом? Человек, пишущий запись, в момент её написания, а не автоматическое сканирование изменённых путей файлов. Изменение в общей библиотеке может породить разную запись в каждом зависящем от неё пакете, и только человек может решить, что на самом деле должна говорить каждая из этих нижестоящих записей.

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

Заменяет ли инструмент changelog для монорепозитория этап человеческого редактирования? Нет. Инструменты вроде Changesets автоматизируют сбор и сборку заметок по пакетам в момент релиза; сама заметка, написанная на языке читателя, а не контрибьютора, остаётся работой человека, как и в любом другом pipeline changelog.

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

Mon, 07 Sep 2026 00:00:00 GMT

Большинство анонсов функций умирает в канале, который никто не читает дважды: твит, пролетевший мимо, письмо дня релиза, погребённое под двенадцатью другими, которые подписчица получила на той неделе, сообщение в Slack в канале, который половина команды заглушила месяцы назад. Функцию выпустили. Почти никто из тех, кто бы ей пользовался, об этом не узнал. Исправить это — меньше о написании лучшего анонса, и больше о выборе правильного канала для правильной читательницы, и о том, чтобы напрямую достучаться до тех, кто явно об этом просил, вместо того чтобы полагаться на то, что они заметят общее сообщение.

Где на самом деле должна анонсироваться новая функция?

В более чем одном месте, потому что «все читают один и тот же канал» никогда не бывает правдой. Запись changelog или feed обслуживает читательницу, которая проверяет по собственному расписанию и хочет постоянную, датированную запись. Уведомление в приложении обслуживает читательницу, которая уже пользуется продуктом и воспользовалась бы функцией сегодня, если бы знала о её существовании. Письмо обслуживает читательницу, которая сейчас не в продукте, но вернулась бы ради нужного обновления. Соцсети обслуживают охват за пределами существующих пользователей, почти без таргетинга.

Канал	Лучше всего для	Слабость
Changelog / feed	Постоянная запись; читательницы своего темпа	Пассивен; бесполезен для тех, кто никогда не проверяет
Уведомление в приложении	Уже присутствующие пользователи, готовые действовать сегодня	Не достигает никого, кто сейчас не в системе
Письмо	Неактивные пользователи, вернувшиеся бы ради этого	Легко теряется среди другой почты; нужна настоящая тема
Соцсети	Охват за пределами текущих пользователей	Почти без таргетинга; короткий срок жизни

Ни один из четырёх не достаточен сам по себе. Changelog — единственный документ, который должен нести каждый релиз независимо от размера, потому что это запись, к которой всё остальное отсылает обратно; остальные три — усиление, добавленное сверху, выбираемое по тому, насколько функция действительно велика.

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

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

Конкретика перед прилагательными. «Более быстрый, более мощный опыт работы с отчётами» не говорит читательнице ничего, на что можно среагировать; «отчёты теперь загружаются меньше чем за секунду и могут фильтроваться по статусу» говорит точно, что изменилось и что попробовать. Вторая версия также выглядит более убедительно, потому что расплывчатое заявление звучит именно так, как звучит маркетинговый текст, когда сказать конкретно нечего.

Чем это отличается от письма с обновлением продукта?

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

Как добраться до конкретных людей, которые об этом просили?

Это анонс с лучшим соотношением усилий и отдачи, и почти все команды его пропускают. Если десять клиентов запросили функцию по имени, эти десять человек заслуживают прямую, личную заметку в момент выпуска, независимо от того, какой более широкий анонс выходит. Замыкание цикла обратной связи с клиентом разбирает механику целиком; резюме здесь в том, что это работает только если исходный запрос остался связан с попросившим, что скорее проблема отслеживания, чем проблема анонса. В changeloop, когда отзыв из виджета стал GitHub issue, а объединённый pull request его закрывает (fixes #142), одобрение записи changelog один раз публикует в этом issue комментарий «Shipped — », ссылающийся обратно на живую запись, а человек, отправивший отзыв, видит выпущенную запись в виджете. Никому не нужно вспоминать, что надо ему сказать. Issue, созданные вручную, и репозитории GitLab или Bitbucket такого комментария не получают.</p> <h2>Как написать саму запись?</h2> <p>Та же дисциплина, что и в любой другой записи release notes: начать с того, что читательница теперь может делать, продолжить нужной настройкой, пропустить внутреннее обоснование. <a href="https://changeloop.dev/blog/ru/how-to-write-release-notes/">Как писать release notes</a> разбирает полный метод; анонс новой функции — случай с самой высокой ставкой, потому что это запись, наиболее вероятно заскриншоченная, переслана и прочитана кем-то, кто никогда не видел changelog продукта.</p> <h2>Когда не стоит анонсировать широко?</h2> <p>Когда функция ещё раскатывается на подмножество аккаунтов, действительно является бетой, или имеет цену или ограничение доступа такие, что девять из десяти читательниц широкого анонса ещё не смогли бы ею воспользоваться. Широкий анонс функции, которой девять из десяти читательниц не могут воспользоваться, читается как приманка, и сжигает доверие к следующему анонсу больше, чем создаёт энтузиазм к этому. Решение — не тишина, а масштаб: напрямую сообщить подходящим аккаунтам и придержать широкие каналы, пока доступность не догонит анонс.</p> <h2>FAQ</h2> <p><strong>Заслуживает ли каждая новая функция собственный анонс?</strong> Каждая заслуживает запись changelog. Только достаточно значимые, чтобы изменить то, как кто-то пользуется продуктом, или явно запрошенные по имени, заслуживают более широких каналов вроде письма или соцсетей.</p> <p><strong>Какой канал лучший для небольшой функции?</strong> Только changelog, плюс уведомление в приложении, если функцию можно обнаружить в потоке, где пользователь уже находится. Письмо и соцсети того стоят для функций, оправдывающих просьбу внимания.</p> <p><strong>Как анонсировать функцию людям, которые именно её просили?</strong> Держать запрос связанным с попросившим с момента регистрации, затем уведомлять индивидуально при выпуске, отдельно от любого более широкого анонса. Общая метка статуса, которую попросивший может проверить сам, тоже снижает, сколько индивидуальных сообщений нужно в принципе.</p> <p><strong>Нужен ли анонсу функции скриншот?</strong> Для всего визуального — да; описанную, но не увиденную функцию пропускают гораздо чаще, чем ту, для которой читательницы могут увидеть превью. Для API или backend-возможности короткий пример кода делает ту же работу, что скриншот для изменения UI.</p> </article> <article> <h1>Как приоритизировать растущий поток запросов на функции</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Отслеживание запросов на функции решает вопрос, где они живут. Оно не решает, какой выйдет первым, и именно на этом втором вопросе команды реально застревают. Бэклог из трёхсот сгруппированных, помеченных запросов всё равно нуждается в правиле решения, потому что "строй самое запрашиваемое" работает только пока два запроса близки, а у третьего есть громкая сторонница — а так бывает большинство недель. Фреймворки ниже — не конкурирующие ответы на один вопрос. Каждый подходит своему типу запроса, и использовать один для всех — обычно и есть настоящая ошибка.</p> <h2>Чем приоритизация запросов на функции отличается от приоритизации roadmap?</h2> <p>Решение по roadmap начинается со стратегии и спрашивает, что строить. Решение по запросу на функцию начинается с уже существующего спроса и спрашивает, действовать ли на его основе, и эти два подхода достаточно часто тянут в разные стороны, что запрос может иметь высокий спрос и всё равно быть неправильным для постройки, или иметь низкий спрос и всё равно того стоить, потому что открывает стратегический аккаунт. Обращение с каждым запросом как с голосом за roadmap пропускает эту проверку.</p> <table> <thead> <tr> <th>Фреймворк</th> <th>Что взвешивает</th> <th>Где ломается</th> </tr> </thead> <tbody><tr> <td>Грубый счёт запросов</td> <td>Сколько людей просили</td> <td>Награждает запоминающиеся названия, а не реальный спрос</td> </tr> <tr> <td>RICE</td> <td>Охват, влияние, уверенность, усилие</td> <td>Нужны оценки, которых ни у кого нет для свежего запроса</td> </tr> <tr> <td>Взвешенный по доходу</td> <td>Кто просил, по ценности аккаунта</td> <td>Игнорирует запросы от аккаунтов, которые пока немного стоят</td> </tr> <tr> <td>Публичные голоса</td> <td>Видимый сигнал с низким усилием</td> <td>Достигает только пользователей, уже знающих, куда смотреть</td> </tr> </tbody></table> <h2>Что такое RICE, и работает ли он для запросов на функции?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> оценивает идею по охвату, влиянию, уверенности и усилию, затем делит первые три на четвёртое, чтобы получить сравнимое число. Он был создан для идей roadmap, в которые команда уже верит, где сложная часть — сравнивать разные ставки друг с другом. Запросы на функции уже приходят с числом охвата — счётом людей, попросивших об этом, — что конкретнее, чем охват, который обычно есть у свежей идеи roadmap. Место, где RICE напрягается с запросом, — уверенность и влияние: команда может быть уверена, что запрос реален, и всё же не иметь основы, насколько сильно он сдвинет метрику, потому что "влияние" для запроса, у которого уже есть название и след реальных пользователей, — это другой тип оценки, чем влияние идеи, которую никто за пределами комнаты ещё не видел.</p> <p>Используй RICE для запросов, которые серьёзно рассматриваются и ещё не решены. Не применяй его к каждому входящему запросу; усилие на оценку окупается только на тех, что достаточно близки, чтобы нужен был тайбрейкер.</p> <h2>Взвешивать по доходу, или по тому, кто просил?</h2> <p>По тому, кто просил, но не только по доходу. Аккаунт, близкий к продлению, аккаунт, уже эскалировавший ранее, и аккаунт, чей запрос открывает текущую сделку, несут срочность, которую плоская цифра дохода одна не улавливает, и запрос от пробной регистрации всё равно может иметь значение, если он блокирует решение, которое скоро станет доходом. Взвешивание по доходу — самое простое для расчёта из всех этих подходов, и именно поэтому его легче всего переоценить: оно корректно убирает шум от аккаунтов без реальной ставки, и так же легко может понизить запрос, который привёл бы гораздо больший аккаунт, всё ещё находящийся в pipeline.</p> <h2>Какую роль на самом деле играют голоса?</h2> <p>Дешёвый, непрерывный сигнал для уже существующих запросов, и плохой способ узнать, какие запросы вообще должны существовать. Счёт голосов достигает только пользователей, уже нашедших запрос и посчитавших его достойным клика, а это значит, что сумма голосов публичной roadmap отражает видимость не меньше, чем спрос: старый запрос ближе к верху списка продолжает собирать голоса отчасти потому, что его легко найти, а более новый, столь же реальный запрос начинает с нуля. Статья о <a href="https://changeloop.dev/blog/ru/public-roadmap/">публичной roadmap</a> предлагает вообще не показывать голоса на roadmap. Относись к голосам как к сигналу, который нужно группировать и взвешивать по свежести, а не как к рейтингу, который строят по порядку. <a href="https://changeloop.dev/blog/ru/feedback-signal-quality/">Тикеты поддержки vs. запросы функций</a> разбирает другое слепое пятно в счёте голосов: реальный разрыв может генерировать почти никаких голосов, если сталкивающиеся с ним пользователи никогда не находят доску, при этом громко проявляясь в поддержке.</p> <h2>Когда побеждает самый громкий клиент, и это проблема?</h2> <p>Иногда, и это проблема только когда никто этого не замечает. Клиент, часто эскалирующий, пишущий подробные тикеты или имеющий прямую линию с кем-то из команды, увидит свои запросы рассмотренными быстрее, чем более тихий клиент с не менее обоснованным запросом, и процесс приоритизации, никогда это не проверяющий, будет систематически благоволить самому настойчивому, а не тому, у кого дело сильнее. Громкие клиенты — не проблема, которую нужно исправлять; их запросы часто действительно важны. Исправление — это привычка: периодически проходить бэклог по источнику и проверять, объясняет ли одна и та же горстка аккаунтов большинство недавно выпущенного, и спрашивать себя, совпадает ли это с тем, где реальный спрос на самом деле находится.</p> <h2>Как решение о приоритизации превращается в ответ?</h2> <p>Каждое решение здесь порождает победителей и проигравших, и оба заслуживают ответа, называющего реальную логику, а не просто смену статуса без объяснения. <a href="https://changeloop.dev/blog/ru/declining-feature-requests/">Как отказать в запросе на функцию</a> разбирает, что говорить проигравшему запросу, способом, сохраняющим отношения нетронутыми, вместо того чтобы звучать как типовой отказ. Работа по группировке и маркировке, делающая всё это возможным с самого начала, разобрана в <a href="https://changeloop.dev/blog/ru/feature-request-tracking/">отслеживании запросов на функции</a>; приоритизация работает только на запросах, уже зарегистрированных и сгруппированных достаточно хорошо, чтобы их можно было сравнивать.</p> <h2>FAQ</h2> <p><strong>Какой фреймворк лучше всего подходит для приоритизации запросов на функции?</strong> Ни один сам по себе. Используй грубые счета, чтобы найти самый громкий сигнал, RICE — чтобы сравнить короткий список серьёзных кандидатов, и проверку по доходу или аккаунту — чтобы поймать случаи, когда тихий спрос от стратегического аккаунта перевешивает более громкую, но менее важную группу.</p> <p><strong>Стоит ли приоритизировать запросы на функции так же, как идеи roadmap?</strong> Нет. Идеи roadmap начинаются со стратегии; запросы на функции начинаются с уже существующего спроса. Оценивая их вместе, хорошо обоснованная стратегическая ставка с небольшим существующим спросом стабильно проигрывает запросу, у которого просто больше людей его попросили.</p> <p><strong>Точно ли голоса на публичной roadmap отражают спрос?</strong> Только среди людей, уже нашедших запрос. Более старые, более заметные запросы собирают голоса быстрее, независимо от того, сколько реального спроса стоит за более новым, так что относись к суммам голосов как к сигналу, сгруппированному и взвешенному по свежести, а не как к рейтингу, который строят по порядку.</p> <p><strong>Как часто нужно пересматривать приоритеты запросов на функции?</strong> По фиксированному циклу, а не только когда кто-то эскалирует. Ежемесячный или ежеквартальный проход, перегруппирующий запросы и перепроверяющий взвешивание, ловит дрейф — вроде горстки аккаунтов, доминирующих в том, что выпускается, — который чисто реактивный процесс никогда не выявляет сам.</p> </article> <article> <h1>Enterprise release notes: что меняется для одного аккаунта</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Публичный SaaS-продукт отправляет одни и те же release notes всем, потому что все на одной версии. Enterprise-клиент на закреплённой версии, выделенном инстансе, или подмножестве продукта с feature-флагами ломает это предположение: release notes, описывающие, что изменилось для него, не те же, что в вашем публичном блоге, а отправка публичных всё равно либо путает клиента изменениями, которых у него ещё нет, либо, хуже, рассказывает ему о функции, о которой команда работы с аккаунтом другого enterprise-клиента явно попросила вас придержать для их аккаунта ещё месяц. <a href="https://changeloop.dev/blog/ru/release-notes-best-practices/">Лучшие практики release notes</a> разбирает общее ремесло; это о том, как писать enterprise release notes для проблемы калибровки, возникающей, когда у вас есть клиенты, не все на одной сборке.</p> <h2>Почему enterprise-клиент не может просто читать публичный changelog?</h2> <p>Потому что он описывает версию, которую клиент, возможно, ещё не запускает, функции, к которым у него, возможно, нет доступа, и график, не совпадающий с его собственным. Клиент, закреплённый за квартальным циклом релизов, читающий о функции, вышедшей для публичного уровня на прошлой неделе, не может узнать, только из публичного changelog, доберётся ли эта функция до него на следующей неделе или в следующем квартале. Публичный changelog отвечает на «что изменилось в продукте»; реальный вопрос enterprise-клиента — «что изменилось в версии, которую я запускаю, и когда я получу остальное», на что публичный changelog никогда не был написан отвечать.</p> <h2>Что нужно приватной release note, что не нужно публичной?</h2> <p>Идентификатор версии или окружения, против которого клиент может реально сверить, и явное заявление о том, что до него ещё не дошло. «Этот релиз включает улучшения массового экспорта из нашего публичного релиза 4.3, но не новую модель разрешений, которая появится в вашем следующем запланированном обновлении» говорит enterprise-администратору точно, где находится его инстанс относительно продукта в целом. Публичной release note такое обрамление никогда не нужно, потому что есть только один инстанс, относительно которого можно быть; приватная бессмысленна без него.</p> <table> <thead> <tr> <th>Публичные release notes</th> <th>Приватные (enterprise) release notes</th> </tr> </thead> <tbody><tr> <td>Одна версия, одна аудитория</td> <td>Несколько версий, сегментированные аудитории</td> </tr> <tr> <td>Предполагает, что у читательницы есть каждая описанная функция</td> <td>Должна заявлять, что есть, а чего нет у читательницы</td> </tr> <tr> <td>Синхронизированы с публичным релизом</td> <td>Синхронизированы с собственным окном обновления клиента</td> </tr> <tr> <td>Можно сразу сделать полностью публичной</td> <td>Может понадобиться скрыть пункты, которых у других клиентов ещё нет</td> </tr> </tbody></table> <h2>Бывает ли когда-нибудь нормально просто отложить отправку публичных release notes enterprise-клиентам вместо написания отдельных?</h2> <p>Только если его версия действительно совпадает с публичной в этот момент, что реже, чем кажется, как только у вас больше пары enterprise-аккаунтов на разных ритмах. Откладывание публичных заметок работает как временное решение для клиента, отставшего на одну версию и готового наверстать; это рушится в момент, когда два enterprise-клиента находятся на разных версиях друг относительно друга, потому что тогда нет уже единых «заметок» для откладывания, только матрица того, что есть у каждого. В этот момент калибровка заметок по аккаунту, даже если это лишь отфильтрованный вид тех же лежащих в основе записей, перестаёт быть опциональной.</p> <pre><code>Публичные заметки, отправленные enterprise-аккаунту, у которого ещё нет функции: "New: Bulk export now supports custom column ordering." (Путаница: админ пробует, а функции нет.) Откалиброванные enterprise-заметки для того же аккаунта: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Кто внутри организации клиента реально это читает, и меняет ли это способ написания?</h2> <p>Обычно IT-администратор или контакт по customer success, а не конечный пользователь, и это меняет, что считается полезным. Конечному пользователю важно, что выглядит иначе на его экране; enterprise-администратору важно, что изменилось в разрешениях, обработке данных, конфигурации SSO, или что-либо, влияющее на то, как она управляет развёртыванием для собственных пользователей, потому что именно она будет отвечать на внутренние вопросы. Приватная release note, читающаяся как потребительский changelog, все сверкающие новые кнопки и никакой операционной детали, заставляет администратора копать в поисках информации, которая реально была нужна.</p> <h2>Как это взаимодействует с публичной roadmap или публичным changelog, уже перечисляющим ту же функцию?</h2> <p>Осторожно, потому что клиент, читающий оба, заметит любую несостыковку. Если ваш публичный changelog уже объявил функцию, которой у конкретного enterprise-аккаунта ещё нет, его приватная release note должна признать этот разрыв, а не притворяться, что публичной записи не существует; администратор, видевший публичное объявление и получающий приватные заметки, игнорирующие это, предположит либо что вы о ней забыли, либо что что-то сломано. <a href="https://changeloop.dev/blog/ru/public-roadmap/">Публичная roadmap</a> разбирает, как сохранять roadmap честной насчёт того, что выпущено против запланированного; enterprise-версия этой честности в release notes — прямо называть разрыв между тем, что публично, и тем, что принадлежит ей.</p> <h2>Нужна ли маленькой компании всего с одним-двумя enterprise-клиентами вся эта структура?</h2> <p>Не полностью сегментированная система, но базовая дисциплина, ясно заявлять, на какой версии находится клиент и что у него есть и чего нет, важна на любом масштабе в момент, когда у вас есть хотя бы один клиент не на вашей последней сборке. Режим сбоя, который это предотвращает, администратор, запутавшийся, относится ли к ней публичное объявление, стоит тикета поддержки и удара по доверию независимо от того, есть ли у вас два enterprise-аккаунта или двести.</p> <h2>FAQ</h2> <p><strong>Должны ли приватные release notes когда-либо упоминать функции, которые уже есть у других клиентов, но нет у этого?</strong> Только если это релевантно его собственному графику, сформулировано как «появится в вашем следующем обновлении», а не как сравнение с другими клиентами. Называть, что есть у конкретного другого клиента, — территория, не ваша, чтобы раскрывать; называть, что придёт конкретно этому клиенту, — именно та информация, что ему нужна.</p> <p><strong>Могут ли одни и те же лежащие в основе записи changelog питать и публичные, и приватные release notes?</strong> Да, и это обычно более поддерживаемый подход: помечайте записи, к каким версиям или уровням они относятся, затем фильтруйте по аудитории при публикации вместо написания двух полностью отдельных документов, неизбежно расходящихся со временем.</p> <p><strong>Что, если enterprise-клиент явно просит быть на публичных release notes вместо приватной ленты?</strong> Уважьте это, но подтвердите, что он понимает, что публичные заметки предполагают публичную версию, и сами письменно отметьте разрыв, если его версия отличается от описанного. Это письменное подтверждение защищает вас позже, если он действует на основе публичных заметок, реально не применимых к его сборке.</p> <p><strong>Насколько заранее enterprise-клиента следует уведомить о функции, к которой у него будет доступ в следующем релизе?</strong> Как только дата подтверждена, а не только в момент релиза, потому что enterprise-администраторам часто нужно планировать собственную внутреннюю коммуникацию или обучение вокруг приближающейся функции, а уведомление в тот же день не оставляет им для этого пространства.</p> </article> <article> <h1>Semantic versioning и ваш changelog</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Semantic versioning говорит вызывающей стороне, насколько больно может быть от релиза, ещё до того, как она прочитает хоть одну запись changelog. Переход с <code>2.4.1</code> на <code>2.5.0</code> говорит: новая возможность, ничего не сломано. Переход с <code>2.5.0</code> на <code>3.0.0</code> говорит: прочитай эту запись перед обновлением. Changelog и номер версии должны утверждать одно и то же в двух форматах, и большая часть трения между ними всплывает именно тогда, когда они расходятся — а это случается чаще, чем предполагает спецификация.</p> <h2>Что на самом деле обещает каждая цифра версии?</h2> <p><a href="https://semver.org/">Semantic versioning</a> определяет три цифры, <code>MAJOR.MINOR.PATCH</code>, каждая со строгим правилом о том, что её запускает. Скачок MAJOR означает несовместимое изменение: то, что могла бы заметить корректная существующая интеграция, и из-за чего ей пришлось бы измениться. Скачок MINOR означает новую, обратно совместимую функциональность: ничего существующего не ломается, появляется что-то новое. Скачок PATCH означает обратно совместимое исправление: поведение приближается к задокументированному, и никто, намеренно полагавшийся на старое поведение, ничего не должен заметить.</p> <table> <thead> <tr> <th>Скачок</th> <th>Значение</th> <th>Запись должна звучать как</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Несовместимое изменение</td> <td>«Требуется действие перед обновлением»</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Новая, совместимая возможность</td> <td>«Доступно уже сейчас, больше ничего не изменилось»</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Совместимое исправление</td> <td>«Теперь ведёт себя так, как задокументировано»</td> </tr> </tbody></table> <p>Таблица работает и в обратную сторону как проверка: если запись не читается как её строка, значит либо номер версии неверен, либо запись занижает или завышает то, что произошло на самом деле.</p> <h2>Что считается несовместимым для целей версионирования?</h2> <p>Тот же тест, который решает, место ли чему-то в changelog API: могла бы корректная вызывающая сторона, написанная против старого поведения и с тех пор не тронутая, повести себя иначе из-за этого изменения. <a href="https://changeloop.dev/blog/ru/breaking-changes/">Что такое несовместимое изменение, и как его выпустить</a> разбирает решение целиком, включая случаи, которые выглядят несовместимыми, но не являются таковыми, и те, что выглядят мелкими, но не являются. Коротко для версионирования: если ответ да, скачок — MAJOR, независимо от того, сколько кода изменение на самом деле затронуло внутри. Номера версий отслеживают последствие для вызывающей стороны, а не усилие команды.</p> <h2>Как запись changelog должна соответствовать скачку версии?</h2> <p>Одна запись, одна категория скачка, заявленная сразу. Паттерн из таблицы продолжается напрямую: несовместимая запись стоит под версией, которая её ввела, сформулированная сначала как предупреждение, потом как описание. Дополняющая запись стоит под своей MINOR-версией, сформулированная как доступность. Исправление стоит под своей PATCH-версией, сформулированное как коррекция. Смешивание категорий в одной записи — например, вписывание несовместимого изменения в тот же абзац, что и несвязанное исправление — это способ, которым читательница упускает именно то единственное, что действительно имело значение.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` теперь возвращает суммы как целые числа в наименьшей денежной единице (копейках) вместо дробей. Обновите код, читающий `amount` напрямую. ## 2.9.0 (2026-09-01) ### Added - Отчёты теперь можно фильтровать по `status`. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=` возвращал пустую страницу вместо 400 для неизвестного статуса. </code></pre> <p>Читая сверху вниз, номер версии и метка раздела говорят одно и то же дважды — и это ровно та цель: читательница, просматривающая только заголовки, получает верное представление о риске ещё до открытия хоть одной строки.</p> <h2>Применяется ли правило о breaking changes так же и до 1.0.0?</h2> <p>Нет, и именно отсюда берётся большая часть путаницы «было ли это на самом деле breaking». SemVer прямо говорит, что нулевая мажорная версия, <code>0.y.z</code>, предназначена для начальной разработки: всё может измениться в любой момент, и публичный API не следует считать стабильным. Скачок с <code>0.4.0</code> на <code>0.5.0</code> может нести breaking change, не нарушая спецификацию, потому что гарантия мажорной версии начинает действовать только с выпуска <code>1.0.0</code>. Запись changelog по-прежнему обязана читателям той же честностью о том, что сломалось; меняется только то, что сам номер версии до 1.0.0 не является сигналом, на который стоит полагаться.</p> <h2>А если ваш продукт не выпускает дискретные версии?</h2> <p>Большинство SaaS-продуктов деплоятся непрерывно и никогда не показывают номер версии вызывающей стороне, что не отменяет потребность в этой дисциплине — только цифру, которая обычно бы её несла. Запись changelog должна проделать всю работу сама: чётко сказать, несовместимо ли изменение, дополняющее оно, или это исправление — теми же тремя словами, которыми пользуется semantic versioning, даже без поля версии, к которому их привязать. Некоторые команды держат чисто внутреннюю версию только для того, чтобы привязать записи changelog к чему-то, на что можно сослаться, никогда не показывая её напрямую вызывающей стороне.</p> <h2>Как это применяется именно к changelog API?</h2> <p>Строже, чем почти где-либо ещё, потому что вызывающие стороны API — это код, а не люди, способные пожать плечами на неожиданное изменение. <a href="https://changeloop.dev/blog/ru/api-changelog/">Changelog API: что публиковать и кто это читает</a> разбирает полную форму этого документа; дисциплина версионирования здесь — то, что держит честными его разделы breaking и additive. API, предлагающий несколько версий одновременно — например, <code>v1</code> и <code>v2</code>, обслуживаемые параллельно во время окна миграции — эффективно применяет semantic versioning в масштабе всего интерфейса, а не одного пакета, и тот же трёхсловный словарь всё ещё применяется к каждой записи.</p> <h2>Что Keep a Changelog говорит о версионировании?</h2> <p>Он напрямую связывается по имени с semantic versioning и рекомендует тот же словарь категорий, которым пользуется эта статья: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/ru/keep-a-changelog-implemented/">Keep a Changelog на практике</a> разбирает, как принять эту спецификацию, включая места, где команды обычно от неё отклоняются. Пересечение не случайно: обе спецификации пытаются решить одну и ту же проблему с противоположных концов — одна стандартизирует номер версии, другая — запись, которая его объясняет.</p> <h2>FAQ</h2> <p><strong>Нужен ли каждой записи changelog номер версии?</strong> Если продукт выпускает версии — да, потому что цифра позволяет читательнице сразу перейти к «насколько это меня касается», не читая сначала запись. Если продукт деплоится непрерывно без поля версии, формулировка записи должна нести этот сигнал сама.</p> <p><strong>В чём разница между скачком MAJOR и записью о несовместимом изменении?</strong> Они должны описывать одно и то же событие двумя способами. Номер версии — сигнал, читаемый машиной (инструменты вызывающей стороны могут на него реагировать); запись changelog — объяснение, читаемое человеком, что конкретно изменилось.</p> <p><strong>Может ли релиз PATCH быть несовместимым?</strong> По определению не должен. Если такой всё же вышел, не редактируйте и не перетегируйте опубликованную версию: <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">SemVer FAQ</a> советует выпустить новую версию, восстанавливающую совместимость, или новую MAJOR, если поломка остаётся, и задокументировать проблемную версию, чтобы пользователи знали, что её надо пропустить.</p> <p><strong>Нужен ли чисто внутренним изменениям скачок версии?</strong> Нет. Semantic versioning отслеживает публичный интерфейс. Рефакторинг без наблюдаемого эффекта для вызывающей стороны не нуждается ни в скачке, ни в записи changelog, даже если внутри это была значительная инженерная работа.</p> </article> <article> <h1>Заголовок Sunset у API и когда его отправлять</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> — это один заголовок ответа, определённый в <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, который сообщает вызывающему, когда ресурс перестанет отвечать. <a href="https://changeloop.dev/blog/ru/api-deprecation/">Депрекация API</a> разбирает полный график объявление-напоминание-brownout-удаление и уведомления, идущие вместе с ним; здесь — об одном машиночитаемом сигнале в этом графике, о том, что он на самом деле говорит, и о единственном случае, когда сам RFC советует его не отправлять.</p> <h2>Что говорит заголовок Sunset, а чего не говорит?</h2> <p>Он несёт одну HTTP-дату — момент, когда ресурс, как ожидается, перестанет отвечать:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>RFC называет это подсказкой, а не гарантией: он не обещает, что ресурс продолжит работать вплоть до этой отметки времени, и ничего не говорит о том, как будет выглядеть сбой после неё. Вызывающие могут получить 4xx, редирект или вообще ничего; заголовок это не различает. Дата, уже находящаяся в прошлом, означает «сейчас или в любой момент», а не ошибку в значении. Ничего из этого протокол не обеспечивает принудительно. Клиент, никогда не читающий заголовок, ведёт себя точно так же, как всегда, и узнаёт об исчезновении ресурса тем же способом, каким узнал бы в любом случае.</p> <h2>Когда его действительно стоит отправлять?</h2> <p>Только когда ресурс по-настоящему собирается перестать отвечать, а не когда он всего лишь перестал быть рекомендуемым выбором. RFC явно говорит, что депрекация проходит в две стадии, и поле заголовка Sunset относится только ко второй: во время первой стадии, объявления, что версия больше не предпочтительна, API остаётся полностью работоспособным, и заголовок там неприменим. Он применяется, когда версия действительно запланирована к остановке ответа.</p> <p>Это напрямую ложится на график депрекации: заголовок <code>Deprecation</code> отправляется с первого дня, на шаге объявления; <code>Sunset</code> описывает дату, когда старое поведение реально остановится, и это та же дата, которую <a href="https://changeloop.dev/blog/ru/api-deprecation/">график из четырёх шагов</a> называет удалением. Отправлять <code>Sunset</code> в первый день — не ошибка, раз дата уже зафиксирована к этому моменту, но отправлять его без предшествующего объявления депрекации, или указывать в нём версию, удаление которой вы на самом деле не подтвердили, сообщает вызывающим то, что вы сами ещё не решили.</p> <h2>Взаимодействует ли он с кэшированием?</h2> <p>Нет, и RFC говорит об этом прямо: <code>Sunset</code> и HTTP-кэширование решают не связанные друг с другом задачи, и их стоит читать как дополняющие, а не пересекающиеся. Заголовки кэширования говорят, когда безопасно переиспользовать закэшированную копию; <code>Sunset</code> ничего не говорит о текущем состоянии ресурса, только о том, что сам ресурс перестанет существовать. Ответ может быть полностью кэшируемым вплоть до момента своего sunset. Не используйте один заголовок как приближение другого и не считайте, что длинный <code>max-age</code> отменяет приближающуюся дату sunset, или наоборот.</p> <h2>Может ли один заголовок закрыть больше одного endpoint?</h2> <p>Заголовок применяется к ресурсу, который его вернул, но RFC позволяет сервису задокументировать более широкую область действия: дата Sunset на домашнем ресурсе API может быть определена как означающая, что уходит весь API, а не только этот один URL. Загвоздка в том, что это работает только для вызывающих, уже знающих ваше правило области действия. Вызывающий, читающий заголовок буквально, видит sunset только на том одном ресурсе, который запросил, и ничего больше, так что более широкую область действия нужно где-то записать так, чтобы вызывающий мог это найти, а не подразумевать.</p> <h2>Что должно идти вместе с заголовком?</h2> <p>Ссылка на то, где объяснено удаление. RFC 8594 регистрирует собственное отношение ссылки <code>sunset</code> именно для этого: указание на ресурс, описывающий политику удаления, предстоящую дату или способ миграции, отдельно от голой отметки времени в заголовке.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Направив эту ссылку на свои собственные <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> или отдельную страницу миграции, вы превращаете заголовок, который почти ничей клиентский код не проверяет, в нечто, что человек, действительно решивший поискать, находит немедленно. Скомбинируйте его с отношением <code>successor-version</code> из <a href="https://changeloop.dev/blog/ru/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">заголовков депрекации</a>, и вызывающий получает из одного только ответа и куда идти, и чем это заменяется.</p> <h2>Как это выглядит целиком?</h2> <p>Допустим, <code>v1</code> уходит 1 марта 2027 года. Объявление о депрекации в первый день добавляет <code>Deprecation</code> и <code>Link: rel="successor-version"</code> к каждому ответу <code>v1</code>, согласно <a href="https://changeloop.dev/blog/ru/api-deprecation/">заголовкам депрекации</a>, но откладывает <code>Sunset</code> до момента, когда дата удаления по-настоящему зафиксирована, а не является заглушкой. Как только это происходит, каждый ответ <code>v1</code> несёт:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Шлюз или мониторинг вызывающего может независимо реагировать на любой из заголовков: <code>Deprecation</code> говорит, что существует более новая версия, <code>Sunset</code> — что у этой есть свои часы. Ни один из заголовков не обязан меняться до 1 марта; меняется сам ответ, в этот день и во время любых запланированных перед ним окон brownout.</p> <h2>Меняет ли brownout то, что говорит заголовок?</h2> <p>Само значение заголовка не обязано сдвигаться из-за запланированного brownout: дата sunset остаётся датой sunset независимо от того, отказывает ли ресурс с перебоями до неё. Меняется ответ, а не заголовок. Планирование коротких окон <code>410 Gone</code> за недели до объявленной даты, как описывает <a href="https://changeloop.dev/blog/ru/api-deprecation/">Депрекация API</a>, — это то, что превращает первый контакт вызывающего со сбоем в репетицию, а не в реальность в день, когда наступает дата из заголовка.</p> <h2>FAQ</h2> <p><strong>Действительно ли какие-то реальные HTTP-клиенты или инструменты читают заголовок Sunset?</strong> На стороне клиента — редко. Его ценность в основном для того, кто управляет инфраструктурой между вами и вызывающим: API-шлюз или инструмент мониторинга, настроенный следить за этим заголовком, может оповестить вашу собственную команду или команду партнёра задолго до того, как код вызывающего вообще что-то заметит. Относитесь к нему как к сигналу, под который вы строите инструментарий, а не как к тому, что у другой стороны уже наверняка есть.</p> <p><strong>Это то же самое, что <code>Cache-Control: max-age</code>?</strong> Нет. <code>max-age</code> о том, как долго закэшированная копия остаётся валидной; <code>Sunset</code> о том, когда ресурс вообще перестаёт существовать. Ответ может нести короткий <code>max-age</code> и дату <code>Sunset</code> через годы, или наоборот, и ни один из заголовков не ограничивает другой.</p> <p><strong>Можно ли отправить Sunset для одного исчезающего поля, а не всего endpoint?</strong> Нет, заголовок привязан к ресурсу, то есть к URL, а не к полю внутри тела ответа. Для поля, параметра или значения enum, которое уходит, пока сам endpoint остаётся, используйте вместо этого заголовок <code>Deprecation</code> и запись в changelog; <a href="https://changeloop.dev/blog/ru/api-deprecation/">Депрекация API</a> разбирает объявление именно такого рода изменений.</p> <p><strong>Что если дату sunset нужно сдвинуть?</strong> Обновите значение заголовка и скажите об этом в записи changelog, объявившей её изначально; тихая смена опубликованной даты — это то, как вызывающий решает, что ни одна из ваших дат не реальна. RFC описывает это значение как подсказку именно потому, что даты иногда действительно сдвигаются, но сдвинутая дата без объяснения будет стоить вам доверия и к следующей.</p> </article> <article> <h1>Changelog вебхуков: breaking change, который никто не просил</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Changelog REST API существует потому, что вызывающий может отклонить ответ, который не понимает, или хотя бы залогировать ошибку достаточно громко, чтобы кто-то заметил. Получатель вебхука редко делает то или другое. Он получает POST, читает ожидаемые поля, и если поле переместилось, сменило тип или исчезло, эндпоинт либо тихо падает внутри фонового job'а, за которым никто не следит, либо, хуже, продолжает работать с неверным значением, которое никогда не валидировал. <a href="https://changeloop.dev/blog/ru/breaking-changes/">Что такое breaking change</a> разбирает общее определение; payload вебхука нуждается в собственном ответе, потому что режим отказа отличается от эндпоинта, который кто-то вызывает намеренно.</p> <h2>Почему изменение payload вебхука ломается иначе, чем изменение ответа API?</h2> <p>Потому что направление запроса перевёрнуто. Вызывающий REST инициирует вызов и может добавить заголовок версии, повторить попытку при 4xx или прочитать уведомление об устаревании в ответе. Получатель вебхука ничего из этого не инициировал: ваш сервер решил отправить, решил когда, и решил, какую форму будет иметь тело. Единственный рычаг получателя — валидация, которую он написал, когда строилась интеграция, а большинство интеграций строятся один раз, работают, и никто их не пересматривает, пока они не сломаются. Эта асимметрия — вся причина, почему изменение payload вебхука заслуживает больше осторожности, чем то же изменение в теле ответа, которое вызывающий активно запросил.</p> <h2>Что на самом деле считается breaking change в payload вебхука?</h2> <table> <thead> <tr> <th>Изменение</th> <th>Breaking для большинства получателей</th> </tr> </thead> <tbody><tr> <td>Добавление нового поля</td> <td>Нет, если получатели игнорируют неизвестные поля (проверьте это предположение, не принимайте его на веру)</td> </tr> <tr> <td>Удаление поля</td> <td>Да, если что-то его читает</td> </tr> <tr> <td>Переименование поля</td> <td>Да, функционально идентично удалению старого</td> </tr> <tr> <td>Изменение типа поля (строка в объект)</td> <td>Да, почти всегда</td> </tr> <tr> <td>Изменение порядка полей в теле JSON</td> <td>Нет, для любого получателя, парсящего по ключу, а такими должны быть все</td> </tr> <tr> <td>Изменение имени или типа события</td> <td>Да, если получатели фильтруют или маршрутизируют по нему</td> </tr> </tbody></table> <p>Строка «добавление поля безопасно» — та, на которую команды опираются больше всего, и та, которую больше всего стоит проверить, а не предполагать. Разрешающий JSON-парсер по умолчанию игнорирует неизвестные поля, но получатель, десериализующий в строгую схему, несколько типизированных языков делают это без дополнительной настройки, может отклонить весь payload, как только появится неожиданное поле. Добавление поля безопасно для вашего вебхука только если вы знаете, как парсят получатели, а не потому что сам JSON разрешающий.</p> <h2>Как версионировать payload вебхука?</h2> <p>Почти как для ответа API, с одним нюансом: получатель никогда не отправляет запрос, поэтому не может попросить версию, и её должен указать отправитель. Её можно передать в теле или в заголовке запроса самой доставки; <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">доставки GitHub</a> несут <code>X-GitHub-Event</code> и <code>X-GitHub-Hook-ID</code>, а <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">спецификация Standard Webhooks</a> кладёт свои метаданные в заголовки <code>webhook-*</code>. Поле версии в payload (<code>"payload_version": 2</code>) — самый дешёвый вариант, и он работает, когда получатели готовы ветвиться по нему. Версионированный тип события (<code>invoice.updated</code> становится <code>invoice.updated.v2</code> как отдельное событие, на которое получатель подписывается добровольно) требует больше работы для построения, но означает, что старая форма продолжает поступать тем, кто никогда не мигрировал, что здесь важнее, чем для REST-эндпоинта, потому что вы не можете позвонить каждому получателю с просьбой обновиться. Настройка на подписку, выбранная при регистрации эндпоинта вебхука, принимает решение заранее вместо ветвления при каждой доставке, и это правильный выбор, когда у вас уже есть запись подписки, к которой можно её прикрепить.</p> <pre><code>POST /endpoint-получателя { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Как вообще узнать, кто слушает?</h2> <p>Хуже, чем эквивалентная версия этой проблемы в changelog API, потому что у вебхука нет журнала входящих запросов на вашей стороне, который называл бы вызывающего; у вас есть только собственный журнал исходящих доставок, который говорит, что эндпоинт получил 200, а не что он сделал с телом. Отслеживайте минимум две вещи: каждый зарегистрированный эндпоинт с владелицей, ту же дисциплину, что <a href="https://changeloop.dev/blog/ru/internal-api-changelog/">changelog внутренних API</a> рекомендует для внутренних потребителей, и вашу долю неудачных доставок на эндпоинт после изменения payload. Всплеск ответов 4xx или 5xx от эндпоинта сразу после изменения — ближайшее к трассировке стека, что вы получите, и часто единственный сигнал, что получатель сломался, потому что команда, которая им управляет, может не заметить это днями.</p> <h2>Должен ли changelog вебхуков быть отдельным от changelog API?</h2> <p>Отдельный раздел на той же странице, а не отдельная публикация. <a href="https://changeloop.dev/blog/ru/api-changelog/">Changelog API</a> уже устанавливает, кто его читает и как на него подписываются; изменение payload вебхука принадлежит той же ленте, помеченное достаточно ясно, чтобы разработчица на стороне получателя, сканирующая «затрагивает ли это мою интеграцию», могла отфильтровать по нему, потому что у потребителя вебхука часто нет другой причины проверять общий changelog API, и он найдёт его, только если кто-то направит его туда напрямую.</p> <h2>Как должно выглядеть разумное окно устаревания для payload вебхука?</h2> <p>Длиннее эквивалентного устаревания REST, потому что миграция на стороне получателя обычно означает, что вторая команда, с которой у вас может не быть прямой связи, должна заметить это, запланировать и выпустить без собственной срочности. Месяц — разумный минимум для поля, которое получатель, вероятно, всё ещё парсит разрешающей библиотекой; три месяца или больше безопаснее для удаления поля, которое строгая схема полностью отклонит. Отправляйте старую и новую форму вместе в течение окна, когда это возможно (старое поле <code>status</code> и его замена из версии 2 в одном payload), потому что получатель, читающий старое поле, продолжает работать, не трогая свой код, а тот, кто уже мигрировал, просто игнорирует поле, которое ему больше не нужно.</p> <h2>FAQ</h2> <p><strong>Должны ли потребители вебхуков подтверждать изменение payload перед публикацией?</strong> По умолчанию не существует механизма подтверждения, и именно поэтому окно устаревания важнее здесь, чем для REST API: никто не подтверждает готовность, поэтому окно должно быть достаточно длинным, чтобы большинство получателей мигрировали в своём темпе до исчезновения старой формы.</p> <p><strong>Безопасно ли когда-либо добавлять неизвестные поля без уведомления?</strong> Только после того, как вы проверили, а не предположили, что ваши получатели парсят разрешающе. Запись в changelog стоит недорого и убирает неопределённость; тихое добавление полей с предположением, что «JSON-парсеры игнорируют лишнее», ломает любого получателя со строгой десериализацией.</p> <p><strong>Какой самый быстрый способ обнаружить сломанного получателя вебхука после изменения payload?</strong> Доля неудачных доставок на эндпоинт, наблюдаемая в часы сразу после изменения. Она не скажет вам, что сломалось, только что что-то сломалось, но это самый ранний и часто единственный сигнал, который вы получите.</p> <p><strong>Помогает ли логика повторных попыток получателям пережить изменение payload?</strong> Нет. Повторная попытка отправляет тот же новый payload заново; она не возвращается к форме, которую получатель может распарсить. Изменение payload ломает получателя при первой доставке и при каждой последующей повторной попытке одинаково.</p> </article> <article> <h1>Changelog: что это такое, с примером записи</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Changelog — это датированная запись того, что изменилось в продукте, написанная для людей, которых затрагивает изменение, а не для команды, которая его выпустила. Каждая запись называет изменение, говорит, когда оно вступило в силу, и говорит, что читательница должна с этим делать — для большинства записей это ничего. Именно последняя часть отделяет changelog от журнала коммитов: журнал коммитов — это запись для тех, кто писал код, а changelog — запись для тех, кто им пользуется.</p> <h2>Что такое changelog, если точнее?</h2> <p>Список датированных записей, от новых к старым, каждая описывает одно изменение в терминах, которые читательница может проверить. Не то, что построила команда, а то, что теперь по-другому. «Рефакторинг сервиса биллинга» — это сообщение коммита. «Счета теперь показывают налог отдельной строкой» — это запись changelog, потому что она говорит читательнице что-то, что та может проверить на собственном аккаунте.</p> <p>Формат старый и намеренно простой: заголовок на релиз или на день, короткий список под ним, иногда метка категории. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> — самая цитируемая спецификация для этой формы, и существует она потому, что большинство проектов, минуя спецификацию, заканчивают тем, что вываливают историю коммитов вместо неё — а это отвечает на другой вопрос, чем тот, с которым пришла читательница.</p> <table> <thead> <tr> <th>Документ</th> <th>Написан для</th> <th>Отвечает на</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Всех, кто пользуется продуктом</td> <td>Что изменилось, и когда?</td> </tr> <tr> <td>Журнал коммитов</td> <td>Команды, писавшей код</td> <td>Что сделано, в каком порядке?</td> </tr> <tr> <td>Release notes</td> <td>Пользователей, решающих обновляться ли</td> <td>Что я теперь могу, чего не мог?</td> </tr> <tr> <td>Patch notes</td> <td>Игроков или пользователей конкретного фикса</td> <td>Что именно исправил этот релиз?</td> </tr> <tr> <td>Roadmap</td> <td>Всех, кто гадает, что дальше</td> <td>Что запланировано, и на какой стадии?</td> </tr> </tbody></table> <p>Эти пять пересекаются на практике, но это не один и тот же документ, и разница в том, кто держит его в руках в момент чтения. Changelog построен так, чтобы его искали и на него ссылались позже, поэтому его записям нужны стабильные даты и URL сильнее, чем остальным.</p> <h2>Что на самом деле входит в запись changelog?</h2> <p>Четыре вещи, в таком порядке: что изменилось, сформулированное в терминах того, что заметил бы пользователь или вызывающая сторона; когда это вступило в силу; к какой категории относится (added, fixed, changed, removed — четыре обычные); и, когда это важно, что читательница должна с этим сделать. Ссылка на подробности — это хорошо. Абзац внутреннего обоснования — нет, потому что читательница спросила не почему, а что.</p> <pre><code>## 2026-09-07 ### Added - Счета теперь показывают налог отдельной строкой, в валюте аккаунта клиента. ### Fixed - Экспорт отчёта в CSV больше не теряет последнюю строку, когда отчёт превышает 10 000 строк. </code></pre> <p>Эта форма масштабируется от обновления в две строки до сотни записей в релизе, не меняя структуры — и это настоящая проверка того, работает ли формат: читается ли он одинаково в загруженную неделю и в спокойную.</p> <h2>Кто пишет changelog, и когда?</h2> <p>Тот, кто внёс изменение, в момент выпуска — а не технический редактор, восстанавливающий его из тикетов неделю спустя. Тот, кто трогал код, знает, что на самом деле изменилось для пользователя; резюме, написанное задним числом, склонно описывать тикет вместо того, что реально выпустили, а это обычно шире или уже реального объёма. Некоторые команды добавляют шаг ревью перед тем, как запись станет публичной, в основном чтобы поймать просочившийся внутренний язык, и это ревью должно быть достаточно быстрым, чтобы запись вышла в тот же день.</p> <h2>Где место changelog?</h2> <p>На собственной странице, по стабильному URL, распространяемой как feed. Спрятанный в меню настроек или в теге релиза на хостинге кода, он доходит только до тех, кто уже знал, где искать. На публичную страницу можно сослаться из тикета поддержки, процитировать в обзоре или подписаться на неё. Feed важен не меньше страницы: читательница, проверяющая changelog продукта раз в месяц — редкость, подписанная на него — нет, и только feed обслуживает второй тип.</p> <h2>Чем он отличается от release notes?</h2> <p>Их постоянно путают, и они достаточно разные, чтобы смешивание давало документ, который плохо служит обеим читательницам. <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">Changelog против release notes</a> разбирает различие целиком; коротко — changelog это полная, хронологическая запись, а release notes — отобранное подмножество, написанное так, чтобы обновление звучало достойным внимания. Продукту обычно нужны оба, обращённые к разным моментам дня читательницы.</p> <h2>Что делает changelog стоящим прочтения?</h2> <p>Конкретность и честность о собственном охвате. «Разные исправления багов» — фраза, которая учит читательницу больше не открывать страницу, потому что не обещает ничего проверяемого. Запись, называющая точное изменившееся поведение, даже для мелкого фикса — та, что держит подписку живой. Эта дисциплина касается и того, что пропускают: changelog, объявляющий только победы и никогда — исправление того, что было сломано, читается как маркетинг под видом changelog, и читательницы это замечают.</p> <p>Дисциплина версионирования тоже важна. <a href="https://changeloop.dev/blog/ru/semantic-versioning-changelog/">Semantic versioning и ваш changelog</a> показывает, как номер версии и запись должны соответствовать друг другу, чтобы читательница, просматривая историю версий, получала один и тот же сигнал дважды, а не два разных.</p> <h2>Как генерируются changelog?</h2> <p>Двумя способами, и большинство реальных настроек — это смесь. Автоматизированная генерация читает сообщения коммитов, обычно в формате <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, и превращает их в записи без чьего-либо вмешательства в результат; <a href="https://changeloop.dev/blog/ru/conventional-commits-changelog/">от conventional commits к changelog</a> разбирает этот пайплайн. Курируемая генерация означает, что кто-то пишет или редактирует каждую запись вручную. Автоматизированный результат быстрее и никогда не пропускает смёрженный pull request, но наследует каждое расплывчатое сообщение коммита дословно — поэтому большинство автоматизирующих команд всё равно оставляют лёгкий проход редактуры перед публикацией, а не показывают сырой результат.</p> <h2>FAQ</h2> <p><strong>Нужен ли changelog каждому продукту?</strong> Любому продукту с пользователями, затронутыми изменениями, он нужен — будь то SaaS-приложение, внутренний инструмент или публичное API. Форма подстраивается (changelog API читается иначе, чем у потребительского приложения), потребность нет.</p> <p><strong>Что такое changelog в терминах программного обеспечения?</strong> То же определение, что и выше: датированный, хронологический список того, что изменилось в софте, написанный для тех, кто им пользуется, а не для тех, кто его строил.</p> <p><strong>Может ли changelog генерироваться автоматически из коммитов?</strong> Да, и многие команды делают именно это, обычно из сообщений в формате Conventional Commits. Компромисс в том, что сгенерированная запись настолько ясна, насколько ясно сообщение коммита, из которого она пришла, так что проход ревью перед публикацией ловит те, что нужно переформулировать.</p> <p><strong>Это то же самое, что история версий?</strong> Достаточно близко, чтобы термины использовали взаимозаменяемо. История версий иногда — просто список номеров версий и дат без описания; changelog всегда включает, что изменилось.</p> </article> <article> <h1>Changelog API: что публиковать и кто это читает</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Changelog API — это датированная запись каждого изменения, которое может заметить вызывающая сторона, написанная для тех, кто интегрируется с API, а не для команды, которая его выпускает. Эта аудитория делает его другим документом, чем changelog продукта: читатель решает, будет ли его код работать через месяц. Большинство таких changelog проваливаются одинаково, будучи отфильтрованной копией внутреннего ленты релизов, так что удалённое поле оказывается рядом с исправлением текста с тем же весом, и ни то ни другое не читают.</p> <h2>Что такое changelog API?</h2> <p>Это публичный, датированный журнал изменений в интерфейсе, под который другие писали код. Полезный тест на то, место ли чему-то в нём, не имеет отношения к тому, насколько велико было изменение внутри. Он спрашивает, мог бы правильный вызывающий код, написанный год назад и с тех пор не тронутый, повести себя иначе из-за него. Этот тест допускает некоторые очень мелкие изменения и исключает некоторые очень крупные.</p> <p>Всё ниже предполагает, что вызывающий находится вне компании и практически недосягаем иначе, чем через этот документ. Когда вызывающий — другая команда той же компании, расчёт меняется настолько, что заслуживает собственного разбора; <a href="https://changeloop.dev/blog/ru/internal-api-changelog/">внутренние changelog API</a> разбирает, что нужно этой аудитории вместо этого.</p> <table> <thead> <tr> <th>Документ</th> <th>Аудитория</th> <th>Отвечает на</th> </tr> </thead> <tbody><tr> <td>Changelog API</td> <td>Разработчики, вызывающие API</td> <td>Всё ещё работает моя интеграция?</td> </tr> <tr> <td>Release notes</td> <td>Пользователи продукта</td> <td>Что я теперь могу, чего не мог раньше?</td> </tr> <tr> <td>Уведомление о депрекейшене</td> <td>Вызывающие конкретную вещь</td> <td>Когда это перестанет работать?</td> </tr> <tr> <td>Страница статуса</td> <td>Все, кто сейчас затронут</td> <td>Сейчас всё лежит?</td> </tr> <tr> <td>Руководство по миграции</td> <td>Вызывающие, делающие апгрейд</td> <td>Как перейти от A к B?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/ru/api-migration-guide/">Как написать гайд по миграции API</a> разбирает этот последний документ целиком; коротко говоря, это то, на что должна ссылаться запись о несовместимом изменении, а не пытаться заменить.</p> <p>Эти пять — отдельные документы с отдельными жизненными циклами. Уведомление о депрекейшене — это обещание с датой, и оно тоже относится к changelog, но запись changelog пишется один раз, пока депрекейшен отслеживается вплоть до его sunset. Смешивание их — причина, по которой sunset пропускают.</p> <h2>Что должно входить в одну запись?</h2> <p>Шесть вещей, и первых трёх обычно не хватает. Само изменение, сформулированное в терминах запроса или ответа, а не внутреннего компонента. Ломает ли оно правильного вызывающего. Что должен сделать вызывающий, включая "ничего". Дата вступления в силу. Затронутая версия или версии. Ссылка на руководство по миграции, если оно есть.</p> <p>Запись, которая говорит "улучшен endpoint accounts", проваливается по всем шести пунктам. Запись, которая говорит "поле <code>accounts.type</code> теперь возвращает <code>individual</code> там, где раньше возвращало <code>personal</code>; существующие значения не меняются для аккаунтов, созданных до 2 сентября; действие не требуется, если вы не сравниваете строку", отвечает на все шесть в одном предложении.</p> <p>Категоризируйте записи по последствиям, а не по отделу. Три метки несут почти всю ценность: breaking, additive и fixed. <a href="https://semver.org/">Semantic Versioning</a> уже точно определяет первые две, и заимствование его определений вместо изобретения своих означает, что читатель, знающий semver, знает и ваши метки. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> предлагает более длинный набор, если хотите, и его центральное правило действует здесь сильнее, чем где-либо ещё: журнал — для людей, а свалка заголовков коммитов — нет.</p> <h2>Чем changelog API отличается от release notes?</h2> <p>Release notes описывают, что продукт теперь умеет. Changelog API описывает, каков теперь контракт. Одна и та же выпущенная работа часто порождает запись в обоих, сформулированную по-разному, потому что аудиториям нужны разные вещи: новый формат экспорта — это функция для пользователя и новое значение enum для вызывающего, переключающегося на этом поле.</p> <p>Практическое следствие в том, что эти два не могут быть одним и тем же потоком с разным стилем. Вызывающий, подписанный на всё, что вы выпускаете, в конце концов отпишется и тогда пропустит breaking change. Если публикуете один поток — фильтруйте его; если публикуете два — сделайте поток API уже и никогда не пускайте в него маркетинговую запись. Мы сравниваем обе формы бок о бок в <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">changelog против release notes</a>.</p> <h2>Где должен жить changelog API?</h2> <p>Рядом с справочной документацией, по стабильному URL, с каждой записью, адресуемой отдельно через фрагмент или собственный путь. Вызывающие ссылаются на записи в разборах инцидентов и внутренних тикетах, и запись, на которую нельзя сослаться, вместо этого вклеивается как скриншот.</p> <p>Публикуйте его также как машиночитаемый вывод, помимо страницы. JSON-поток, следующий <a href="https://www.jsonfeed.org/version/1.1/">спецификации JSON Feed</a>, или <a href="https://www.rssboard.org/rss-specification">RSS-поток</a> ничего не стоит, как только записи становятся структурированными данными, и именно это позволяет клиенту встроить ваши изменения в собственный процесс релизов. Это также часть, которая решает, будет ли кто-то на этом строить. GitHub документирует свои <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">версии REST API</a> прямо рядом со справочником по той же причине: политика версионирования — часть интерфейса.</p> <h2>Как выглядит хорошая запись на практике?</h2> <p>Три записи за одну неделю, в описанной выше форме:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` теперь отклоняет `currency`, не совпадающую с валютой аккаунта клиента, возвращая 422 вместо тихого конвертирования. Вызывающие, полагавшиеся на конвертацию, должны отправлять валюту аккаунта. Затрагивает только v2; v1 не меняется до sunset 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` получает временную метку `settled_at`, null до момента оплаты счёта. Действие не требуется. Клиентов, отклоняющих неизвестные поля, следует обновить. 2026-08-31 Fixed v2 `GET /invoices?status=` возвращал пустую страницу вместо 400 для неизвестного статуса. Теперь возвращает 400 с допустимыми значениями. Вызывающие с опечаткой раньше видели ноль результатов, теперь видят ошибку. </code></pre> <p>Третья — тип, который чаще всего пропускают, потому что внутри это исправление бага. Для вызывающего, построившего retry вокруг этой пустой страницы, это изменение поведения, и запись — именно то, что предотвращает тикет в поддержку. Метка говорит fixed, а тело говорит, что мог бы заметить вызывающий, и это различие держит журнал честным, не раздувая каждое исправление до breaking change.</p> <h2>Как вызывающие на это подписываются?</h2> <p>Дайте им больше одного канала, потому что у них разные задачи. Поток для разработчика, которому нужно всё. Email для того, кому нужны только breaking changes. Заголовки ответа для самого кода — единственного подписчика, который никогда не забывает проверить: <a href="https://datatracker.ietf.org/doc/html/rfc8594">заголовок <code>Sunset</code>, определённый в RFC 8594</a>, помещает дату вывода из эксплуатации в ответ, где клиентская библиотека может её залогировать.</p> <p>Канал, который большинство команд пропускает, — прямой. Если вызывающий использовал на прошлой неделе поле, которое вы меняете, вы знаете, кто это, и письмо на эти аккаунты стоит больше любой общей рассылки. Это та же дисциплина, что и <a href="https://changeloop.dev/blog/ru/customer-feedback-loop/">закрытие петли обратной связи с клиентом</a>, применённая к изменению, которое никто не просил: затронутых оповещают индивидуально, а все остальные получают поток. Вебхук — четвёртый канал со своим режимом отказа, о котором стоит знать перед тем, как на него полагаться: <a href="https://changeloop.dev/blog/ru/webhook-changelog/">changelog вебхуков</a> разбирает, почему изменение payload там ломается тихо, без вызывающего, способного отклонить новую форму.</p> <h2>Как написать запись для breaking change?</h2> <p>Начните с поломки, а не с причины. Вызывающий, просматривающий десять записей, должен в первой фразе понять, будет ли эта запись стоить ему работы. Затем дата, затронутые версии, миграция и крайний срок, если старое поведение исчезает, а не меняется.</p> <p>Поместите одно и то же содержание в уведомление о депрекейшене, заголовок ответа и прямое письмо, сформулировав его согласованно, и дайте всем четырём одну и ту же дату. Расхождение между ними — ошибка, превращающая запланированное изменение в инцидент, потому что вызывающий, прочитавший только одно из них, действует по неверной дате. <a href="https://changeloop.dev/blog/ru/breaking-changes/">Что такое breaking change</a> охватывает само решение, а <a href="https://changeloop.dev/blog/ru/api-deprecation/">как деприкейтить API</a> охватывает последующий график.</p> <p>В changeloop изменение API становится записью, когда pull request объединяется, кто-то редактирует и утверждает черновик, и запись публикуется в <a href="https://changeloop.dev/docs">ленте и виджете</a> в тот же момент, когда вызывающего, чей отзыв из виджета стал GitHub issue, который закрывает этот pull request, оповещают об этом в том же issue. Шаг проверки — именно то, что здесь важно: changelog API — это договорной документ, и ни один черновик не должен дойти до вызывающего без того, чтобы его прочитал человек.</p> <h2>FAQ</h2> <p><strong>Нужна ли каждому изменению API запись в changelog?</strong> Каждому изменению, которое мог бы заметить правильный вызывающий — да, включая те, что вы считаете внутренними. Изменения без наблюдаемого эффекта на запрос или ответ — нет, и добавление их приучает читателей проглядывать текст.</p> <p><strong>Должен ли changelog API жить в документации или на маркетинговом сайте?</strong> В документации, прямо рядом со справочником. Читатель обычно уже там, а changelog на маркетинговом сайте склонен набирать аудиторию, для которой он не был написан.</p> <p><strong>Насколько далеко назад он должен идти?</strong> Бесконечно. На записи ссылаются годы спустя в разборах инцидентов, и обрезанный журнал ломает эти ссылки. Используйте пагинацию, а не удаление.</p> <p><strong>Нужен ли отдельный changelog для каждой версии API?</strong> Нет, один журнал с полем версии в каждой записи легче читать и искать. Фильтрация по версии — функция страницы, а не причина разделять документ.</p> </article> <article> <h1>Как сделать страницу changelog, за которой следят</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Страницу changelog стоит делать, если люди будут на неё возвращаться. Это более высокая планка, чем просто иметь такую страницу, и именно на ней спотыкается большинство: страница существует, на неё есть ссылка в футере, обновляется рывками и посещается разве что во время инцидента. Решения, разделяющие эти два случая, принимаются до того, как написано хоть слово, и в основном касаются того, где живёт страница и что ещё генерируется из того же содержимого.</p> <h2>Что такое страница changelog?</h2> <p>Это публичный, датированный список того, что изменилось в продукте, по URL, который принадлежит вам. Это одна из пяти поверхностей, на которых могут появляться одни и те же записи, и полезный вопрос — не какую выбрать, а какая из них каноническая, а какие сгенерированы из неё.</p> <table> <thead> <tr> <th>Поверхность</th> <th>Лучше всего для</th> <th>Стоимость</th> </tr> </thead> <tbody><tr> <td>Хостируемая страница</td> <td>Поиска, ссылок, длинного журнала</td> <td>URL и шаблон</td> </tr> <tr> <td>Виджет в приложении</td> <td>Пользователей, никогда не заходящих на страницу</td> <td>Встраивание, и сдержанность</td> </tr> <tr> <td>Раздел документации</td> <td>Аудитории API и разработчиков</td> <td>Хранения рядом со справочником</td> </tr> <tr> <td>JSON-поток</td> <td>Клиентов, строящих на ваших изменениях</td> <td>Структура, которая у вас уже есть</td> </tr> <tr> <td>RSS-поток</td> <td>Разработчиков, подписывающихся один раз</td> <td>Почти ничего</td> </tr> </tbody></table> <p>Выберите один канонический источник, публикуйте один раз, а остальное генерируйте. Команды, поддерживающие страницу и виджет отдельно вручную, в итоге получают два текста, которые не совпадают, и расхождение обнаруживает клиент.</p> <h2>Где должна жить страница changelog?</h2> <p>На вашем собственном домене, по стабильному пути, с каждой записью, адресуемой отдельно. Три распространённых варианта — путь на основном сайте, поддомен и раздел документации. Путь на основном сайте — выбор по умолчанию, против которого нужно аргументировать, а не за него: он наследует авторитет сайта, не требует дополнительного сертификата или DNS, и держит страницу в той же навигации, что и всё остальное.</p> <p>Поддомен — правильный ответ, когда страницу обслуживает система, отличная от маркетингового сайта, и иначе пришлось бы делать proxy. Цена — он накапливает авторитет отдельно. Размещение changelog в документации правильно, когда аудитория — разработчики, по причине, разобранной в <a href="https://changeloop.dev/blog/ru/api-changelog/">changelog API</a>: читатель там уже обычно находится.</p> <p>Важнее выбора то, что на записи можно ссылаться по отдельности. Люди ссылаются на записи в разборах инцидентов и внутренних тикетах, и запись, на которую можно сослаться только как "changelog, прокрутите вниз", вместо этого вклеивается скриншотом.</p> <h2>Что нужно странице changelog?</h2> <p>Пять вещей, и на первых двух проваливается большинство страниц. Датированная запись на каждое изменение, новейшие сначала. Категория или метка на запись, чтобы можно было сканировать по интересующему типу. Постоянная ссылка на запись. Способ подписки. Поиск или фильтр после примерно пятидесяти записей.</p> <p>Остальное опционально. Скриншоты помогают и требуют поддержки. Имена авторов создают доверие в одних продуктах и шум в других. Номера версий важны для вызывающих API и почти ни для кого больше. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> — разумный выбор по умолчанию для меток, если у вас нет причин изобретать свои, и его центральное правило стоит сохранить, даже если отбросить остальное: журнал пишется для людей.</p> <p>Группируйте по дате, а не по версии, если ваш продукт релизится непрерывно. Читатель, сканирующий "это было до или после нашего инцидента девятого числа", ищет дату, а страница, организованная по номеру версии, заставляет его считать.</p> <h2>Страница или виджет в приложении?</h2> <p>И то, и другое, из одного источника. Страница — это место, где живут поиск, ссылки и длинный журнал. Виджет — способ достучаться до большинства пользователей, которые никогда не зайдут на страницу, и он работает, потому что появляется в продукте, которым они уже пользуются.</p> <p>Провал виджета — это прерывание. Значок, требующий внимания на каждую запись, будет навсегда отклонён в течение недели, что стоит вам канала для той записи, которая действительно имела значение. Считайте непрочитанное с последнего взгляда читателя, тихо засевайте счётчик при первом визите, чтобы никого не встречал значок с историей за год, и дайте читателю открыть его самому, вместо того чтобы открывать за него.</p> <h2>Как сделать страницу changelog машиночитаемой?</h2> <p>Публикуйте те же записи как поток. <a href="https://www.jsonfeed.org/version/1.1/">JSON-поток</a> — вариант с наименьшим трением для всего, что потребляет его в коде, а <a href="https://www.rssboard.org/rss-specification">RSS-поток</a> — то, чего ожидает разработчик, подписавшийся в ридере. Оба обходятся дёшево, как только записи становятся структурированными данными вместо HTML, написанного вручную, что и есть реальный аргумент за то, чтобы держать каноническую копию структурированной.</p> <p>Разметьте и страницу тоже. Записи — это произведения с датой и заголовком, и <a href="https://schema.org/CreativeWork">schema.org</a> предоставляет словарь. Это стоит сделать по той же причине, что и постоянные ссылки: это делает страницу пригодной для использования вещами, которые не являются браузером, включая собственный процесс релизов клиента. Ничего из этого не работает, если исходные записи никогда не были структурированными данными с самого начала; <a href="https://changeloop.dev/blog/ru/changelog-file-formats/">форматы файлов changelog</a> разбирает, сколько стоит каждый из Markdown, JSON и YAML как источник истины, из которого этот поток и эта разметка реально генерируются.</p> <h2>Помогает ли страница changelog SEO?</h2> <p>Косвенно и медленно. Отдельные записи редко ранжируются, потому что не нацелены ни на один запрос, который кто-то вводит. Страница зарабатывает своё место через ссылки: записи цитируют в ответах поддержки, на форумах и в разборах инцидентов, и эти ссылки накапливаются на URL, который принадлежит вам. Страница, обновляемая еженедельно два года подряд, — это ещё и убедительный сигнал свежести для продукта, которому она принадлежит.</p> <p>Что не работает — это относиться к записям как к контент-маркетингу. Запись, раздутая до трёх абзацев ради длины, хуже справляется со своей настоящей работой — сказать читателю в одном предложении, изменилось ли что-то, чем он пользуется. Если хотите, чтобы changelog поддерживал поиск, вкладывайте усилия в постоянные ссылки, поток и внутренние ссылки на него, а записи держите короткими. Наша собственная страница <a href="https://changeloop.dev/changelog-examples">примеров changelog</a> собирает страницы, которые верно ловят этот баланс.</p> <h2>Как люди подписываются?</h2> <p>Дайте им пути, которыми они уже пользуются: RSS- или JSON-поток для разработчиков, email для тех, кто хочет слышать только важное, и виджет в приложении для всех, кто никогда не сделает ни того ни другого. Спрашивайте, что они хотят слышать, а не предполагайте, потому что читатель, желающий breaking changes и получающий исправления текста, отписывается от обоих.</p> <p>Путь, который стоит добавить последним, — тот, что замыкает петлю. Когда запись решает то, о чём попросил конкретный человек, скажите ему это напрямую, вместо того чтобы надеяться, что он прочтёт страницу. В changeloop запись публикуется сразу на <a href="https://changeloop.dev/docs">странице, в потоке и виджете</a>, и человека, чей отзыв из виджета стал GitHub issue, закрытым этим pull request, оповещают в этом issue со ссылкой на запись, и он видит запись в виджете. Механизм тот же, что и у любой подписки; разница в том, что получатель уже спросил. Это аргумент, развёрнутый в <a href="https://changeloop.dev/blog/ru/customer-feedback-loop/">закрытии петли обратной связи со стороны changelog</a>.</p> <h2>FAQ</h2> <p><strong>Должна ли страница changelog быть на поддомене или на пути?</strong> По умолчанию — путь на основном сайте, потому что он наследует авторитет сайта и не требует дополнительной инфраструктуры. Поддомен оправдан, когда страницу обслуживает другая система.</p> <p><strong>Сколько записей должна показывать страница за раз?</strong> Достаточно, чтобы заполнить экран, и не больше, с пагинацией после этого. Загрузка двух лет истории в один документ работает медленно и усложняет поиск новейшей записи.</p> <p><strong>Стоит ли когда-нибудь удалять старые записи?</strong> Нет. На них ссылаются извне вашего сайта, и ссылки ломаются. Исправляйте запись на месте с пометкой, и держите URL живым.</p> <p><strong>Должно ли каждое изменение появляться на странице?</strong> Только те, что мог бы заметить пользователь. Страница, фиксирующая внутренние рефакторинги, приучает читателей проглядывать текст, а проглядываемая страница проваливается в тот день, когда несёт что-то срочное.</p> </article> <article> <h1>Шаблон письма об обновлении продукта, которое читают</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Письмо об обновлении продукта, которое читают, — это то, что отправлено человеку, попросившему именно то, о чём оно сообщает. Всё остальное конкурирует с остальной почтой за интерес — гонку, которую анонс релиза проигрывает в большинство недель. Этот единственный факт должен определять форму письма ещё до того, как сформулировано хоть одно слово: кто его получает, и что этот человек сделал, чтобы попасть в список.</p> <h2>Что такое письмо об обновлении продукта?</h2> <p>Это сообщение, рассказывающее существующим пользователям, что изменилось в продукте, которым они уже пользуются. Есть четыре разных типа, и обращение с ними как с одним списком — причина падения open rate. У каждого свой триггер, своя аудитория и своя приемлемая частота.</p> <table> <thead> <tr> <th>Тип</th> <th>Триггер</th> <th>Аудитория</th> <th>Частота</th> </tr> </thead> <tbody><tr> <td>Целевое уведомление</td> <td>Конкретный запрос кого-то выпущен</td> <td>Один человек</td> <td>Каждый раз</td> </tr> <tr> <td>Уведомление о breaking change</td> <td>Изменение, стоящее читателю работы</td> <td>Только затронутые аккаунты</td> <td>Каждый раз</td> </tr> <tr> <td>Дайджест</td> <td>Течение времени</td> <td>Пользователи opt-in</td> <td>Не чаще раза в месяц</td> </tr> <tr> <td>Анонс запуска</td> <td>Запуск, стоящий прерывания</td> <td>Сегмент или все</td> <td>Редко, и должно ощущаться редким</td> </tr> </tbody></table> <p>Большинство команд строят только третий тип, рассылают его всем и делают вывод, что письма об обновлении продукта не работают. Первые два несут почти всю ценность, потому что у читателя уже есть причина заинтересоваться, и письмо приходит, пока эта причина ещё жива.</p> <p>Все эти четыре строки написаны для клиентов. Продажам, саппорту и customer success тоже нужно знать, что вышло, обычно в форме, отличной от этих четырёх; <a href="https://changeloop.dev/blog/ru/internal-release-notes/">внутренние release notes</a> разбирают, что должен говорить этот документ и почему он должен выходить раньше заметки для клиентов.</p> <p>Email — один из нескольких каналов, которые может использовать анонс запуска, не единственный. <a href="https://changeloop.dev/blog/ru/new-feature-announcement/">Как анонсировать новую функцию</a> описывает остальные и как выбирать между ними в зависимости от того, насколько велика функция на самом деле.</p> <h2>Что входит в шаблон?</h2> <p>Шесть блоков в таком порядке. Первый — тот, которого обычно не хватает, и тот, что делает работу.</p> <pre><code>Тема: <что изменилось, словами читателя> 1. Почему вы это получаете "Вы просили экспорт в CSV в марте." или "Ваша интеграция вызывает /v1/invoices, который меняется 15 января." 2. Что изменилось Одно предложение. Что теперь возможно, или что теперь ломается. 3. Что вам нужно сделать Часто "ничего". Скажите это явно, не оставляйте подразумеваемым. 4. Где это увидеть Ссылка на запись changelog, а не на главную страницу. 5. Когда Дата выпуска, или с какого момента это действует. 6. Как отписаться Один клик, немедленно уважаемый. </code></pre> <p>Блок 1 — разница между сообщением и общей рассылкой. Читатель, которому в первой строке говорят, что это решение того, о чём он лично просил, читает дальше. Без него блоки 2-5 — рассылка, каким бы хорошим ни был текст.</p> <p>Держите всё в пределах примерно 150 слов. Письмо — указатель на запись changelog, и именно там место деталям. Письмо, воспроизводящее всю запись целиком, не даёт читателю причины кликнуть, а вам — сигнала, было ли это кому-то важно.</p> <h2>Какие темы работают?</h2> <p>Называйте изменение, а не релиз. "Экспорт в CSV уже доступен" побеждает "обновление за сентябрь", потому что первое — факт, который читатель может оценить, а второе — контейнер. Номера версий в теме полезны вызывающим API и шум для всех остальных, ещё одна причина разделить аудитории.</p> <p>Избегайте заявлений о выгоде, на которую читатель не соглашался. "Ваши отчёты теперь быстрее" заявляет что-то о его опыте; "Отчёты свыше 10 000 строк теперь загружаются меньше чем за секунду" сообщает об изменении и позволяет ему решить, важно ли это.</p> <h2>Когда его отправлять, и кому?</h2> <p>Отправляйте целевое уведомление в момент, когда что-то выпущено, людям, которые это просили, индивидуально. Отправляйте уведомление о breaking change сразу, как дата станет точной, и ещё раз ближе к ней, реально затронутым аккаунтам, а не всему списку. Отправляйте дайджест, только если у вас достаточно изменений, чтобы читатель иначе что-то пропустил, и дайте людям подписываться отдельно.</p> <p>Список, который почти никогда не стоит использовать, — "все пользователи". Он превращает конкретное сообщение в общее и приучает к отпискам. Сегментируйте по поведению, которое вы уже храните: кто это просил, кто использует этот endpoint, кто на этом плане.</p> <h2>Нужно ли согласие на отправку?</h2> <p>Для существующих клиентов обновление об услуге, которой они пользуются, обычно другой юридический вопрос, чем маркетинг потенциальному клиенту, и ответ зависит от того, где они находятся, и что вы сказали им при регистрации. В ЕС релевантный вопрос — какое правовое основание из <a href="https://gdpr-info.eu/art-6-gdpr/">статьи 6 GDPR</a> применимо, а в США коммерческие сообщения несут конкретные требования, установленные в <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">руководстве по соответствию CAN-SPAM от FTC</a>. Оба на практике требуют одного и того же: скажите, кто вы, проясните цель, и дайте людям возможность остановить рассылку.</p> <p>Каким бы ни было основание, держите транзакционный и маркетинговый потоки раздельными на уровне отправки. Уведомление о breaking change, от которого клиент отписался, потому что оно делило список с промо-дайджестом, — это инцидент поддержки, ждущий своей даты.</p> <h2>Как это выглядит заполненным?</h2> <p>Целевое уведомление — самое ценное письмо об обновлении продукта и то, которое большинство команд никогда не строят:</p> <pre><code>Тема: Экспорт в CSV уже доступен Привет, Дана, ты просила экспорт в CSV в марте. Это стало доступно сегодня утром. У отчётов теперь есть кнопка Export, создающая CSV текущего вида, включая фильтры. С твоей стороны ничего делать не нужно. Уже включено на твоём аккаунте. Подробности: example.com/changelog#csv-export Выпущено: 2 сентября 2026 Ты получаешь это, потому что просила. Отписаться от обновлений по запросам: <ссылка> </code></pre> <p>Девяносто слов, и читатель в первой строке знает, почему это пришло. Сравните с тем же изменением в месячном дайджесте, где оно появляется как один из девяти пунктов, а у Даны нет причин заметить, что её собственный запрос вышел.</p> <h2>Что стоит измерять?</h2> <p>Не только open rate. Для целевого уведомления вопрос в том, вернулся ли попросивший человек и воспользовался ли этим, так что число для отслеживания — клик к записи и использует ли этот аккаунт функцию в течение недели. Для уведомления о breaking change это покрытие: какая доля затронутых аккаунтов открыла письмо до даты, и с кем вы связались индивидуально.</p> <p>Дайджест — единственный из четырёх типов, где open rate что-то значит, и даже там он полезнее как тренд относительно собственной истории, чем относительно отраслевого бенчмарка. У разных типов писем об обновлении продукта разные задачи, так что усреднённая по всем цифра не описывает ничего, на что можно опереться в действиях.</p> <h2>Чем это отличается от release notes?</h2> <p>Release notes — документ, который остаётся доступным. Письмо — механизм доставки, случающийся один раз. Одно и то же изменение порождает оба, и письмо должно быть короче записи, на которую указывает. <a href="https://changeloop.dev/blog/ru/release-notes-best-practices/">Лучшие практики release notes</a> охватывает документ, а <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">changelog против release notes</a> охватывает, какой из них вы пишете.</p> <p>Отношение, которое стоит наладить правильно: запись changelog — канонический текст, а письмо его цитирует. Когда эти два расходятся, читатель, кликнувший по ссылке, находит другое описание изменения и перестаёт доверять обоим. Публикация записи первой и генерация письма из неё убирает расхождение конструктивно. changeloop со своей стороны работает так же: запись рецензируется один раз и публикуется на <a href="https://changeloop.dev/docs">странице, в потоке и виджете</a>, а человека, попросившего о ней через виджет, оповещают в GitHub issue, которым стал его отзыв, и в самом виджете. Письмо changeloop не отправляет; ваш почтовый инструмент цитирует опубликованную запись.</p> <h2>FAQ</h2> <p><strong>Как часто должно выходить письмо об обновлении продукта?</strong> Так часто, как есть что-то конкретное, что получатель хочет знать, что для целевого уведомления означает каждый раз, когда выпускается его запрос, а для дайджеста — не чаще раза в месяц.</p> <p><strong>Должно ли письмо содержать всю запись changelog целиком?</strong> Нет. Одно предложение и ссылка. Запись — каноническая версия, а полная копия в письме означает два текста, которые нужно держать согласованными.</p> <p><strong>Какой open rate стоит ожидать?</strong> Сравнивайте каждый тип с самим собой, а не с бенчмарком. Целевое уведомление и месячный дайджест — разные продукты, и их усреднение скрывает единственную цифру, за которой стоит следить.</p> <p><strong>Нужен ли отдельный список для breaking changes?</strong> Да, и это должен быть тот список, от которого люди не могут отписаться небрежно, не понимая последствий, потому что это тот список, что стоит им сбоя.</p> </article> <article> <h1>Как деприкейтить API, не теряя разработчиков</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Деприкейтить API означает объявить, что что-то ещё работает сегодня и перестанет работать к объявленной дате, а затем сдержать обе половины этого обещания. Большинство депрекаций проваливаются на второй половине: дата тихо сдвигается, или наступает, а вызывающие, никогда не видевшие уведомления, узнают об этом из ошибки. Депрекация завершена, когда каждый затронутый вызывающий либо мигрировал, либо был индивидуально уведомлён, что не сделал этого.</p> <h2>Что такое депрекация API?</h2> <p>Депрекация — это период между объявлением, что endpoint, поле или версия исчезнут, и их фактическим удалением. В этот период старое поведение продолжает работать, документация говорит, что оно уходит, и каждый ответ несёт машиночитаемое предупреждение. Удаление — это отдельное, более позднее событие, часто называемое sunset. Эти два путают, и эта путаница — то место, где происходит вред: «deprecated» начинает означать «возможно, уже исчезло», а вызывающие перестают доверять обоим словам.</p> <table> <thead> <tr> <th>Термин</th> <th>Значение</th> <th>На что могут полагаться вызывающие</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Объявлено как исчезающее, всё ещё работает</td> <td>Полное поведение до даты sunset</td> </tr> <tr> <td>Sunset</td> <td>Дата, когда перестаёт работать</td> <td>Ничего после этой даты</td> </tr> <tr> <td>Retired / удалённое</td> <td>Исчезло; запросы падают</td> <td>Ошибка, в идеале называющая замену</td> </tr> <tr> <td>Legacy</td> <td>Неопределено. Избегайте этого слова</td> <td>Ничего, что и есть проблема</td> </tr> </tbody></table> <h2>Сколько должен длиться период депрекации?</h2> <p>Достаточно долго, чтобы вызывающий узнал и выполнил работу, измеряется от момента, когда уведомление до него дошло, а не от момента, когда вы его написали. Девяносто дней — обычный минимум для публичного веб-API. Двенадцать месяцев нормально для всего, встроенного в софт, который устанавливают конечные пользователи, потому что исправление также должно пройти через их процесс релиза. Руководство Google по версионированию, <a href="https://google.aip.dev/185">AIP-185</a>, требует разумного переходного периода и рекомендует 180 дней даже перед удалением бета-функциональности, а Kubernetes документирует свою <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">политику депрекации</a> в количестве релизов, а не месяцах, что является правильной единицей, когда ваши вызывающие обновляются по версии.</p> <p>Выберите период, запишите его как политику, и прекратите решать это по каждому изменению. Опубликованная политика превращает каждую депрекацию из переговоров в применение правила.</p> <p>Запись политики депрекации покрывает начало окна; <a href="https://changeloop.dev/blog/ru/sunsetting-api-version/">закрытие версии API</a> разбирает отдельное уведомление, нужное в конце, когда период реально истекает и версия перестаёт работать.</p> <h2>Расписание депрекации</h2> <p>Четыре даты, объявленные вместе в первый день. Каждая — отдельная запись changelog при наступлении, поэтому история рассказывается четыре раза каждому, кто читает только changelog.</p> <ol> <li><strong>Объявите.</strong> Запись говорит, что депрекируется, почему, что это заменяет, и дату sunset. Документация старой вещи получает баннер, ведущий к миграции. Ответы получают заголовки, описанные ниже.</li> <li><strong>Напомните, на полпути.</strong> Вторая запись, и прямое сообщение каждому вызывающему, всё ещё использующему старое поведение. Это шаг, требующий данных об использовании: если вы не можете перечислить, кто всё ещё вызывает депрекированный endpoint, вы не можете это сделать, и это стоит исправить до следующей депрекации.</li> <li><strong>Brownout, незадолго до даты.</strong> Возвращайте ошибки для старого поведения в течение короткого окна, час или день, затем восстановите. Вызывающие, пропустившие каждое уведомление, узнают об этом сейчас, пока ещё есть время. GitHub использовал запланированные brownout перед <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">выводом из эксплуатации аутентификации по паролю для API</a>, и это самый эффективный отдельный шаг в этом списке.</li> <li><strong>Sunset.</strong> Удалите это. Ошибка, заменяющая это, называет замену и ведёт к руководству по миграции. Держите ошибку на месте долго; 404 ничего не сообщает вызывающему.</li> </ol> <h2>Что должно говорить уведомление о депрекации?</h2> <p>Уведомление о депрекации говорит, что уходит, когда останавливается, что использовать вместо этого, и кого затрагивает. Вот форма, заполненная:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> депрекирован и перестаёт работать 1 марта 2027 года.</strong> Заменяется на <code>GET /v2/reports?granularity=day</code>, который возвращает те же данные со стабильной схемой и пагинацией. Затрагивает 214 интеграций, вызвавших endpoint v1 за последние 30 дней; если ваша одна из них, вы также получите это уведомление по почте. Руководство по миграции: [ссылка]. Ничего не меняется до 1 марта 2027 года. С этой даты endpoint v1 возвращает <code>410 Gone</code> со ссылкой на эту запись.</p> </blockquote> <p>Каждое предложение несёт что-то, что нужно читательнице. Количество затронутых интеграций сообщает каждой читательнице, стоит ли продолжать читать. «Ничего не меняется до» — это предложение, позволяющее незатронутым закрыть вкладку. Страница <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> собирает записи от команд, последовательно пишущих эту форму, и стоит прочитать три перед написанием своей первой.</p> <h2>Какие заголовки должен посылать депрекированный endpoint?</h2> <p>Отправляйте <code>Deprecation</code>, <code>Sunset</code> и <code>Link</code> на преемника в каждом ответе от депрекированного endpoint, с дня объявления. <a href="https://datatracker.ietf.org/doc/html/rfc9745">Заголовок <code>Deprecation</code></a> несёт дату, когда депрекация вступила в силу; <a href="https://datatracker.ietf.org/doc/html/rfc8594">заголовок <code>Sunset</code></a> несёт дату, когда endpoint перестаёт отвечать; <code>Link: <url>; rel="successor-version"</code> указывает, что использовать вместо этого.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>Большинство вызывающих никогда сами не прочитают заголовки. Их ценность в том, что HTTP-клиент, шлюз или мониторинг вызывающего могут, что превращает вашу депрекацию в оповещение на их стороне вместо страницы на вашей. SDK, которые вы поставляете, должны логировать предупреждение, когда видят такое.</p> <h2>Кто был уведомлён, и откуда вы это знаете?</h2> <p>Это шаг, решающий, будет ли sunset тихим или станет инцидентом поддержки, и это самое сложное, что можно сделать только с changelog. Запись changelog уведомляет каждого, кто читает changelog. Депрекация должна достичь конкретных людей, чей код упадёт, и обычный способ их найти — те же данные об использовании, которые нужны напоминанию на полпути: API-ключи, приложения или аккаунты, недавно вызывавшие депрекированное поведение.</p> <p>Цикл, который мы выполняем: запись составляется из pull request, добавляющего депрекацию, человек рецензирует формулировку и дату, а после публикации сама запись является уведомлением. Каждый, чей отзыв из виджета о проблеме или запрос замены стал GitHub issue, который закрывает этот pull request, получает в этом issue комментарий, говорящий, что это выпущено, со ссылкой на запись. <a href="https://changeloop.dev/docs">Лента и виджет</a> обслуживают ту же запись всем остальным, вместе с каждой другой записью в <a href="https://changeloop.dev/blog/ru/api-changelog/">changelog API</a>. Что мы не делаем — не позволяем депрекации стать «выпущенной» до того, как человек её опубликовал; уведомление с неправильной датой хуже, чем отсутствие уведомления.</p> <p>Какими бы ни были ваши инструменты, вопрос, на который вы должны уметь ответить в день sunset: какие вызывающие всё ещё использовали это на прошлой неделе, и кому из них мы сказали напрямую? Если ответ «мы опубликовали об этом что-то», sunset не готов.</p> <h2>В чём разница между депрекацией и версионированием?</h2> <p>Версионирование — это то, как вы сохраняете старое поведение доступным, пока существует новое; депрекация — это то, как вы выводите старое из эксплуатации. Новая версия API без политики депрекации для предыдущей — это обязательство работать с обеими навсегда. Депрекация без версионирования — это <a href="https://changeloop.dev/blog/ru/breaking-changes/">breaking change</a> с задержкой. Вам нужны оба, и версия — более лёгкая половина. GraphQL — исключение, которое стоит назвать: обычно там вообще нет номера версии для повышения, и <a href="https://changeloop.dev/blog/ru/graphql-schema-deprecation/">депрекация схемы GraphQL</a> разбирает, как одна общая схема выводит поле из эксплуатации директивой вместо этого.</p> <h2>FAQ</h2> <p><strong>Должен ли депрекированный endpoint продолжать работать точно так же, как раньше?</strong> Да, до даты sunset. Единственные допустимые изменения — добавленные заголовки и, ближе к концу, запланированный brownout, который вы объявили заранее.</p> <p><strong>Какой код статуса должен возвращать выведенный из эксплуатации endpoint?</strong> <code>410 Gone</code>, с телом и заголовком <code>Link</code>, указывающим на замену и запись changelog. <code>404</code> говорит, что URL никогда не существовал, что ложно и бесполезно.</p> <p><strong>Можно ли сократить период депрекации?</strong> Только по соображениям безопасности. Если старое поведение эксплуатируемо, скажите это, сократите период, и уведомите каждого затронутого вызывающего напрямую, вместо того чтобы полагаться на changelog.</p> <p><strong>Нужно ли мне деприкейтить поле, или только целые endpoint?</strong> Поля, параметры, значения enum, значения по умолчанию и заголовки — все нуждаются в одинаковом обращении, потому что каждый может сломать корректного вызывающего. Удалённое поле — самая распространённая депрекация и наиболее часто пропускаемая.</p> </article> <article> <h1>Лучшие практики версионирования API, ради вызывающих</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Версионирование API — это практика поддержания старого контракта работающим после того, как вы его изменили, чтобы вызывающие могли переходить по своему собственному графику, а не вашему. Это предложение содержит два решения, которые важны: что считается изменением контракта, и как долго старый продолжает работать. То, где живёт номер версии, о чём большинство дебатов о версионировании, наименее важно из трёх и легче всего сделать правильно.</p> <h2>Когда следует версионировать API?</h2> <p>Версионируйте API только когда изменение сломало бы корректного вызывающего. Аддитивные изменения, новые поля, новые endpoint, новые опциональные параметры не нуждаются в версии; вызывающие, написанные под старый контракт, продолжают работать, а новая возможность просто существует. <a href="https://changeloop.dev/blog/ru/breaking-changes/">Breaking change</a> нуждается в ней, потому что альтернатива — узнать об этом вызывающему из ошибки. Версионирование каждого релиза, включая аддитивные, учит вызывающих, что версии — это шум, и они перестают читать важные уведомления.</p> <p>Практический тест такой же, как в статье о breaking change: если вызывающий, полагавшийся только на документированное поведение, должен что-то изменить, чтобы продолжить работать, изменению нужна версия. Если нет, выпустите его под текущей версией и напишите запись changelog.</p> <h2>Какую схему версионирования API следует использовать?</h2> <p>Используйте схему, которую ваши вызывающие могут легче всего видеть и устанавливать, что для большинства публичных API — это версия в пути URL или датированный заголовок версии. Четыре общие схемы различаются меньше в возможностях, чем в том, что они требуют от вызывающего, и это правильная основа для выбора.</p> <table> <thead> <tr> <th>Схема</th> <th>Пример</th> <th>Что должен сделать вызывающий</th> <th>Кто использует</th> </tr> </thead> <tbody><tr> <td>Путь URL</td> <td><code>/v2/invoices</code></td> <td>Изменить URL при миграции</td> <td>Большинство публичных REST API</td> </tr> <tr> <td>Заголовок версии</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Отправить заголовок, или принять умолчание</td> <td>GitHub</td> </tr> <tr> <td>Датированная версия аккаунта</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Закрепить дату на запрос или на аккаунт</td> <td>Stripe</td> </tr> <tr> <td>Параметр запроса</td> <td><code>/invoices?version=2</code></td> <td>Добавить параметр</td> <td>Более старые API; редко выбирается сейчас</td> </tr> <tr> <td>Тип медиа</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Согласовывать типы содержимого</td> <td>Пуристы; мало вызывающих справляются</td> </tr> </tbody></table> <p><strong>Путь URL</strong> самый заметный и наименее гибкий. Каждый вызывающий может видеть, в какой он версии, читая строку лога, а скачок версии — это найти-и-заменить. Цена: вся поверхность двигается сразу, вы не можете изменить контракт одного endpoint без выпуска новой версии для всех, поэтому версии пути, как правило, редки и велики.</p> <p><strong>Заголовок версии</strong> держит URL стабильными и позволяет серверу выбрать умолчание для вызывающих, ничего не отправляющих, так работает <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">версионирование REST API GitHub</a>: версия, названная по дате, в <code>X-GitHub-Api-Version</code>, с самой старой поддерживаемой версией как умолчанием, чтобы неверсионированные вызывающие не ломались. Цена: версия невидима в URL и легко забывается в новом клиенте.</p> <p><strong>Датированная версия аккаунта</strong> — это схема заголовка плюс одно дополнение: версия хранится против аккаунта, поэтому каждый запрос получает её, ничего не отправляя. <a href="https://docs.stripe.com/api/versioning">Версионирование API Stripe</a> закрепляет каждый аккаунт на версии, с которой он был создан, и позволяет запросу перезаписать это <code>Stripe-Version</code>. Это самая дружественная к вызывающему схема и требующая больше всего работы для эксплуатации, потому что серверу нужно переводить между каждой поддерживаемой версией и текущей.</p> <p><strong>Параметр запроса</strong> и <strong>тип медиа</strong> оба работают и оба проваливают тест видимости по-разному: параметр запроса легко теряется при построении URL, а версия типа медиа невидима почти для любого инструмента, которым вызывающий бы отлаживал. Схема Stripe с датами является самым известным примером подхода с датой, и <a href="https://changeloop.dev/blog/ru/stripe-api-versioning/">как Stripe версионирует свой API</a> разбирает её подробно.</p> <h2>Как версионирование API делается на практике?</h2> <p>На практике версия — это именованный набор поведений, и сервер отображает каждый запрос на одно из них. Шаги одинаковы независимо от того, какая схема несёт имя.</p> <ol> <li><strong>Называйте версии по дате или целому числу, не по семантической версии.</strong> Веб-API — это не пакет. Вызывающие не могут закрепить minor версию URL, поэтому <code>v2</code> или <code>2026-08-26</code> говорит всё, что нужно вызывающему, а <a href="https://semver.org/">семантическое версионирование</a> подразумевает обещание совместимости, которое схема не может выполнить.</li> <li><strong>Держите версию вне путей кода, которым она безразлична.</strong> Версия должна выбирать слой трансляции на границе, а не разветвлять бизнес-логику. Две полные копии кодовой базы — это как версия оказывается неподдерживаемой.</li> <li><strong>Давайте каждой версии умолчание и документ.</strong> Вызывающие, не отправляющие версию, получают самую старую поддерживаемую, никогда не самую новую, чтобы незакреплённый клиент не сломался в день релиза. У каждой версии есть страница, говорящая, что изменилось по сравнению с предыдущей.</li> <li><strong>Установите окно поддержки и опубликуйте его.</strong> Руководство Google по версионированию, <a href="https://google.aip.dev/185">AIP-185</a>, требует разумного и заранее объявленного переходного периода и рекомендует 180 дней даже для бета-функциональности. Выберите окно, запишите его, и применяйте без пересогласования по каждой версии.</li> <li><strong>Выводите версии из эксплуатации так же, как выводите endpoint.</strong> Версия, прошедшая своё окно, получает то же обращение, что и любой <a href="https://changeloop.dev/blog/ru/api-deprecation/">депрекированный API</a>: объявление, заголовок <code>Sunset</code> (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) в каждом ответе, напоминание на полпути оставшимся вызывающим, и дата удаления, которая соблюдается.</li> </ol> <h2>Что такое v1 и v2 в REST API?</h2> <p><code>v1</code> и <code>v2</code> — это имена для двух контрактов, которые один и тот же сервер поддерживает одновременно. <code>v2</code> существует, потому что что-то в <code>v1</code> нельзя было изменить без разрушения его вызывающих, поэтому изменение пошло в новый контракт, а старый продолжил работать. Номера не подразумевают, что <code>v2</code> завершён или что <code>v1</code> мёртв; оба верны, только если документация так говорит. <code>v3</code>, появляющийся каждый квартал, — это признак того, что версионируются аддитивные изменения, или что контракт никогда не проектировался для поглощения изменений.</p> <p>Это модель версионирования через путь URL, где номер версии — сегмент, который набирает вызывающий. Сервисы gRPC обычно решают ту же проблему иначе: версия живёт в имени пакета внутри самого файла <code>.proto</code>. <a href="https://changeloop.dev/blog/ru/grpc-protobuf-api-changes/">gRPC и Protobuf</a> разбирает эту разницу и то, почему совместимость на проводе там определяется номерами полей, а не формой URL.</p> <h2>Что должно объявлять изменение версии?</h2> <p>Изменение версии должно объявлять, что ломается, кого затрагивает, как мигрировать, и как долго предыдущая версия продолжает работать. У записи та же форма, что у любой другой записи об изменении, ломающем совместимость, плюс строка, объявляющая окно поддержки. Вот одна для API, версионированного заголовком:</p> <blockquote> <p><strong>Версия API 2026-11-01 доступна. Версия 2025-06-15 поддерживается до 1 ноября 2027 года.</strong> Новое в 2026-11-01: <code>GET /invoices</code> возвращает <code>amount</code> в минимальных единицах как целое число вместо десятичной строки, а депрекированное поле <code>customer_name</code> удаляется в пользу объекта <code>customer</code>. Затрагивает вызывающих на 2025-06-15, парсящих <code>amount</code> как строку, что является умолчанием для незакреплённых клиентов, созданных до июня 2025 года. Миграция: парсите <code>amount</code> как целое число и читайте имя из <code>customer.name</code>. Закрепите <code>X-Api-Version: 2026-11-01</code>, когда будете готовы. Ничего не меняется для вызывающих, не закрепляющих версию.</p> </blockquote> <p>Последнее предложение — то, что позволяет большинству читательниц перестать читать, и оно принадлежит каждому объявлению версии. Страница <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> включает записи от API, версионирующих таким образом, и разница между хорошими и остальными в основном в этом последнем предложении.</p> <h2>Кого уведомляют, когда версия меняется?</h2> <p>Всех на старой версии, индивидуально, и changelog для всех остальных. Изменение версии — это единственный случай, когда «мы опубликовали об этом что-то» гарантированно пропускает именно тех вызывающих, которые важны: тех, кто закрепил версию два года назад и с тех пор не читал заметки о релизе. Данные об использовании отвечают, кто они; уведомление должно достичь их там, где их код, в заголовках ответа и в сообщении владелице аккаунта.</p> <p>В цикле, который мы выполняем, запись, объявляющая версию, составляется из pull request, который её выпускает, рецензируется человеком, и публикуется на <a href="https://changeloop.dev/docs">ленте и виджете</a>, где версионированный клиент может прочитать её как JSON. Каждый, чей отзыв из виджета просил об изменении или сообщал о баге, который оно решает, и стал GitHub issue, который закрывает этот pull request, уведомляется в этом issue, как только запись выходит в эфир. Механизм тот же, что и для любой записи; скачок версии — это просто запись с самой высокой ставкой.</p> <h2>FAQ</h2> <p><strong>Должно ли каждое изменение API получать новую версию?</strong> Нет. Только изменения, ломающие совместимость. Аддитивные изменения выпускаются под текущей версией с записью changelog. Версионирование аддитивных изменений учит вызывающих игнорировать версии.</p> <p><strong>Лучше ли версионирование через URL, чем через заголовок?</strong> Версионирование через URL легче видеть вызывающим и сложнее вам развивать постепенно; версионирование через заголовок наоборот. Для публичного API с множеством мелких клиентов версионирование через URL проваливается реже. Для крупного API со слоем трансляции датированная версия через заголовок масштабируется лучше.</p> <p><strong>Сколько версий следует поддерживать одновременно?</strong> Настолько мало, насколько позволяет ваше окно поддержки, и никогда неограниченное число. Две или три параллельные версии — это нормально; больше обычно означает, что версии не выводятся из эксплуатации.</p> <p><strong>Что должны получать невероенные запросы?</strong> Самую старую поддерживаемую версию, чтобы существующие незакреплённые клиенты продолжали работать, с заголовком ответа, сообщающим им, какую версию они получили.</p> </article> <article> <h1>Breaking changes: что считается и как выпустить</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Breaking change это изменение, которое корректно написанный вызывающий не смог бы пережить. Определение важно, потому что большинство споров о том, «считается» ли что-то, на самом деле споры о том, кто держал это неправильно. Если вызывающий следовал вашей документации, а ваше изменение заставило его код перестать работать, изменение было breaking. Ваши намерения к этому не имеют никакого отношения.</p> <p>Это весь тест. Остальная часть этой статьи посвящена тому, что из него следует: что его не проходит, что проходит, как поймать провал до слияния и что делать, как только вы знаете, что выпускаете такое.</p> <h2>Что считается breaking change?</h2> <p>Применяйте тест к вызывающему, а не к диффу. Изменение является breaking, когда вызывающий, полагавшийся только на документированное поведение, должен изменить свой код, конфигурацию или данные, чтобы продолжить работать. Удаление поля, переименование endpoint, ужесточение валидации, изменение значения по умолчанию и изменение типа значения, всё это квалифицируется. Добавление опционального поля, нет. Исправление бага обычно нет, с одним важным исключением ниже.</p> <table> <thead> <tr> <th>Изменение</th> <th>Breaking?</th> <th>Почему</th> </tr> </thead> <tbody><tr> <td>Удаление или переименование поля, endpoint, флага или опции</td> <td>Да</td> <td>Корректные вызывающие ссылаются на это</td> </tr> <tr> <td>Добавление опционального поля или нового endpoint</td> <td>Нет</td> <td>Существующие вызовы не меняются</td> </tr> <tr> <td>Превращение опциональной входной величины в обязательную</td> <td>Да</td> <td>Вызовы, опускавшие её, теперь падают</td> </tr> <tr> <td>Ужесточение ранее принимавшейся валидации</td> <td>Да</td> <td>Входные данные, которые работали, теперь отклоняются</td> </tr> <tr> <td>Изменение значения по умолчанию</td> <td>Да</td> <td>Вызывающие, не установившие его, получают новое поведение</td> </tr> <tr> <td>Изменение типа (строка в число, единичное значение в массив)</td> <td>Да</td> <td>Парсеры, написанные под документированный тип, падают</td> </tr> <tr> <td>Изменение порядка ключей объекта</td> <td>Нет</td> <td>Если только вы не документировали порядок</td> </tr> <tr> <td>Исправление бага, на который полагались вызывающие</td> <td>На практике да</td> <td>См. раздел о случайных контрактах</td> </tr> <tr> <td>Повышение лимита частоты или размера</td> <td>Нет</td> <td>Ничто из работавшего не перестаёт работать</td> </tr> <tr> <td>Понижение лимита частоты или размера</td> <td>Да</td> <td>Трафик, который был в порядке, теперь ограничивается</td> </tr> <tr> <td>Изменение формулировки сообщения об ошибке</td> <td>Зависит</td> <td>Breaking, если вы это документировали или вызывающие сопоставляют с ним</td> </tr> </tbody></table> <h2>Что не является breaking change?</h2> <p>Изменение не breaking, когда каждый вызов, который работал раньше, по-прежнему работает без изменений и значит то же самое. Новый endpoint, опциональный параметр запроса, новое поле в ответе, превращение обязательного входного значения в опциональное, повышение лимита и улучшение сообщения об ошибке, с которым никто не сопоставляет, проходят тест. Такие аддитивные изменения можно выпускать в минорном релизе с обычной записью в changelog.</p> <p>Аддитивные изменения всё же ломают вызывающих в трёх случаях. Клиент, чей десериализатор отклоняет неизвестные поля, падает на первом же новом поле ответа, поэтому заранее документируйте, что вызывающие должны игнорировать незнакомые поля. Новое значение enum ломает каждого вызывающего с исчерпывающим switch (подробнее ниже). А растущий ответ может вытолкнуть вызывающего за лимит размера, таймаут или ширину столбца, о которых ему не приходилось думать.</p> <p>Четыре строки таблицы заслуживают более пристального взгляда, потому что именно там возникают разногласия.</p> <h2>Четыре breaking change, которые упускают команды</h2> <p><strong>Случайные контракты.</strong> Если ваш API три года возвращал одно и то же недокументированное поле, вызывающий на это опирался. <a href="https://www.hyrumslaw.com/">Закон Хайрума</a>: короткая версия: при достаточном числе пользователей каждое наблюдаемое поведение вашей системы будет от кого-то зависимым. Вот почему «это было исправление бага», не защита. Исправление может быть корректным и всё равно быть breaking. Выпустите его как таковое.</p> <p><strong>Изменения поведения без изменения схемы.</strong> Поле всё ещё там, тип тот же, а значение теперь означает что-то другое. <code>status</code>, который был <code>active</code> или <code>inactive</code>, а теперь также возвращает <code>suspended</code>, ломает каждого вызывающего с исчерпывающим switch. Timestamp, переходящий с локального времени на UTC, ломает всех, кто не прочитал документацию дважды. Ничто в диффе файла OpenAPI этого не показывает.</p> <p><strong>Ужесточённая валидация.</strong> Вы начинаете отклонять email без TLD, или пробелы в конце, или имена длиннее 80 символов. Каждый вызывающий, отправлявший ровно это, теперь получает 400 на запрос, который работал на прошлой неделе. Изменения валидации чаще всего выпускаются как исправление «усиления».</p> <p><strong>Изменённые значения по умолчанию.</strong> Никто, кто установил значение явно, ничего не замечает. Все, кто этого не сделал, а это большинство вызывающих, получают новое поведение, не меняя ни строки. Изменённое значение по умолчанию ломает большинство ваших пользователей именно потому, что они никогда не видели эту настройку.</p> <h2>Как обнаружить breaking change до выпуска?</h2> <p>Сравните контракт в pull request с контрактом в основной ветке, в CI, и провалите сборку при breaking-различии. Инструменты сравнения схем есть для большинства форматов интерфейсов, и каждый знает правила breaking для своего формата:</p> <table> <thead> <tr> <th>Интерфейс</th> <th>Инструмент</th> <th>Что сравнивает</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Две спецификации OpenAPI, с отчётом о breaking changes</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td>Файлы <code>.proto</code>, на уровне wire или исходного кода</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Две схемы, с пометкой breaking и опасных изменений</td> </tr> <tr> <td>Rust crates</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>Публичный API против последней опубликованной версии</td> </tr> <tr> <td>Пакеты TypeScript</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Закоммиченный отчёт о публичном API пакета</td> </tr> </tbody></table> <p>Эти инструменты надёжно ловят удалённые поля, переименованные операции и изменённые типы. Они не видят первые два из четырёх видов выше, случайный контракт и изменение поведения, потому что ни то, ни другое не отражается в схеме. Используйте инструмент, чтобы остановить очевидные случаи, а для остальных вопрос на ревью: «заметит ли это корректный вызывающий?». Тот же CI-джоб, естественное место, чтобы требовать запись в changelog, как описано в <a href="https://changeloop.dev/blog/ru/changelog-ci-enforcement/">проверке записей changelog в CI</a>, а <a href="https://changeloop.dev/blog/ru/grpc-protobuf-api-changes/">изменения API gRPC и Protobuf</a> разбирают случаи на уровне wire.</p> <h2>Как пометить breaking change в коммите?</h2> <p>В <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a> breaking change помечается <code>!</code> перед двоеточием (<code>feat(api)!: remove the legacy export endpoint</code>) или футером, начинающимся с <code>BREAKING CHANGE:</code> и описанием. Любой из вариантов соответствует major версии. Пишите футер как первый черновик записи в changelog: кого это затрагивает и что им нужно сделать. <a href="https://changeloop.dev/blog/ru/conventional-commits-changelog/">Conventional commits и changelog</a> разбирает, как далеко вас доводит это соглашение.</p> <p>То же правило действует для библиотек. Удалённая публичная функция, суженный тип параметра или изменённое возвращаемое значение, это major версия по семантическому версионированию. Библиотеки соблюдают его не всегда: <a href="https://arxiv.org/abs/2110.07889">исследование 119 879 обновлений в Maven Central</a> показало, что 16,6% нарушили семантическое версионирование, но затронули лишь 7,9% клиентских проектов, потому что большинство этих изменений касалось кода, который ни один клиент не вызывал. Поломку измеряют у вызывающего.</p> <h2>Как выпускается breaking change?</h2> <p>Вы выпускаете его открыто, с датой, с путём. Шаги ниже в порядке, и последний, тот, который пропускает большинство команд: сказать людям, кого это затронуло, что то, чего они ждали, теперь произошло.</p> <ol> <li><strong>Решите, является ли это им.</strong> Используйте тест выше, а не дифф. Если два инженера не согласны, это breaking; несогласие, доказательство того, что вызывающий мог разумно полагаться на старое поведение.</li> <li><strong>Версионируйте это.</strong> По <a href="https://semver.org/">семантическому версионированию</a> breaking change, это major версия. Если вы работаете с датированным или версионированным API, это идёт в новую версию, а старая продолжает работать до объявленной даты. Если вы не можете версионировать, вы не выпускаете breaking change, вы выпускаете сбой с записью в changelog. Какая схема несёт версию, тема <a href="https://changeloop.dev/blog/ru/api-versioning-best-practices/">лучших практик версионирования API</a>.</li> <li><strong>Напишите запись до объединения кода.</strong> У записи фиксированная форма: что меняется, кого затрагивает, что им нужно сделать, и до когда. Если вы не можете заполнить все четыре, изменение не готово. <a href="https://changeloop.dev/release-notes-template">Шаблон release notes</a> ставит эти записи первыми, с датой вместо номера версии, именно поэтому.</li> <li><strong>Дайте дедлайн, а не номер релиза.</strong> «Удалено в v5» ничего не значит для того, кто не следит за вашими релизами. «Перестаёт работать 1 ноября 2026 года» значит одно и то же для всех.</li> <li><strong>Предоставьте миграцию.</strong> Пример кода старого вызова рядом с новым. Если изменение переименование, назовите оба имени в одном предложении. Если это удалённое поле, скажите, куда делись данные.</li> <li><strong>Объявите везде, где было документировано старое поведение.</strong> Changelog, страницу документации, описывающую endpoint, release notes SDK, и заголовок депрекации в ответе, если он у вас есть. Объявленное в одном месте объявлено людям, которые случайно туда посмотрели.</li> <li><strong>Замкните петлю.</strong> Если клиентка попросила изменение, или сообщила о баге, который к нему привёл, скажите ей, когда оно выпущено. Это шаг, превращающий это из чего-то, сделанного с вашими пользователями, в что-то, сделанное вместе с ними.</li> </ol> <h2>Как выглядит хорошая запись о breaking change?</h2> <p>Хорошая запись называет затронутого вызывающего в первой строке, объявляет дату, и включает исправление. Вот одна для случая ужесточённой валидации, в форме, которую мы используем:</p> <blockquote> <p><strong>Адреса электронной почты без домена отклоняются с 1 ноября 2026 года.</strong> <code>POST /users</code> и <code>PATCH /users/:id</code> в настоящее время принимают значения <code>email</code> вроде <code>alice@localhost</code>. С 1 ноября они возвращают <code>400 invalid_email</code>. Затрагивает любую интеграцию, создающую пользователей из внутренних каталогов. Миграция: отправьте полностью квалифицированный адрес, или опустите поле и установите его позже. Никаких изменений не требуется, если ваши адреса уже имеют домен, что верно для 99,4% аккаунтов, созданных в этом году.</p> </blockquote> <p>Где место этому уведомлению, и что ещё должно быть рядом с ним, разбирает <a href="https://changeloop.dev/blog/ru/api-changelog/">changelog API</a>.</p> <p>Процент в конце, не украшение. Он говорит читательнице, стоит ли ей беспокоиться, что и есть вопрос, с которым она открыла запись.</p> <h2>Почему бы просто не избегать их?</h2> <p>Потому что альтернатива хуже. API, который никогда ничего не ломает, накапливает каждую ошибку, которую когда-либо совершил: неправильно названное поле, неверное значение по умолчанию, timestamp в локальном времени. Каждая из них, налог на каждого нового вызывающего навсегда, чтобы защитить вызывающих, которые могли бы мигрировать за один вечер. Команды с лучшей репутацией стабильности ломают вещи редко, по расписанию, с путём миграции и предупреждением, дошедшим до людей, для кого оно предназначалось.</p> <p>Механика этого предупреждения, тема сопутствующей статьи о <a href="https://changeloop.dev/blog/ru/api-deprecation/">депрекации API</a>. Запись, объявляющая это, составляется так же, как любая другая запись в <a href="https://changeloop.dev/docs">ленте changelog</a>: из объединённого pull request, удержанная для человека, затем опубликованная там, где затронутые вызывающие уже читают.</p> <h2>FAQ</h2> <p><strong>В чём разница между breaking и non-breaking изменением?</strong> Breaking change заставляет корректного вызывающего менять код, конфигурацию или данные, чтобы продолжить работать. Non-breaking оставляет каждый существующий вызов рабочим с тем же значением, поэтому добавления обычно безопасны, а удаления, переименования и ужесточённые правила обычно нет.</p> <p><strong>Считается ли добавление обязательного поля?</strong> Да. Каждый существующий вызов его опускает, поэтому каждый существующий вызов теперь падает. Добавьте его как опциональное с разумным значением по умолчанию, или версионируйте endpoint.</p> <p><strong>Считается ли исправление бага?</strong> Может быть. Если вызывающие полагались на ошибочное поведение, исправление его ломает их, независимо от того, что говорила документация. Относитесь к любому исправлению, меняющему наблюдаемый вывод, как к breaking, если только вы не можете показать, что никто на него не полагался.</p> <p><strong>Применяется ли семантическое версионирование к веб-API?</strong> Правило да: breaking change получают новую major версию, а старая продолжает работать в течение объявленного периода. Номер часто живёт в URL или заголовке даты, а не в версии пакета.</p> <p><strong>Сколько предупреждения достаточно?</strong> Достаточно, чтобы вызывающий нашёл уведомление и выполнил работу. Девяносто дней, обычный минимум для публичных API; дольше для всего, используемого в коде, отправляемом конечным пользователям и не обновляемом удалённо.</p> </article> <article> <h1>Замыкание петли обратной связи со стороны changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Петля обратной связи клиента замкнута, когда человеку, давшему обратную связь, сообщают, что с ней произошло. Не когда она зарегистрирована. Не когда приоритизирована. Даже не когда выпущена. Когда ему говорят. Большинство команд хорошо выполняют первые три шага и совсем не выполняют последний, а потом удивляются, почему люди, отправляющие обратную связь, перестают её отправлять.</p> <p>Эта статья о том последнем шаге, и о конкретном утверждении: changelog — верное место для замыкания петли, потому что это единственный артефакт, уже существующий именно в тот момент, когда петлю можно замкнуть.</p> <h2>Что такое петля обратной связи клиента?</h2> <p>Петля обратной связи клиента — это путь от пользователя, говорящего вам что-то, до этого пользователя, узнающего, что вы с этим сделали. У неё четыре шага: сбор обратной связи, решение, что с ней делать, выпуск результата, и уведомление запросившего. Петля открыта, пока не произойдёт четвёртый шаг. У команды, собирающей обратную связь и выпускающей исправления, но никогда никого не уведомляющей, есть почтовый ящик, а не петля.</p> <table> <thead> <tr> <th>Шаг</th> <th>Что происходит</th> <th>Где обычно рвётся</th> </tr> </thead> <tbody><tr> <td>Сбор</td> <td>Обратная связь приходит: виджет, поддержка, продажи, интервью</td> <td>Ничего; каждая команда это делает</td> </tr> <tr> <td>Решение</td> <td>Триаж, объединение с дубликатами, принятие или отклонение</td> <td>Отклонения никогда не сообщаются</td> </tr> <tr> <td>Выпуск</td> <td>Кто-то это строит, и это выходит в эфир</td> <td>Ссылка на запрос теряется при merge</td> </tr> <tr> <td>Уведомление</td> <td>Запросивший узнаёт, что выпущено</td> <td>Пропускается, или делается только для самого громкого запросившего</td> </tr> </tbody></table> <p>Четвёртая строка — то, о чём эта статья. Она рвётся по структурной причине, а не культурной: к моменту выпуска функции запрос, вызвавший её, живёт в другой системе, чем выпущенная вещь, и соединение их — не чья-то обязанность. Петля начинается раньше, с того, как запрос вообще запрашивается; формулировки и время описаны в статье <a href="https://changeloop.dev/blog/ru/how-to-ask-for-customer-feedback/">как попросить обратную связь у клиентов</a>.</p> <h2>Почему петли обратной связи остаются открытыми?</h2> <p>Петли обратной связи остаются открытыми, потому что запрос и выпущенное изменение живут в разных местах, а связь между ними устанавливается вручную, если вообще устанавливается. Запрос в инструменте обратной связи, ящике поддержки или таблице. Изменение в pull request. Объявление в changelog или письме. Три системы, три владельца, и ссылка от третьей обратно к первой — это человек, вспоминающий месяцы спустя, кто спрашивал.</p> <p>Есть вторая причина. Шаг уведомления обычно оформляется как маркетинговая задача («объявить функцию») вместо задачи поддержки («ответить человеку»). Объявления идут всем и не достигают никого конкретно. Человек, попросивший функцию в марте, читает объявление в июне, если вообще читает, как новость, а не как ответ. Петля замыкается, только если сообщение адресовано ему.</p> <h2>Почему замыкать петлю со стороны changelog?</h2> <p>Потому что запись changelog — единственный артефакт, существующий именно в правильный момент, содержащий именно правильные слова, и написанный именно правильным человеком. Она существует, когда изменение в эфире, и не раньше. Она говорит, что изменилось, словами читательницы, что и есть сообщение, в котором нуждается запросивший. И написана кем-то, кто только что прочитал pull request, что является единственным моментом, когда ссылка на исходный запрос всё ещё видна.</p> <p>Сравните альтернативы. Замыкание петли из инструмента обратной связи означает, что инструменту обратной связи нужно знать, когда функция выпущена, что означает, что кто-то вручную обновляет статус. Замыкание её из pull request означает уведомление клиентки при merge, до того как изменение в эфире, нарушенное обещание с временной меткой, как только развёртывание задерживается. Замыкание её из маркетингового объявления означает ожидание такового, а большинство выпущенных изменений его никогда не получают.</p> <p>Changelog находится посередине: после merge, в момент релиза, с готовой формулировкой.</p> <h2>Как замыкается петля, шаг за шагом</h2> <p>Это механизм, который мы выполняем. Он описан здесь как спецификация, а не как тур по продукту, потому что каждый шаг можно выполнить вручную или другими инструментами; важен порядок.</p> <ol> <li><strong>Обратная связь становится issue в репозитории, который её исправит.</strong> Отправка через виджет регистрируется как помеченный issue на GitHub (<code>feature-request</code> или <code>bug</code>, приоритет, и <code>from-widget</code>), причём адрес электронной почты отправителя в тело issue не попадает. Issue живёт рядом с кодом, чтобы шаг три мог его найти. Issue, созданный вручную, например по <a href="https://changeloop.dev/blog/ru/feature-request-template/">шаблону запроса функции</a>, находится вне этого пути: шаг пять его не комментирует, так что эту петлю замыкайте сами.</li> <li><strong>Исправление ссылается на issue.</strong> Pull request говорит <code>Fixes #142</code>, собственное ключевое слово закрытия GitHub. Ничего нового учить не нужно, и это то же предложение, которое разработчицы уже пишут.</li> <li><strong>Запись changelog составляется из объединённого pull request и несёт ссылку.</strong> При merge черновик создаётся, а <code>#142</code> читается из тела PR и прикрепляется к черновику. Ссылка создаётся, пока ещё дёшево, машиной, из данных, которые уже там есть.</li> <li><strong>Человек рецензирует запись.</strong> Формулировку, аудиторию, стоит ли вообще публиковать. Выброшенный черновик ничего не замыкает, что верно: внутренний рефакторинг, случайно сославшийся на issue, — не новость.</li> <li><strong>При одобрении запросивший уведомляется.</strong> Комментарий публикуется в issue, которым стал его отзыв, «Shipped —» затем заголовок записи и ссылка на опубликованную запись, а виджет показывает отправителю ту же выпущенную запись. Один раз, никогда дважды, и только после того, как человек опубликовал запись. Та же запись выходит через <a href="https://changeloop.dev/docs">ленту и виджет</a> всем, кто не спрашивал.</li> </ol> <p>Порядок в пятом шаге — весь дизайн. Уведомление запросившего при merge было бы раньше и легче, и было бы неверным примерно так же часто, как задерживаются развёртывания. Feature flag ломает даже этот порядок, потому что одобрено и опубликовано может произойти, пока функция всё ещё невидима для аккаунта запросившего; <a href="https://changeloop.dev/blog/ru/feature-flags-feature-requests/">feature flag и запросы на функции</a> разбирает дополнительную проверку, которая нужна этому шагу, как только задействован флаг.</p> <h2>Как выглядит замкнутая петля для клиентки?</h2> <p>Она выглядит как ответ. Клиентка отправила запрос через виджет, и однажды виджет показывает его выпущенным, со ссылкой на запись, описывающую это её словами; на GitHub issue получает ту же новость в виде комментария. Она не подписалась на рассылку, не проверяла roadmap, не искала в changelog. Ей сказали.</p> <p>Это опыт, заставляющий случиться следующий кусок обратной связи. Люди отправляют обратную связь продуктам, которые отвечают. Страница <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> включает записи от команд, чьи пользователи явно продолжают возвращаться с запросами, и общая нить не в инструменте; она в том, что записи читаются как ответы.</p> <h2>Как измерить петлю обратной связи?</h2> <p>Измеряйте долю выпущенных изменений, уведомивших хотя бы одного запросившего, и время от выпуска до уведомления. Два числа, оба лёгкие, как только ссылка существует, и невозможные до этого.</p> <ul> <li><strong>Коэффициент замыкания</strong>: из записей changelog, опубликованных в этом месяце, сколько связаны хотя бы с одним запросом, и из них, сколько уведомили запросившего. Если второе число намного ниже первого, уведомления проваливаются; если первое низкое, запросы не связываются из pull request, и исправление — это одно предложение в шаблоне PR.</li> <li><strong>Время от выпуска до уведомления</strong>: сколько времени между выходом записи в эфир и уведомлением запросившего. С механизмом выше это секунды. Вручную это обычно недели, или никогда, и «никогда» — число, которое важно.</li> </ul> <p>Не измеряйте петлю по объёму собранной обратной связи. Сбор — лёгкий шаг, и команда, которая его измеряет, будет его оптимизировать, что производит больше открытых петель.</p> <h2>Где вписывается roadmap?</h2> <p>Публичная roadmap — это способ замкнуть петлю раньше: она говорит запросившим, что их запрос услышан, до его выпуска. Она полезна, и не заменяет последний шаг. «Запланировано» — это обещание о будущем; «Выпущено» — это факт о настоящем. Ведите <a href="https://changeloop.dev/blog/ru/public-roadmap/">публичную roadmap</a> из тех же issue, с одной меткой на колонку, чтобы один и тот же запрос переходил от запланированного к выпущенному без повторного ввода где-либо. Перевод в выпущенное делается сменой метки (<code>roadmap:shipped</code>), которую никто не сделает за вас при одобрении записи, так что делайте это в том же ревью.</p> <h2>FAQ</h2> <p><strong>Каковы четыре шага петли обратной связи клиента?</strong> Сбор, решение, выпуск, уведомление. Петля открыта, пока не произойдёт четвёртый шаг. Большинство фреймворков добавляют шаги анализа и приоритизации в середине; это уточнения «решения», и ни один из них ничего не замыкает.</p> <p><strong>Следует ли уведомлять клиентов, когда запрос отклонён?</strong> Да, и это самое пренебрегаемое сообщение в петле. Чёткое «мы не будем это делать, и вот почему» заканчивает ожидание. Молчание оставляет петлю открытой навсегда, а клиентку — проверяющей.</p> <p><strong>Чем замыкание петли отличается от объявления функции?</strong> Объявление идёт всем. Замыкание петли — это ответ людям, которые спрашивали, по каналу, через который они спрашивали. Делайте оба; это разные сообщения для разных читательниц.</p> <p><strong>А если запросившего нет на GitHub?</strong> Большинства там нет, и это нормально. Виджет продолжает показывать им статус того, что они отправили, включая выпущенную запись и её ссылку, так что им не нужно ничего, кроме страницы, с которой они писали. Комментарий в issue предназначен для тех, кто видит репозиторий.</p> <p><strong>Работает ли эта петля с GitLab или Bitbucket вместо GitHub?</strong> Виджет и changelog работают; автоматический комментарий на шаге пять пока нет. Команда на GitLab или Bitbucket всё равно получает каждую заявку, всё равно заводит её как issue и всё равно показывает запросившему статус в виджете, но замыкание именно этой петли обратно на сам issue приходится делать вручную, пока такая интеграция не появится.</p> </article> <article> <h1>Шаблон запроса функции, становящийся changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Шаблон запроса функции — это форма с четырьмя вопросами: что пытается сделать человек, что его останавливает, что он попробовал вместо этого, и как он хочет быть уведомлён, когда это будет готово. Всё остальное, что обычно появляется на такой форме, селекторы приоритета, оценки усилий, баллы бизнес-ценности, предназначено для команды, получающей запрос, и неправильно заполняется отправителем.</p> <p>Аккуратные запросы — неправильный тест для шаблона. Правильный: шесть месяцев спустя, когда функция выпущена, может ли кто-то найти запрос, понять его, и уведомить человека, который его написал? Большинство шаблонов спроектированы для приёма. Этот спроектирован для дня, когда петля замыкается.</p> <h2>Что должен включать шаблон запроса функции?</h2> <p>Он должен включать цель, блокер, обходной путь, и путь обратно к запросившему. Четыре поля, в этом порядке, каждое отвечает на вопрос, который команда задаст позже.</p> <table> <thead> <tr> <th>Поле</th> <th>Вопрос, на который отвечает позже</th> <th>Почему оно в форме</th> </tr> </thead> <tbody><tr> <td>Что вы пытаетесь сделать?</td> <td>Была ли построенная функция той, что нужна?</td> <td>Цель переживает любое конкретное предложение</td> </tr> <tr> <td>Что вас останавливает сегодня?</td> <td>Как выглядит «готово»?</td> <td>Называет пробел, не предписывая исправление</td> </tr> <tr> <td>Что вы делаете вместо этого?</td> <td>Насколько это на самом деле срочно?</td> <td>Болезненный обходной путь — более сильный сигнал, чем селектор приоритета</td> </tr> <tr> <td>Как нам вас уведомить?</td> <td>Кто получает сообщение «выпущено»?</td> <td>Поле, которое чаще всего пропускают шаблоны</td> </tr> </tbody></table> <p>Что намеренно отсутствует: предложенное решение как обязательное поле (желанное в комментарии, неверное как рамка), селектор приоритета (каждый отправитель выбирает высокий), и любая оценка усилий или ценности (работа команды, после триажа). Шаблон, просящий решение, получает запросы на кнопки; шаблон, просящий цель, получает запросы на результаты, и о результатах пишется запись changelog.</p> <h2>Шаблон</h2> <p>Это шаблон issue GitHub, который мы используем, в виде формы. Вставьте его в <code>.github/ISSUE_TEMPLATE/feature_request.yml</code>, и он отрендерится как структурированная форма на странице нового issue. Запросы, поданные через него, попадают как issue с теми же полями, что и поданные через виджет обратной связи, что важно для следующего раздела.</p> <pre><code class="language-yaml">name: Feature request description: What you are trying to do, and what stops you. labels: ["feature-request"] body: - type: textarea id: goal attributes: label: What are you trying to do? description: >- The outcome, not the button. "Export a month of invoices as one PDF" beats "add a PDF export". validations: required: true - type: textarea id: blocker attributes: label: What stops you today? description: >- Where the product runs out. An error, a missing option, a limit. validations: required: true - type: textarea id: workaround attributes: label: What do you do instead? description: >- The spreadsheet, the script, the manual step. "Nothing, I gave up" is a valid answer. - type: input id: contact attributes: label: How should we tell you when it ships? description: >- An email address, or leave blank to be notified only on this issue. </code></pre> <p>Две детали выполняют работу. <code>labels: ["feature-request"]</code> означает, что запрос классифицируется при создании, вместо того чтобы ждать, пока кто-то его триажирует. А последнее поле существует, потому что «мы дадим вам знать» — это обещание, а обещанию нужен адрес.</p> <h2>Какие метки должен нести запрос функции?</h2> <p>Запрос функции должен нести одну метку для того, что он есть, одну для того, насколько он срочен, и одну для того, откуда он пришёл. Три метки, три оси, и каждую читает другая читательница.</p> <table> <thead> <tr> <th>Метка</th> <th>Значения</th> <th>Кто читает</th> </tr> </thead> <tbody><tr> <td>Тип</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Кто решает, в какую очередь он попадает</td> </tr> <tr> <td>Приоритет</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Кто планирует следующий цикл</td> </tr> <tr> <td>Источник</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Кто измеряет, откуда приходят запросы</td> </tr> </tbody></table> <p>Виджет применяет первые две оси и <code>from-widget</code>, когда подаёт отправку как issue; <code>from-form</code> и <code>from-support</code> предлагаются для запросов, приходящих другими путями. Метки виджета такие: тип (<code>bug</code> или <code>feature-request</code>, решаемый классификатором только по сообщению), приоритет (спокойный, конкретный отчёт о сбое высокий; дубликат чего-то уже спрошенного низкий; всё, что даже намекает на проблему безопасности, — <code>bug</code> и высокий, независимо от формулировки), и <code>from-widget</code>. Те же три оси работают для запросов, приходящих вручную через шаблон выше, и в этом суть: запрос — это запрос, независимо от того, откуда он вошёл.</p> <p>Ещё одна конвенция: виджет удаляет адрес электронной почты отправителя из тела issue перед подачей, потому что issue живёт в репозитории, который может быть публичным, и заменяет его ссылкой на отправку. Адрес в issue не попадает; отправитель следит за результатом в самом виджете. Делайте то же самое с полем контакта, если ваш трекер виден людям вне команды.</p> <h2>Как запрос функции становится записью changelog?</h2> <p>Запрос функции становится записью changelog, когда pull request закрывает issue, а запись, составленная из этого pull request, связывается обратно. Механизм — собственные ключевые слова закрытия GitHub: PR, чьё описание говорит <code>Fixes #142</code>, закрывает issue 142 при merge. Если ваши записи changelog составляются из объединённых pull request, черновик может нести номер issue с собой, и запись знает, кто спрашивал.</p> <p>Вот почему шаблон просит цель вместо решения. Когда запись пишется, цель — это предложение, нужное автору: «Теперь вы можете экспортировать месяц счетов как один PDF» — это запись changelog. «Добавлен экспорт PDF» — это сообщение коммита. <a href="https://changeloop.dev/changelog-tools">Инструменты для changelog</a>, составляющие записи из pull request, могут выполнить сбор и связь; формулировка всё ещё нуждается в человеке, и человеку нужна цель.</p> <h2>Что происходит, когда это выпущено?</h2> <p>Запросивший уведомляется со ссылкой на запись. В нашей настройке это происходит автоматически для запросов, пришедших через виджет: комментарий, говорящий «Shipped — <заголовок записи>» со ссылкой на опубликованную запись, размещённый на issue, как только человек одобряет запись, а виджет показывает отправителю ту же запись. Issue, поданный вручную по этому шаблону, автоматического комментария не получает; замыкайте эту петлю сами, по тому же правилу. Комментарий намеренно размещается при одобрении, а не при merge: комментарий, говорящий, что что-то в эфире до того, как это так, — это нарушенное обещание с временной меткой. Каждый запрос уведомляется не более одного раза; второе одобрение той же записи не создаёт второй комментарий.</p> <p>Если вы делаете это вручную, применяется то же правило. Не замыкайте петлю из pull request. Замыкайте её из опубликованной записи, и замыкайте один раз. <a href="https://changeloop.dev/docs">Лента и виджет</a> несут ту же запись всем, кто не спрашивал, что большинство; комментарий для тех, кто спрашивал.</p> <h2>Почему большинство шаблонов запросов функций проваливаются</h2> <p>Они спроектированы, чтобы облегчить триаж, и им это удаётся, ценой единственного момента, важного для запросившего. Шаблон с двенадцатью полями получает меньше запросов, а те, что получает, приходят от людей с терпением заполнить двенадцать полей, что не та же популяция, что нуждается в функции. Шаблон с четырьмя полями, одно из которых «как с вами связаться», получает больше запросов и может почтить каждый из них.</p> <h2>FAQ</h2> <p><strong>Должен ли шаблон запроса функции спрашивать о приоритете?</strong> Нет. Спрашивайте вместо этого об обходном пути. «Я экспортирую в таблицу и перепечатываю каждую пятницу» говорит о приоритете больше, чем выпадающий список, который отправитель поставил на высокий.</p> <p><strong>Должны ли запросившие предлагать решение?</strong> Могут, в свободном тексте. Не делайте это рамкой. Запросы, написанные как решения, труднее объединять друг с другом и труднее превращать в запись changelog.</p> <p><strong>Должны ли запросы функций появляться в публичной roadmap?</strong> После планирования да: метка на том же issue помещает его в колонку запланировано, и запросивший может видеть, как он движется. Статья <a href="https://changeloop.dev/blog/ru/public-roadmap/">публичная roadmap</a> — это механизм.</p> <p><strong>Как обрабатывать дубликаты?</strong> Свяжите новый запрос с существующим issue и пометьте его низким приоритетом; не закрывайте его. Каждый дубликат — ещё один человек для уведомления при выпуске. С автоматическим комментарием Changeloop этот человек уведомляется, только если pull request называет и его issue (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Где должен жить шаблон?</strong> В репозитории, который получит pull request, чтобы работало ключевое слово закрытия. Запрос в отдельном трекере должен связываться вручную при merge, и именно этот шаг пропускается.</p> </article> <article> <h1>Публичная roadmap из вашего issue-трекера, три колонки</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Публичная roadmap — это список того, что вы намерены построить, опубликованный там, где клиенты могут его увидеть. Слово, выполняющее работу, — <em>намерены</em>: roadmap — это набор обещаний о будущем, и каждый элемент в ней — тот, который вы либо сдержите, либо станет видно, что не сдержали. Это причина публиковать её, и это также причина, по которой большинство публичных roadmap устаревают за квартал. Версия, которая выживает, маленькая, выведена из данных, которые вы уже поддерживаете, и связана на другом конце с changelog, чтобы обещание становилось фактом без того, чтобы кто-то его повторно вводил.</p> <h2>Для чего нужна публичная roadmap?</h2> <p>Публичная roadmap говорит клиентке с запросом, что её запрос услышан, до его выпуска. Это ранняя половина замыкания петли: «Запланировано» отвечает на вопрос «прочитал ли это кто-то», а «В разработке» отвечает на «действительно ли это происходит». Ни одно из них не заменяет последний шаг, уведомление запросившей при выпуске, но оба уменьшают число людей, спрашивающих тем временем.</p> <p>Это также делает кое-что для команды: заставляет публичное обязательство, что является самым дешёвым известным лекарством против backlog, тихо хранящего четыреста элементов, которые никто не построит.</p> <table> <thead> <tr> <th>Колонка</th> <th>Обещание, которое она даёт</th> <th>Что перемещает элемент в неё</th> </tr> </thead> <tbody><tr> <td>Запланировано</td> <td>Мы намерены это построить</td> <td>Решение, зафиксированное как метка на issue</td> </tr> <tr> <td>В разработке</td> <td>Кто-то работает над этим сейчас</td> <td>Метка <code>roadmap:building</code> на issue</td> </tr> <tr> <td>Выпущено</td> <td>Это в эфире</td> <td>Метка <code>roadmap:shipped</code>, или закрытие issue, пока она на нём стоит</td> </tr> </tbody></table> <p>Трёх колонок в фиксированном порядке достаточно. Четвёртая колонка («рассматривается», «на рецензии», «backlog») — место, где благие намерения становятся музеем, и это первая, которую клиенты учатся игнорировать.</p> <h2>Должна ли ваша roadmap быть публичной?</h2> <p>Сделайте её публичной, если вы можете держать её маленькой и честной; держите её приватной, если альтернатива — длинный список возможно. Цена публичной roadmap не имеет ничего общего с её публикацией: каждый элемент на ней теперь вопрос, который кто-то задаст, в поддержке, в звонках продаж и в разговорах о продлении. Десять элементов, которые вы построите, — это актив. Шестьдесят элементов, которые вы, возможно, построите, — это шестьдесят будущих разговоров о том, почему нет.</p> <p>Две честные причины не публиковать: ваши планы меняются быстрее квартала, или ваши конкуренты читают вашу roadmap внимательнее ваших клиентов. Обе реальны, и обе решаются публикацией меньшего вместо ничего: только «в разработке», с «запланировано», держимым внутренним, всё равно говорит запросившей, что её issue движется.</p> <h2>Как построить публичную roadmap из issue GitHub?</h2> <p>Поместите одну метку на колонку на issue, которые вы уже отслеживаете, и отрендерите помеченные issue как roadmap. Ничто не вводится повторно, roadmap не может отклониться от работы, и один и тот же issue, начавшийся как запрос клиента, движется через колонки, не меняя идентичность.</p> <p>Механизм, как мы его выполняем:</p> <ol> <li><strong>Одна метка на колонку, с фиксированным префиксом</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Любой issue в подключённом репозитории, несущий одну из них, появляется в этой колонке. Issue без ни одной из них не на roadmap, что верно для большинства issue, что правильно.</li> <li><strong>Колонки — это упорядоченный массив, всегда в одном порядке.</strong> Запланировано, в разработке, выпущено. Не карта, индексированная по имени, чтобы читательнице (или виджету) никогда не пришлось угадывать последовательность.</li> <li><strong>Если issue несёт две метки, побеждает наиболее продвинутая.</strong> Кто-то добавит <code>roadmap:shipped</code> до удаления <code>roadmap:planned</code>; конечный автомат, руководимый «какой webhook пришёл последним», поместил бы элемент в разные колонки в зависимости от порядка доставки. Решение только из набора меток делает ответ одинаковым независимо от того, как приходят события.</li> <li><strong>Выпущено это такое же состояние метки, как и остальные.</strong> Карточка перемещается, когда issue получает <code>roadmap:shipped</code> или закрывается, пока эта метка на нём стоит. Сама карточка не ссылается на запись changelog; подробности живут в записи, составленной из pull request, закрывшего issue.</li> <li><strong>Подавайте её как данные.</strong> Roadmap — это документ JSON с этими тремя колонками, опубликованный рядом с лентой changelog с теми же заголовками кэша, чтобы сайт документации, виджет или страница статуса могли отрендерить её без второй интеграции. <a href="https://changeloop.dev/docs">Документация ленты</a> имеет точную форму.</li> </ol> <p>Метка — это немного, о чём просить мейнтейнера, и это вся интеграция. Никакой доски для поддержания синхронизации, никакого отдельного инструмента для входа, и запрос, поданный клиенткой, является элементом на roadmap; при выпуске это тот же элемент.</p> <h2>Что публичная roadmap не должна содержать?</h2> <p>Она не должна содержать даты, оценки, или что-либо, о чём вам было бы стыдно, если бы спросили через девять месяцев. Даты — классическая ошибка: квартал на roadmap становится обязательством в презентации продаж становится тикетом под названием «вы сказали Q3». Колонки говорят достаточно. «В разработке» уже означает «достаточно скоро, что кто-то этим занимается».</p> <p>Она также не должна содержать внутренний backlog. Roadmap с тремястами элементов — это проблема поиска, не обещание, и клиентка, находящая свой запрос на позиции 212, узнала кое-что, что вы не хотели ей говорить.</p> <h2>Как roadmap связывается с changelog?</h2> <p>Roadmap и changelog описывают одни и те же issue с двух сторон, одна для будущего, другая для прошлого. Никто не двигает карточку на отдельной доске. Мейнтейнер меняет метку на issue, с которым уже работал, запись составляется из pull request, а когда человек одобряет запись, запросившая, чей отзыв из виджета стал этим issue, уведомляется на нём. Перевод карточки в выпущено остаётся отдельным шагом, меткой <code>roadmap:shipped</code>, так что сделайте его частью того же ревью; одобрение записи не делает этого за вас.</p> <p>Это та же петля, которую <a href="https://changeloop.dev/blog/ru/customer-feedback-loop/">статья о петле обратной связи</a> описывает со стороны changelog; roadmap — это то, что клиентка видит посередине этого. Обзор <a href="https://changeloop.dev/changelog-tools">инструменты для changelog</a> охватывает, какие продукты предлагают представление roadmap, а какие относятся к ней как к отдельной доске, что и есть разница, решающая, остаётся ли она точной.</p> <h2>Как выглядит хорошая публичная roadmap?</h2> <p>Она выглядит короткой, и каждый элемент на ней — это issue, который может открыть любой. Тест — может ли клиентка перейти от элемента к обсуждению за ним, и от выпущенного элемента к записи, описывающей, что на самом деле изменилось. Roadmap, являющаяся списком названий функций без входа, — это брошюра.</p> <p>Проработанный пример, как JSON, который получил бы виджет:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Три элемента в трёх колонках — это вполне достаточная публичная roadmap. Она говорит, что грядёт, что происходит, и что произошло, и каждая строка проверяема. Ещё пять форматов, от Now/Next/Later до roadmap по результатам, показаны на примерах пунктов в статье <a href="https://changeloop.dev/blog/ru/product-roadmap-examples/">примеры product roadmap</a>.</p> <h2>FAQ</h2> <p><strong>Сколько элементов должна иметь публичная roadmap?</strong> Настолько мало, насколько вы можете защитить. Меньше десяти в общей сложности нормально для маленького продукта; больше тридцати в «запланировано» обычно backlog, замаскированный под roadmap.</p> <p><strong>Должна ли публичная roadmap иметь даты?</strong> Нет. Колонки сообщают последовательность, не создавая дедлайн. Если клиентке нужна дата, это разговор, а не элемент roadmap.</p> <p><strong>Должны ли клиенты голосовать за элементы roadmap?</strong> Голоса измеряют, кто пришёл, а не что важно. Комментарий на issue, объясняющий обходной путь, который они используют сегодня, стоит больше пятидесяти голосов, и стоит что-то голосующему, что и есть суть.</p> <p><strong>Что происходит с отменённым элементом roadmap?</strong> Удалите метку и скажите почему на issue. Публичное «мы не будем это делать» — часть петли, и это сообщение, которое большинство команд никогда не отправляют.</p> </article> <article> <h1>Автоматизация changelog и её пределы</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Автоматизация changelog работает, когда она автоматизирует сбор, классификацию и публикацию, и останавливается на отборе и формулировке. Автоматизируйте всё — и вы доставляете отформатированный git log; не автоматизируйте ничего — и changelog пишется рывками, по памяти, перед релизами. Полезный вопрос в том, какие части автоматизировать, а не сколько.</p> <p>Проекты автоматизации changelog проваливаются в одном из двух направлений, и оба предсказуемы уже с первой встречи по дизайну. Автоматизируйте слишком мало, и changelog становится документом, который кто-то должен обновлять, что означает, что он обновляется рывками, кем бы ни выпала короткая соломинка. Автоматизируйте слишком много, и он превращается в отформатированный git log: полный, точный, и никем не читаемый.</p> <h2>Какие части changelog следует автоматизировать?</h2> <p>Три из четырёх шагов. Сбор и публикацию полностью; классификацию как первый проход с человеческим переопределением; отбор и формулировку никогда.</p> <table> <thead> <tr> <th>Шаг</th> <th>Автоматизировать?</th> <th>Почему</th> </tr> </thead> <tbody><tr> <td>Сбор: изменения из коммитов, PR, тикетов в список</td> <td>Полностью</td> <td>Утомительно, пропускается под дедлайном, машины делают это идеально</td> </tr> <tr> <td>Классификация: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Первый проход, человеческое переопределение</td> <td>Около 80% верно только из метаданных; неверные 20% — это записи, которые важны</td> </tr> <tr> <td>Отбор и формулировка: что сказать читателю, и как</td> <td>Никогда</td> <td>Это вся ценность артефакта</td> </tr> <tr> <td>Публикация: страница, лента, письмо, виджет, Slack</td> <td>Полностью, из одного источника</td> <td>Куда на самом деле уходит большая часть ручных усилий</td> </tr> </tbody></table> <p><strong>Сбор.</strong> Извлечение изменений из места, где они происходят (коммиты, PR, тикеты), и помещение их в список. Автоматизируйте это полностью. Люди плохи в этом, это утомительно, и это шаг, который пропускается под дедлайном. <a href="https://changeloop.dev/blog/ru/conventional-commits-changelog/">Conventional commits</a> или метки PR — обычное сырьё.</p> <p><strong>Классификация.</strong> Решение, является ли что-то Added, Fixed, Changed, Deprecated, Removed или Security. Автоматизируйте первый проход из типа коммита или метки PR, и позвольте человеку переопределить. Точность здесь около восьмидесяти процентов только из метаданных, а неверные двадцать процентов концентрируются именно на записях, которые важны, потому что двусмысленность коррелирует со значимостью.</p> <p><strong>Отбор и формулировка.</strong> Решение о том, что должен узнать читатель, и как это сказать. <strong>Не автоматизируйте это.</strong> Это вся ценность артефакта. Всё остальное — логистика.</p> <p><strong>Публикация.</strong> Доставка готовых записей на страницу, в ленту, письмо, in-app виджет, канал Slack. Автоматизируйте полностью, и из одного источника. Сюда на самом деле уходит большая часть ручных усилий, и почти никто это не считает. Это также шаг, который может сообщить человеку, попросившему изменение, что оно выпущено, что и есть вся суть <a href="https://changeloop.dev/blog/ru/customer-feedback-loop/">замыкания петли обратной связи со стороны changelog</a>. У почтовой половины этого шага своя форма, в <a href="https://changeloop.dev/blog/ru/product-update-email/">шаблоне письма об обновлении продукта</a>.</p> <p>Последний пункт стоит обдумать. Команды склонны видеть changelog как проблему письма, а затем тратят большую часть времени на распространение: копирование записей в инструмент почты, переформатирование для in-app, вставку в Slack, обновление страницы документации. Написание занимает час. Копирование занимает час на каждый релиз, навсегда, и это часть, которую должна иметь машина.</p> <h2>Что происходит, когда граница сдвигается?</h2> <p><strong>Сдвиньте её вверх, и получите дамп git.</strong> Полная автоматизация из коммитов производит <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> и <code>address review comments</code> перед клиентами. Каждая команда, сделавшая это, потом добавила фильтр, и фильтр — это шаг отбора, повторно введённый под другим именем, с худшей эргономикой.</p> <p><strong>Сдвиньте её вниз, и получите рывки.</strong> Полностью ручной сбор означает, что записи пишутся по памяти в момент релиза. Это тот режим, о котором предупреждает <a href="https://changeloop.dev/blog/ru/keep-a-changelog-implemented/">Keep a Changelog</a> с самого начала, и он тихо ухудшается: changelog выглядит поддерживаемым вплоть до той самой недели, когда ни у кого не было времени.</p> <h2>Как выглядит pipeline автоматизации changelog?</h2> <p>Четыре шага, с ровно одними человеческими воротами, размещёнными там, где черновик становится публичным.</p> <ol> <li>При merge выводите черновик записи из PR: тип из метки или префикса коммита, заголовок как первый черновик, ссылка обратно на PR, зафиксированный автор. Поместите его в неопубликованную корзину.</li> <li>Любой может редактировать любой черновик в любой момент, и редактирование дёшево. Большинство получает одну переписанную строку.</li> <li>Выпуск релиза требует, чтобы каждая запись в корзине была либо отредактирована, либо явно помечена как внутренняя. Эти ворота — весь дизайн. Без них черновики выпускаются неотредактированными в загруженную неделю.</li> <li>Публикация — это разветвление из выпущенного набора: публичная страница, лента, письмо, виджет, пост в Slack. Один источник, несколько отображений, без копирования.</li> </ol> <p>Шаг 3 — единственное место, где нужен человек, и он занимает около десяти минут на релиз, как только черновики приличные. Там, где вовлечён запрос клиента, черновик также несёт issue, который он закрывает, что позволяет шагу 4 уведомить попросившего; <a href="https://changeloop.dev/blog/ru/feature-request-template/">шаблон запроса функции</a> спроектирован так, чтобы эта ссылка пережила процесс. Где этот шаг стоит в общем потоке релиза, рассказывает статья <a href="https://changeloop.dev/blog/ru/release-management-process/">процесс управления релизами</a>.</p> <h2>Что автоматизация требует от ваших данных?</h2> <p>Ничего из вышеперечисленного не работает, если changelog — это файл Markdown, потому что файл не может быть отображён на пяти поверхностях без повторного парсинга, а парсинг прозы — это как вы заканчиваете с виджетом, показывающим половину заголовка.</p> <p>Записи должны быть структурированы: тип, дата, версия или идентификатор релиза, аудитория, тело и ссылка. Тогда файл, страница, лента и письмо — все представления. Этот структурный момент — единственное, что стоит сделать правильно перед выбором инструмента, потому что это то, что нельзя дёшево добавить позже. Ничто из этого не работает, если запись на самом деле не создаётся для каждого изменения, которому она нужна; <a href="https://changeloop.dev/blog/ru/changelog-ci-enforcement/">обязательная запись в changelog в CI</a> разбирает, как заставить pipeline отклонять merge без записи, вместо того чтобы оставлять этот шаг на память.</p> <p>Мы строим <a href="https://changeloop.dev/">changeloop</a>, где changelog сначала лента, а потом уже страница, так что читайте это как заинтересованность, а не беспристрастную рекомендацию; <a href="https://changeloop.dev/pricing">цены</a> — это один бесплатный репозиторий без карты, достаточный, чтобы увидеть форму. <a href="https://changeloop.dev/changelog-tools">Инструменты для changelog</a> — наш обзор того, что ещё существует, включая продукты, с которыми мы конкурируем, а <a href="https://changeloop.dev/changelog-generator">генератор changelog</a> выполняет шаги сбора и классификации в браузере, если вы хотите увидеть вывод перед тем, как обязаться на pipeline.</p> <h2>Тест</h2> <p>Посчитайте минуты между объединённым изменением и видимостью этого изменения для клиентки, которая не читает ваш репо. Если большинство этих минут — это кто-то, копирующий текст между инструментами, автоматизация, которая вам нужна, находится в публикации, а не в написании.</p> <h2>FAQ</h2> <p><strong>Может ли ИИ написать changelog?</strong> Он может составить черновик. Модель, которой дан объединённый pull request, чаще всего производит пригодный первый черновик заголовка и тела, что и есть сбор и классификация, сделанные лучше. Отбор — стоит ли вообще что-то говорить читателю, и финальная формулировка всё ещё нуждаются в человеке, знающем аудиторию, и pipeline, публикующий черновики без этих ворот, автоматизировал не тот шаг.</p> <p><strong>В чём разница между генератором changelog и автоматизацией changelog?</strong> Генератор превращает коммиты в отформатированный список один раз, по запросу. Автоматизация работает при каждом merge, поддерживает неопубликованную корзину, обусловливает релиз человеческим ревью, и публикует на каждую поверхность из одного источника. Генератор — это первый шаг pipeline, выполняемый вручную.</p> <p><strong>Следует ли автоматизировать changelog из коммитов или из pull request?</strong> Из pull request, где единицей изменения является PR: заголовок и описание пишутся один раз, для всего изменения, и PR связывает issue, который закрывает. Вывод на основе коммитов работает, когда коммит является единицей и следует конвенции.</p> <p><strong>Как предотвратить публикацию внутренних изменений автоматизацией?</strong> Классифицируйте <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> и обновления зависимостей как внутренние по умолчанию, и сделайте продвижение к публичности осознанным актом. Обратный по умолчанию, публичное если только кто-то не скроет, — это как <code>bump deps</code> достигает клиентов.</p> </article> <article> <h1>Changelog vs release notes: в чём разница?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Changelog — это непрерывный, накопительный реестр всего, что изменилось, написанный для того, кто что-то ищет. Release notes — это отобранное сообщение об одном релизе, написанное для того, кто решает, важно ли ему это. Разница в аудитории, а не в форматировании, и большинству команд нужны оба: один как справочник, другой как анонс, выведенные из одних и тех же записей.</p> <p>Большинство команд заканчивают с одним из них случайно, а с другим — по запросу. Вы начинаете с changelog, потому что разработчица хочет реестр того, что было выпущено. Месяцами позже кто-то из поддержки спрашивает, почему клиенты не знали о функции, которая живёт с апреля, и теперь вам нужны release notes.</p> <h2>Changelog vs release notes, рядом друг с другом</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Читатель</td> <td>Тот, кто что-то ищет</td> <td>Тот, кто решает, важно ли это ему</td> </tr> <tr> <td>Охват</td> <td>Всё, что изменилось</td> <td>То, что стоит сказать об этом релизе</td> </tr> <tr> <td>Периодичность</td> <td>Непрерывная, при каждом merge или релизе</td> <td>При релизе, и только тех, что стоит анонсировать</td> </tr> <tr> <td>Тон</td> <td>Краткий, фактический, часто повелительный</td> <td>Объясняющий, иногда убеждающий</td> </tr> <tr> <td>Срок жизни</td> <td>Постоянный, читается и годы спустя</td> <td>Читается первую неделю, потом архивируется</td> </tr> <tr> <td>Живёт в</td> <td>Репо, сайте документации, странице <code>/changelog</code></td> <td>Письме, in-app, посте блога, странице релиза</td> </tr> <tr> <td>Терпит неудачу из-за</td> <td>Неполноты</td> <td>Скучности, или слишком позднего появления</td> </tr> </tbody></table> <h2>Что такое changelog?</h2> <p>Changelog — это хронологический, почти полный реестр того, что изменилось, самое новое первым, с каждой записью, типизированной (added, changed, deprecated, removed, fixed, security) и датированной. Его читатель уже решил, что ему важно. Он что-то ищет: когда изменилось поведение, исправлен ли баг, какая версия ввела флаг. Полнота — вся ценность, поэтому конвенция <a href="https://changeloop.dev/blog/ru/keep-a-changelog-implemented/">Keep a Changelog</a> тратит большую часть своей единственной страницы на структуру и почти ничего на прозу.</p> <h2>Что такое release notes?</h2> <p>Release notes — это избирательное сообщение, написанное прозой, об одном релизе. Его читатель ещё ничего не решил. Он решает, важен ли ему этот релиз, и нужно ли ему что-то с этим делать. Отбор — вся ценность: release note, перечисляющая всё, — это changelog с абзацами, и она подводит читателя так же, как changelog, пропускающий что-то, подводит своего. <a href="https://changeloop.dev/blog/ru/how-to-write-release-notes/">Как писать release notes</a> о том, как отбирать и формулировать.</p> <h2>Нужен ли вам и changelog, и release notes?</h2> <p>Вам нужны оба, как только ваши две аудитории начинают хотеть разного; до этого один артефакт, выполняющий обе работы, — правильно. Маленькие команды публикуют одну страницу <code>/changelog</code> с коротким абзацем в начале каждой записи, и какое-то время это одинаково хорошо служит и разработчице, ищущей исправление, и клиентке, просматривающей новости. Разделение слишком рано даёт вам два дела для поддержки, и одно из них сгниёт.</p> <p>Разделение оказывается стоящим, когда начинает происходить это:</p> <ul> <li>Ваши записи changelog обросли объясняющими абзацами, которые разработчики пропускают.</li> <li>Или наоборот: ваши анонсы релизов начали перечислять обновления зависимостей.</li> <li>Поддержка копирует записи в письма и переписывает их по пути.</li> <li>Кто-то просит «только breaking change», а вы не можете их отфильтровать.</li> </ul> <p>Последнее — настоящий признак. Если никто не может ответить «что изменилось, что касается меня», не прочитав всё, у вас один артефакт, плохо выполняющий две работы.</p> <h2>Один источник, два представления</h2> <p>Ошибка — относиться к ним как к двум документам. Это два представления одного и того же набора изменений.</p> <p>Пишите changelog по ходу дела, одна запись на значимое изменение, каждая помечена тем, что она есть: fixed, added, changed, removed, deprecated, security. Держите записи достаточно короткими, чтобы написание одной не было решением. Затем, в момент релиза, release notes — это отбор и переписывание: возьмите записи, важные для человека, сгруппируйте их по тому, что они позволяют кому-то сделать, и поставьте причину сверху.</p> <p>У этого есть практическое следствие. Если changelog — это источник, он должен быть структурированными данными, а не страницей, поддерживаемой вручную. Записи нужен тип, дата, версия и способ сказать, для кого она. Как только это есть, публичная страница, in-app виджет и лента RSS или JSON — это три отображения одной вещи, и никто ничего не переписывает по пути к клиенту. Письмо с release notes может цитировать ту же запись, из любого инструмента, которым вы отправляете почту. <a href="https://changeloop.dev/blog/ru/changelog-automation/">Автоматизация changelog</a> — о том, какой из этих шагов должен принадлежать машине. Это весь аргумент в пользу того, чтобы относиться к changelog как к ленте, а не как к странице. Это также, с полной прозрачностью, то, что мы строим, так что читайте это как интерес, а не беспристрастный опрос.</p> <h2>Если у вас есть время только на одно</h2> <p>Пишите changelog. Он дешевле на запись, полезен в день, когда вы его пишете, и release notes можно потом вывести из него. Обратное неверно: вы не можете восстановить год изменений из двенадцати писем с анонсами, а люди попросят вас об этом.</p> <p>Держите его в фиксированном формате, чтобы вывод оставался возможным. Наша страница <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> собирает записи от команд, делающих это хорошо, а <a href="https://changeloop.dev/release-notes-template">шаблон release notes</a> — это форма, которую мы используем, превращая набор записей во что-то, что стоит отправить.</p> <h2>Заметка об именовании</h2> <p>Ничто из этого не стандартизировано, и вы найдёте «release notes», используемое для непрерывного списка, и «changelog», используемый для квартального анонса. Спорить о словах не стоит. Решите, какую из двух работ выполняет каждый из ваших артефактов, называйте это так, как уже называет ваша команда, и убедитесь, что ни один из них молча не делает оба.</p> <p>На какой поверхности окажется результат — отдельное решение, разобранное в <a href="https://changeloop.dev/blog/ru/changelog-page/">как сделать страницу changelog</a>.</p> <h2>FAQ</h2> <p><strong>Одно ли и то же changelog и release notes?</strong> Нет. Changelog — это полный реестр, читаемый теми, кто что-то ищет; release notes — это отобранный анонс, читаемый теми, кто решает, важно ли это им. Одно и то же изменение появляется в обоих, сформулированное по-разному для каждого читателя.</p> <p><strong>Можно ли сгенерировать release notes из changelog?</strong> Да, и это правильное направление. Отберите записи, важные для человека, сгруппируйте по результату, перепишите заголовок. Обратное, восстановление changelog из анонсов, теряет всё, что анонсы опустили.</p> <p><strong>Где должен жить changelog?</strong> Где-то постоянном и ссылаемом, куда читатель может добраться без репозитория: странице <code>/changelog</code>, сайте документации, или ленте, отображаемой в нескольких местах. Один <code>CHANGELOG.md</code> достигает контрибьюторов, но не клиентов.</p> <p><strong>Должен ли changelog включать внутренние изменения?</strong> Да, внизу, по одной строке каждое. Changelog — это полный реестр. Release notes тоже могут их содержать, в короткой последней секции, если изменения, которые читатель заметит, идут первыми.</p> </article> <article> <h1>От conventional commits к changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Conventional commits бесплатно дают changelog три вещи: тип каждого изменения, часть системы, которую оно затронуло, и ломает ли оно что-то. Больше они не дают ничего. Формулировка, группировка и отбор, которые и есть changelog, остаются полностью открытыми, и pipeline, притворяющийся иначе, доставляет отформатированный git log.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Три коммита в формате <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. Из них машина может сказать вам, что один — это функция, один — исправление, один — уборка, и какую часть системы затронул каждый. Это по-настоящему полезно, и это всё обещание конвенции: история коммитов, которую может прочитать что-то помимо человека. Ошибка — думать, что это даёт вам changelog. Это даёт вам сырьё.</p> <h2>Что определяет конвенция?</h2> <p>Тип, необязательный scope, и описание: <code>type(scope): description</code>. Типы условно <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Две вещи помечают breaking change: <code>!</code> перед двоеточием, или футер <code>BREAKING CHANGE:</code>. Инструменты ориентируются на <code>feat</code> и <code>fix</code> для minor и patch версий, и на маркер breaking для major.</p> <table> <thead> <tr> <th>Коммит даёт вам</th> <th>Changelog нуждается в</th> <th>Кто заполняет разрыв</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / внутреннее</td> <td>Отображение, автоматическое</td> </tr> <tr> <td><code>(scope)</code></td> <td>Группировку, которую узнаёт читатель</td> <td>Человек, раз на scope</td> </tr> <tr> <td><code>!</code> или <code>BREAKING CHANGE:</code></td> <td>Кто ломается, до когда, и что делать</td> <td>Человек, каждый раз</td> </tr> <tr> <td>Описание, написанное для ревьюера</td> <td>Результат, написанный для клиентки</td> <td>Человек, каждая запись</td> </tr> <tr> <td>Один коммит</td> <td>Одно изменение, которое может быть многими коммитами</td> <td>Правила squash, или человек</td> </tr> </tbody></table> <p>Маркер сообщает это инструменту; он не сообщает это вызывающей стороне, что является темой <a href="https://changeloop.dev/blog/ru/api-deprecation/">как деприкейтить API</a> и <a href="https://changeloop.dev/blog/ru/breaking-changes/">что такое breaking change</a>. Это маленькая спецификация, и её стоит соблюдать, даже если вы никогда ничего из неё не генерируете, потому что она заставляет принять одно решение на коммит: видят ли пользователи это изменение, или нет.</p> <h2>Где останавливаются conventional commits?</h2> <p>Они останавливаются на предложении. Всё, что захватывает конвенция, — это метаданные об изменении; само изменение всё ещё описано словарём ревьюера.</p> <p><strong>Сообщения коммитов написаны для ревьюеров.</strong> <code>fix(auth): reject expired refresh tokens</code> корректно и ничего не говорит клиентке. Читательница changelog хочет «вас выйдут из системы, когда сессия действительно истечёт, вместо периодических 401».</p> <p><strong>Scope внутренние.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> — это названия модулей. Они стабильны, что делает их хорошими для группировки, и бессмысленны для тех, кто вне кодовой базы.</p> <p><strong>Одно изменение часто — это много коммитов.</strong> Функция, объединённая через одиннадцать коммитов, создаёт одиннадцать записей, десять из которых шум, а сжатие их для сокрытия этого теряет историю ревью.</p> <p><strong><code>chore</code> — это мусорка, а не категория.</strong> Обновления зависимостей, изменения CI и переименования попадают туда все, и некоторые важны для пользователей, пока большинство нет.</p> <p>Итак: конвенция бесплатно даёт вам тип, scope и статус breaking, и оставляет формулировку, группировку и отбор полностью открытыми. Эти три — и есть changelog. <a href="https://changeloop.dev/blog/ru/changelog-entry-ownership/">Кто на самом деле отвечает за запись в changelog</a> разбирает, кто должен заниматься этой формулировкой, группировкой и отбором, поскольку сама конвенция не имеет на этот счёт мнения.</p> <h2>Как генерируется changelog из conventional commits?</h2> <p>В двух слоях, и второй должен быть обязательным.</p> <p><strong>Слой первый, автоматический.</strong> При merge выводите черновик записи из коммита: тип отображён на тип changelog (<code>feat</code> на Added, <code>fix</code> на Fixed, маркер breaking на Changed плюс флаг), scope сохранён как метаданные, а не текст, ссылка на PR. Поместите его в раздел Unreleased, который требует <a href="https://changeloop.dev/blog/ru/keep-a-changelog-implemented/">Keep a Changelog</a>.</p> <p><strong>Слой второй, человеческий, и необходимый.</strong> Прежде чем выйдет релиз, каждая черновая запись либо получает однострочное переписывание словарём пользователя, либо помечается как внутренняя и убирается из публичного вида. Это шаг, который люди пытаются пропустить, и его пропуск создаёт changelog, читающиеся как диф.</p> <p>Важная деталь дизайна в том, что второй слой не опционален в pipeline. Если релиз можно выпустить с неотредактированными черновиками, это случится, в неделю, когда все заняты. Какие шаги принадлежат машине, а какие человеку — вся суть <a href="https://changeloop.dev/blog/ru/changelog-automation/">автоматизации changelog</a>.</p> <p>Вырезка релиза — это и момент, когда git-тег, релиз и эта запись changelog либо совпадают, либо начинают расходиться; <a href="https://changeloop.dev/blog/ru/git-tags-releases-changelog/">git-теги, релизы и ваш changelog</a> разбирает, как держать эти три вещи синхронизированными.</p> <h2>Три ловушки</h2> <p><strong>Squash merge съедает футеры.</strong> Если ваша платформа сжимает с заголовком PR как сообщением, футер <code>BREAKING CHANGE:</code> коммита внутри этой ветки исчезает, и ваши инструменты молча перестают видеть breaking change. Проверьте, что на самом деле сохраняет ваш шаблон squash.</p> <p><strong>Коммиты revert создают призрачные записи.</strong> <code>fix</code>, который откатывается на следующий день, создаёт запись для того, что никогда не было выпущено, если только вывод не примиряет revert-ы. Большинство инструментов этого не делают.</p> <p><strong>Повышение версии и changelog рассинхронизируются.</strong> Если версия вычисляется из коммитов, а changelog пишется вручную после, они расходятся примерно за два релиза. Вычисляйте оба за один проход или примите, что один из них неверен.</p> <h2>Если вам нужна механическая часть без pipeline</h2> <p>Наш <a href="https://changeloop.dev/changelog-generator">генератор changelog</a> выполняет шаг вывода в браузере: вставьте коммиты, получите сгруппированные, типизированные записи. Он намеренно детерминирован и полностью клиентский, поэтому вставляемые вами коммиты никогда не покидают вашу машину, что важно, когда сообщения из приватного репозитория. Он честно выполняет половину сбора и не пытается сделать второй слой, потому что второй слой — это суждение, а инструмент, притворяющийся им, создаёт именно тот changelog, против которого выступает эта статья.</p> <p>Для версии pipeline, <a href="https://changeloop.dev/changelog-tools">инструменты для changelog</a> охватывает, что существует.</p> <h2>Резюме</h2> <p>Conventional commits надёжно и дёшево отвечают на «какого рода это изменение». Они не отвечают на «что мы должны сказать людям», и никакое количество инструментов поверх сообщения коммита этого не сделает, потому что информация никогда не была в сообщении коммита. Бюджетируйте на переписывание.</p> <h2>FAQ</h2> <p><strong>Генерируют ли conventional commits changelog автоматически?</strong> Они автоматически генерируют черновик: типизированные, со scope, связанные записи. Формулировка для клиентки, группировка и решение о том, что опустить, всё ещё нуждаются в человеке, и pipeline, пропускающий этот шаг, публикует сообщения коммитов.</p> <p><strong>Какие типы conventional commit появляются в changelog?</strong> <code>feat</code> и <code>fix</code> всегда, как Added и Fixed. <code>perf</code> обычно, как Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> и <code>ci</code> по умолчанию внутренние и появляются только если человек продвигает один из них.</p> <p><strong>Как conventional commits помечают breaking change?</strong> <code>!</code> после типа или scope (<code>feat(api)!: ...</code>), или футер <code>BREAKING CHANGE:</code> в теле коммита. Оба теряются, если squash merge сохраняет только заголовок PR.</p> <p><strong>Нужны ли conventional commits для автоматизации changelog?</strong> Нет. Метки PR, шаблоны PR и ссылки на issue несут те же метаданные для команд, которые объединяют через pull request. Conventional commits — самый дешёвый вариант, когда единицей изменения является коммит.</p> </article> <article> <h1>Как писать release notes, которые реально читают</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Чтобы писать release notes, которые читают, отвечайте на один вопрос в каждой записи: что читатель теперь может сделать, чего не мог раньше, и что ему нужно для этого сделать. Ставьте всё с дедлайном первым, называйте, кого это касается, пишите «действий не требуется», когда это правда, и пропускайте релизы, которым нечего сказать. Всё остальное на этой странице — применение этого правила.</p> <blockquote> <p>Исправления багов и улучшения производительности.</p> </blockquote> <p>Каждый продукт когда-нибудь публиковал это. Причина редко в лени: так получается, когда release notes пишутся изнутри, кем-то, кто провёл две недели в диффе и уже не видит, какие части заинтересуют постороннего. Лучший тон это не исправит; ответ на вопрос — да.</p> <h2>Что должны включать release notes?</h2> <p>Release notes должны включать для каждого изменения, заслуживающего упоминания: что читатель теперь может сделать, кого это касается, что ему нужно сделать (включая «ничего»), и когда вступает в силу то, у чего есть дедлайн. Они не должны включать номера внутренних тикетов, названия компонентов, которые использует только команда, или номер версии как единственный заголовок.</p> <table> <thead> <tr> <th>Включить</th> <th>Опустить</th> </tr> </thead> <tbody><tr> <td>Результат, словами читателя</td> <td>Реализацию, словами команды</td> </tr> <tr> <td>Кого касается, по плану, роли или версии API</td> <td>«Некоторые пользователи»</td> </tr> <tr> <td>Требуемое действие, или «действий не требуется»</td> <td>Тишину, которую читатель заполняет худшим сценарием</td> </tr> <tr> <td>Дату для всего, у чего есть дедлайн</td> <td>Номер версии вместо даты</td> </tr> <tr> <td>Ссылку на документацию с объяснением</td> <td>Ссылку на pull request</td> </tr> <tr> <td>Баги, о которых сообщили люди, и поднятый лимит</td> <td>Внутренние id тикетов</td> </tr> <tr> <td>Скучный раздел, по одной строке, внизу</td> <td>Скучный раздел, смешанный с новостями</td> </tr> </tbody></table> <p>Разделение между release note и <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">записью changelog</a> — это то, что делает возможным этот список: changelog хранит всё, поэтому заметки могут что-то опускать. Размеченные примеры каждого вида записи собраны в статье <a href="https://changeloop.dev/blog/ru/release-notes-examples/">примеры release notes</a>.</p> <h2>Вопрос, на который отвечает каждая запись</h2> <p><strong>Что читатель теперь может сделать, чего не мог раньше, и что ему нужно для этого сделать?</strong></p> <p>Если запись не может на это ответить, она принадлежит changelog, а не release notes. Обе половины важны. Первая половина — это ценность. Вторая половина — та, которую забывают команды, и именно она порождает тикеты в поддержку, когда её нет.</p> <p>Два примера второй половины, выполняющей реальную работу:</p> <ul> <li>«Существующие вебхуки продолжат работать до 1 ноября. После этой даты неподписанные payload будут отклоняться.»</li> <li>«Действий не требуется. Существующие экспорты автоматически перекодируются при следующем открытии.»</li> </ul> <p>Второй пример явно говорит «действий не требуется». Эту фразу стоит писать каждый раз, потому что читатель, который её не находит, предполагает худшее.</p> <h2>Как следует упорядочивать release notes?</h2> <p>Упорядочивайте их по последствиям для читателя, никогда — по части системы, которая изменилась. Группировка по API, панели, мобильному приложению и инфраструктуре — это ваша организационная схема, а не проблема читателя.</p> <ol> <li><strong>Breaking change и всё, у чего есть дедлайн.</strong> Всегда первым, даже если это мелочь. Если читатель перестаёт читать после одной строки, это должна быть та строка, которую он должен был прочитать. Если дедлайн — это sunset, запись должна звучать как <a href="https://changeloop.dev/blog/ru/api-deprecation/">уведомление об устаревании</a>.</li> <li><strong>Что нового и чего они хотели.</strong> По одному на абзац, с результатом в первом предложении.</li> <li><strong>Что улучшилось.</strong> Баги, о которых сообщили, лимиты, которые подняли, что было медленным.</li> <li><strong>Всё остальное, списком.</strong> Обновления зависимостей, внутренние рефакторинги, мелкие тексты. По одной строке каждое. Никто не читает этот раздел, и всё же он должен быть, потому что тот, кто его ищет, действительно в нём нуждается.</li> </ol> <h2>Переписывание</h2> <p>До:</p> <blockquote> <p><strong>v4.2.0</strong> Исправлена проблема, из-за которой endpoint <code>POST /exports</code> периодически возвращал 500 под нагрузкой. Рефакторинг воркера экспорта. Обновлён <code>node-pg</code> до 8.11. Улучшена обработка ошибок в сериализаторе CSV.</p> </blockquote> <p>После:</p> <blockquote> <p><strong>Экспорты больше не падают на больших аккаунтах.</strong> Аккаунты с более чем примерно 50 000 строк могли получить 500 при запуске экспорта, чаще в конце месяца. Это исправлено, и теперь экспорты любого размера сами повторяют попытку вместо того, чтобы падать. Действий не требуется, и любой экспорт, упавший на прошлой неделе, можно просто запустить заново.</p> <p>Также в 4.2.0: <code>node-pg</code> 8.11, более понятные ошибки в сериализаторе CSV.</p> </blockquote> <p>Тот же релиз. Второй вариант называет затронутый аккаунт, момент, когда было хуже всего, что изменилось, и что делать. Обновление зависимости не исчезло, оно просто перестало быть заголовком. Статья <a href="https://changeloop.dev/blog/ru/release-notes-best-practices/">лучшие практики release notes</a> содержит остальные правила, которым следует это переписывание, каждое с ценой пропуска.</p> <h2>Что стоит удалить</h2> <ul> <li><strong>«Мы рады объявить.»</strong> Читатель ещё не рад. Заслужите это в следующем предложении.</li> <li><strong>Внутренние номера тикетов.</strong> <code>PROJ-4471</code> ничего не значит вне вашего трекера. Если записи нужна ссылка, дайте ссылку на страницу документации.</li> <li><strong>Названия компонентов, которые использует только ваша команда.</strong> Если вы переименовали «пайплайн приёма данных», скажите «импорты».</li> <li><strong>Номер версии как единственный заголовок.</strong> <code>v4.2.0</code> — это ярлык для архива, а не резюме.</li> <li><strong>Скриншоты страницы настроек, которую никто не посещал.</strong> Покажите то, что изменилось, в действии.</li> </ul> <h2>Как часто следует публиковать release notes?</h2> <p>Публикуйте, когда что-то произошло, а не по расписанию. Заметки, приходящие с каждым релизом, приучают всех их игнорировать. Заметки, приходящие, когда что-то произошло, открывают. Это нормально, и обычно правильно, выпустить релиз вообще без заметок и перенести его записи в следующий набор, у которого есть заголовок, достойный прочтения.</p> <p>Changelog продолжает фиксировать всё. Таково разделение труда: changelog полон, заметки избирательны. Если вы поддерживаете changelog структурированным по ходу дела, написание заметок становится отбором и переписыванием, а не археологией.</p> <p><a href="https://changeloop.dev/release-notes-template">Шаблон release notes</a> — это форма, которую мы используем для этапа отбора, а <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> собирает записи от команд, чей changelog достаточно хорош, чтобы выводить из него заметки.</p> <p>Всё это предполагает страницу, которую вы полностью контролируете, без ограничения длины и с работающими ссылками. <a href="https://changeloop.dev/blog/ru/mobile-app-release-notes/">Release notes для мобильных приложений</a> разбирает, что меняется, когда поверхность — это листинг App Store или Play Store. <a href="https://changeloop.dev/blog/ru/emergency-release-notes/">Экстренные release notes</a> разбирают другое исключение: что меняется, когда не остаётся времени вообще следовать обычному процессу написания.</p> <h2>Один тест перед публикацией</h2> <p>Прочитайте заметки как человек, который был в отпуске две недели и у которого есть 40 секунд. Если за это время он не может понять, требуется ли от него что-то, заметки не готовы, какими бы точными они ни были.</p> <h2>FAQ</h2> <p><strong>Насколько длинными должны быть release notes?</strong> Такими длинными, каких требуют значимые изменения, и ни строкой больше. Релиз с одним breaking change и двумя улучшениями — это три абзаца. Наполнение тихого релиза, чтобы он казался значительным — это как читатели учатся пропускать заметки.</p> <p><strong>Кто должен писать release notes?</strong> Человек, понимающий изменение, отредактированный кем-то, кто его не понимает. Инженерка знает, что изменилось; редакторка знает, что посторонний поймёт неправильно. Написание записи в момент merge, пока инженерка ещё помнит, — это практика, которая делает это дешёвым.</p> <p><strong>Должны ли release notes включать исправления багов?</strong> Да, те, о которых кто-то сообщил или с которыми столкнулся. Укажите симптом, который видел читатель, а не причину. «Экспорты более 50 000 строк падали» — это исправление, которое читатель узнаёт; «исправлена гонка в воркере экспорта» — это сообщение коммита.</p> <p><strong>В чём разница между release notes и changelog?</strong> Changelog — это полный, непрерывный реестр; release notes — это отобранное сообщение об одном релизе, написанное для людей, которые ещё не решили, интересует ли их это. Более длинный ответ — в <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">changelog vs release notes</a>.</p> </article> <article> <h1>Keep a Changelog, реально внедрённый</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog — это конвенция на одну страницу для <code>CHANGELOG.md</code>: самая новая версия первая, один раздел на версию с номером и датой ISO, записи, сгруппированные под шестью типами (Added, Changed, Deprecated, Removed, Fixed, Security), и раздел Unreleased сверху для записей между релизами. Большинство команд, ссылающихся на неё, внедряют около двух третей, а треть, которую они оставляют, — это та треть, что защищает их пользователей.</p> <p>Оливье Лакан опубликовал <a href="https://keepachangelog.com/">Keep a Changelog</a> в 2014 году с фразой, которая состарилась лучше большинства прозы о софте: <em>don't let your friends dump git logs into changelogs</em>. Десять лет спустя это ближайшее к стандарту, что есть в этом уголке софта. Стоит прочитать источник, а не пересказ; этот текст о частях, которые оставляют в стороне.</p> <h2>Что требует Keep a Changelog?</h2> <p><code>CHANGELOG.md</code> в корне репо, самая новая версия первая, с одним разделом на версию. Каждая версия несёт номер и дату ISO, и группирует свои записи под шестью типами:</p> <table> <thead> <tr> <th>Тип</th> <th>Для</th> <th>Цена его оставления в стороне</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Новые функции</td> <td>Ничего; никто это не оставляет</td> </tr> <tr> <td>Changed</td> <td>Изменения в существующем поведении</td> <td>Читатели узнают об изменении поведения из ошибки</td> </tr> <tr> <td>Deprecated</td> <td>Функции на пути к удалению</td> <td>Удаление становится инцидентом вместо запланированного события</td> </tr> <tr> <td>Removed</td> <td>Функции, удалённые в этом релизе</td> <td>Никто не отличает удаление от бага</td> </tr> <tr> <td>Fixed</td> <td>Исправления багов</td> <td>Ничего; никто это тоже не оставляет</td> </tr> <tr> <td>Security</td> <td>Уязвимости</td> <td>Единственная читательница, искавшая это, не находит</td> </tr> </tbody></table> <p>Плюс раздел <code>Unreleased</code> сверху, чтобы было место для записи в момент её merge, и чтобы каждый мог увидеть, что грядёт.</p> <p>Это почти всё. Остальное — обоснование: записи для людей, одна запись на изменение, и файл — документ, а не лог.</p> <h2>Какие части Keep a Changelog оставляют в стороне?</h2> <p>Раздел Unreleased, затем четыре из шести типов, Security в их числе, в этом порядке.</p> <p><strong><code>Unreleased</code> исчезает первым.</strong> Это раздел без дедлайна, поэтому его поддержка прекращается первой, и как только он исчезает, записи пишутся в момент релиза из истории коммитов. Это именно тот сброс git-лога, о котором спецификация предупреждает с самого начала, достигнутый постепенно. <a href="https://changeloop.dev/blog/ru/changelog-automation/">Автоматизация changelog</a> в основном о том, как поддерживать этот раздел живым без того, чтобы кто-то должен был помнить об этом.</p> <p><strong>Шесть типов схлопываются в два.</strong> Большинство реальных changelog заканчиваются с Added и Fixed, потому что Changed и Deprecated требуют суждения о том, на что кто-то полагался. Это суждение — ценная часть. Deprecated в частности — единственный тип, являющийся обещанием о будущем, и его пропуск — это как удаление превращается в инцидент; механика соблюдения этого обещания — в <a href="https://changeloop.dev/blog/ru/api-deprecation/">как деприкейтить API</a>.</p> <p><strong>Security перестаёт быть отдельным.</strong> Исправление безопасности, помещённое под Fixed, невидимо для единственной читательницы, искавшей его. Держите его отдельно, даже когда исправление тривиально, и особенно когда вы предпочли бы не привлекать к нему внимание.</p> <h2>На что не отвечает спецификация?</h2> <p>Это формат файла. Он ничего не говорит о вопросах, с которыми вы сталкиваетесь сразу после её принятия:</p> <ul> <li><strong>Как кто-то узнаёт?</strong> Файл в репо достигает контрибьюторов. Он не достигает клиентку, которая никогда не открывала GitHub.</li> <li><strong>А продукты без версий?</strong> Непрерывно развёртываемый сервис не имеет v4.2.0, по которой можно группировать. Большинство команд заменяют это датами, что работает, и спецификация это ни благословляет, ни запрещает.</li> <li><strong>Кто пишет запись?</strong> Спецификация предполагает, что это делает человек. Она не говорит когда.</li> <li><strong>А множество аудиторий?</strong> Один файл обслуживает разработчиков. Он не обслуживает тем же содержимым нетехническую администраторку, и ручное переформатирование для неё — то, откуда начинается дублирование. <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">Changelog vs release notes</a> — это разделение, которое спецификация оставляет вам сделать самостоятельно.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, более строгий форк идеи, ужесточает часть этого: запрещает определённые формулировки записей, требует ссылку на изменение, и имеет чёткое мнение о том, кто читатель. Стоит прочитать, если свободные части Keep a Changelog — это то, о чём ваша команда постоянно спорит.</p> <h2>Можно ли автоматизировать Keep a Changelog без сброса git-логов?</h2> <p>Да: выводите черновик из структурированных коммитов, помещайте его в Unreleased с предзаполненным типом, и требуйте, чтобы человек редактировал формулировку перед выпуском релиза. Предупреждение спецификации о результате, а не об инструменте. Выведение черновика из коммитов — это нормально. Публикация этого черновика без редактирования — то, против чего она возражает.</p> <p>Машина занимается сбором и форматированием, в чём она хороша. Человек занимается отбором и формулировкой, в чём она не хороша. <a href="https://changeloop.dev/blog/ru/conventional-commits-changelog/">Conventional commits</a> описывают то разделение на два уровня, на которое это опирается, и то, какие типы коммитов соответствуют каким из шести категорий выше. Наш обзор <a href="https://changeloop.dev/changelog-tools">инструменты для changelog</a> охватывает, что существует для половины сбора.</p> <h2>Где Keep a Changelog перестаёт быть достаточным?</h2> <p>Он останавливается на распространении. Keep a Changelog — хороший ответ на «как должен выглядеть этот файл». Это не ответ на «как наши пользователи узнают, что изменилось», потому что файл Markdown в репо — это стратегия распространения, работающая только если ваши пользователи — контрибьюторы.</p> <p>Это препятствие, с которым большинство команд сталкивается вторым: файл в порядке, и никто вне команды его не читает. Решение этого означает, что записи должны стать данными, которые можно отобразить в другом месте, что является другой проблемой, чем форматирование файла, и причиной, по которой <a href="https://changeloop.dev/changelog-examples">примеры changelog</a> собирает публичные страницы changelog, а не файлы репозитория. Как превратить эти записи в то, к чему люди возвращаются, разбирает <a href="https://changeloop.dev/blog/ru/changelog-page/">как сделать страницу changelog</a>.</p> <p>Всё равно примите спецификацию. Она стоит вечера, делает вторую проблему решаемой, и всё ещё лучшая страница, когда-либо написанная об этом.</p> <h2>FAQ</h2> <p><strong>Является ли Keep a Changelog стандартом?</strong> Это широко принятая конвенция, а не спецификация органа стандартизации. Инструменты (скрипты релиза, линтеры, парсеры) достаточно часто предполагают её форму, чтобы её следование покупало совместимость.</p> <p><strong>Что попадает в раздел Unreleased?</strong> Каждая запись для изменения, которое было объединено, но ещё не выпущено в пронумерованном релизе. Когда релиз выпускается, раздел переименовывается в версию и дату, а новый, пустой раздел Unreleased идёт над ним.</p> <p><strong>Должен ли changelog использовать семантическое версионирование?</strong> Keep a Changelog рекомендует это и не требует. Библиотеки и API от этого выигрывают; непрерывно развёртываемый сервис обычно заменяет это датами, что формат допускает.</p> <p><strong>Должны ли исправления безопасности быть в changelog до того, как они публичны?</strong> Добавьте запись, когда исправление выпущено, с достаточной детализацией, чтобы оператор мог действовать, и не более. Отложить запись до даты скоординированного раскрытия нормально; опустить её — нет.</p> </article> <article> <h1>Лучшие практики release notes, которые важны</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Важные лучшие практики release notes — это те, к которым прилагается последствие: пишите запись в момент merge, называйте, кого это касается, указывайте требуемое действие даже когда его нет, датируйте breaking change, ведите одну постоянную запись на изменение, группируйте по результату и сохраняйте скучный раздел. Каждая меняет поведение читателя. Большинство остальных советов на эту тему меняют то, как заметки выглядят.</p> <p>Поищите лучшие практики release notes, и получите советы по стилю: будьте ясны, будьте кратки, используйте простой язык, добавляйте скриншоты. Ничто из этого не неверно, и ничто из этого ничего не меняет, потому что ни одна команда никогда не садилась с намерением быть неясной. Практики ниже идут вместе с ценой их пропуска, потому что практика без прикреплённого режима отказа — это просто предпочтение.</p> <table> <thead> <tr> <th>Практика</th> <th>Цена пропуска</th> </tr> </thead> <tbody><tr> <td>Писать запись при merge, а не при релизе</td> <td>Восстановленные позже записи говорят «различные улучшения»</td> </tr> <tr> <td>Называть, кого касается</td> <td>Каждый читатель решает, что это не про него</td> </tr> <tr> <td>Указывать требуемое действие, включая «никакого»</td> <td>Сорок одинаковых тикетов в поддержку, и читатели, предполагающие худшее</td> </tr> <tr> <td>Датировать breaking change, а не версионировать</td> <td>Дедлайн обнаруживают после того, как он прошёл</td> </tr> <tr> <td>Одна постоянная, ссылаемая запись на изменение</td> <td>Никто не может ответить «когда это изменилось»</td> </tr> <tr> <td>Группировать по результату, а не по системе</td> <td>Читателям нужна ваша архитектура, чтобы найти свой раздел</td> </tr> <tr> <td>Сохранять скучный раздел</td> <td>Служба безопасности, проверяющий соответствие и отлаживающий несовпадение версий теряют свой источник</td> </tr> </tbody></table> <h2>Какие лучшие практики для release notes?</h2> <p><strong>Пишите запись, когда делаете merge, а не когда выпускаете релиз.</strong> Цена пропуска: человек, восстанавливающий релиз из истории коммитов, — не тот, кто внёс изменение, и он угадает намерение. Записи, написанные две недели спустя, — это те, что говорят «различные улучшения».</p> <p><strong>Называйте, кого касается, по имени.</strong> «Команды на плане Business», «любой, кто использует API экспорта v1», «self-hosted установки на Postgres 14». Цена пропуска: каждому читателю приходится выяснять, касается ли это его, и большинство решит, что нет.</p> <p><strong>Указывайте требуемое действие, включая случаи, когда его нет.</strong> Цена пропуска: поддержка отвечает на один и тот же вопрос сорок раз, а читатели, не спросившие, предполагают, что что-то требуется, и откладывают это.</p> <p><strong>Давайте breaking change дату, а не номер релиза.</strong> «Удалено в v5» ничего не значит для того, кто не следит за вашими релизами. «Перестаёт работать 1 ноября» значит одно и то же для всех. Цена пропуска: дедлайн обнаруживают после того, как он прошёл. Что считается таковым, и чек-лист для выпуска, — в <a href="https://changeloop.dev/blog/ru/breaking-changes/">что такое breaking change</a>.</p> <p><strong>Ведите одну постоянную, ссылаемую запись на изменение.</strong> Письмо — не архив, а сообщение в Slack — не ссылка. Цена пропуска: никто не может ответить «когда это изменилось» через шесть месяцев, включая вас. У письма всё же есть своя задача, разобранная в <a href="https://changeloop.dev/blog/ru/product-update-email/">шаблоне письма об обновлении продукта</a>; оно указывает на запись, а не заменяет её.</p> <p><strong>Группируйте по результату, а не по системе.</strong> Цена пропуска: читателю приходится держать вашу архитектуру в голове, чтобы понять, какой раздел относится к нему. Порядок, следующий из этого, — в <a href="https://changeloop.dev/blog/ru/how-to-write-release-notes/">как писать release notes</a>.</p> <p><strong>Сохраняйте скучный раздел.</strong> Обновления зависимостей и внутренние изменения остаются внизу, по одной строке каждое. Цена пропуска: команда безопасности, проверяющий соответствие и отлаживающий несовпадение версий теряют свой единственный источник. Чаще всего ошибаются в исправлениях; <a href="https://changeloop.dev/blog/ru/bug-fix-release-notes/">release notes об исправлении багов</a> показывает, как их писать, чтобы читатель понимал, нужно ли ему действовать.</p> <h2>Какие лучшие практики changelog, и чем они отличаются?</h2> <p>Changelog — это справочник, поэтому его практики касаются полноты и структуры, а не убеждения. Четыре важные:</p> <ul> <li><strong>Один фиксированный тип записи на строку.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. Это не домашний стиль, а фильтр: именно он позволяет запросить «только breaking change». Конвенция <a href="https://changeloop.dev/blog/ru/keep-a-changelog-implemented/">Keep a Changelog</a> — обычный источник.</li> <li><strong>Раздел неопубликованного.</strong> Место, где записи живут между merge и релизом. Его отсутствие — причина, по которой команды пишут записи поздно.</li> <li><strong>Даты ISO.</strong> <code>2026-08-28</code>, а не <code>28/08/26</code>, что означает два разных дня в зависимости от читателя.</li> <li><strong>Одна запись на изменение, а не на коммит.</strong> Три коммита, исправляющие один баг, — это одна запись.</li> </ul> <p>Оба артефакта подробно сравниваются в <a href="https://changeloop.dev/blog/ru/changelog-vs-release-notes/">changelog vs release notes</a>; короткая версия — практики changelog защищают полноту, а практики release notes защищают внимание. <a href="https://changeloop.dev/blog/ru/private-release-notes-enterprise/">Приватные release notes для enterprise-клиентов</a> разбирает версию этого, возникающую, только когда ваши клиенты больше не все на одной сборке: те же цели полноты и внимания, но откалиброванные по аккаунту вместо рассылки всем сразу.</p> <h2>Три, оказывающиеся чистым карго-культом</h2> <p><strong>Эмодзи как типы записей.</strong> Ракета и гаечный ключ — это не таксономия. Они выглядят аккуратно и не могут быть отфильтрованы, отсортированы или полезно прочитаны программой чтения с экрана. Используйте слова, а если хотите эмодзи, ставьте его после слова.</p> <p><strong>Семантические номера версий как заголовки для размещённого продукта.</strong> Semver — это обещание о совместимости API. Для продукта SaaS, где никто не выбирает свою версию, номер версии в заголовке — это внутренний архив, замаскированный под новость. Держите semver в changelog и вне анонса.</p> <p><strong>Публикация по расписанию независимо от содержания.</strong> Ежемесячные заметки без содержания учат людей, что ваши заметки — это шум. Публикуйте, когда есть что сказать. Changelog покрывает остальное.</p> <h2>Та, что действительно сложна</h2> <p>Поддержание changelog и анонса в согласии, без написания всего дважды.</p> <p>Большинство команд начинают с одной страницы, разделяют её, когда аудитории расходятся, а затем тихо позволяют одной из двух сгнить, обычно changelog, потому что у него нет прикреплённого дедлайна. Выход структурный, а не дисциплинарный: храните записи как данные с типом, датой и аудиторией, и относитесь к обеим поверхностям как к отображениям этого. Наш обзор <a href="https://changeloop.dev/changelog-tools">инструменты для changelog</a> охватывает, что доступно для этого, включая инструменты, с которыми мы конкурируем, а страница <a href="https://changeloop.dev/beamer-alternative">альтернатива Beamer</a> — честное сравнение с виджетом, с которого начинает большинство команд.</p> <p><a href="https://changeloop.dev/release-notes-template">Шаблон release notes</a> — это место, где живёт этап отбора, как только записи существуют.</p> <h2>Если вы внедряете только одно</h2> <p>Пишите запись в момент merge, в фиксированном формате, с типом. Каждая другая практика на этой странице становится проще, как только эта на месте, и ни одна не выживает без неё.</p> <h2>FAQ</h2> <p><strong>Должны ли release notes иметь скриншоты?</strong> Только того, что изменилось, в действии. Скриншот страницы настроек, которую никто не посещал, добавляет прокрутку, а не информацию. Текст, называющий результат и затронутого читателя, побеждает изображение, не показывающее ни того, ни другого.</p> <p><strong>Как писать release notes для breaking change?</strong> Сначала дата, потом затронутые вызывающие стороны, потом требуемое действие, потом миграция. Никогда не начинайте с номера версии. Полная форма с примером записи — в <a href="https://changeloop.dev/blog/ru/breaking-changes/">что такое breaking change</a>.</p> <p><strong>Должны ли release notes писаться инженерией или маркетингом?</strong> Составлены инженером, внёсшим изменение, в момент merge, и отредактированы кем-то, кто читает их как посторонний. Ни то ни другое само по себе не создаёт заметки, на основе которых клиент может действовать.</p> <p><strong>Какой идеальный формат для release notes?</strong> Сначала элементы с дедлайном, потом новые возможности, потом улучшения, потом список по одной строке для остального. <a href="https://changeloop.dev/release-notes-template">Шаблон release notes</a> — это формат в виде страницы для заполнения.</p> </article> </main></body></html>