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

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

Что такое changelog API?

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

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

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

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

Что должно входить в одну запись?

Шесть вещей, и первых трёх обычно не хватает. Само изменение, сформулированное в терминах запроса или ответа, а не внутреннего компонента. Ломает ли оно правильного вызывающего. Что должен сделать вызывающий, включая “ничего”. Дата вступления в силу. Затронутая версия или версии. Ссылка на руководство по миграции, если оно есть.

Запись, которая говорит “улучшен endpoint accounts”, проваливается по всем шести пунктам. Запись, которая говорит “поле accounts.type теперь возвращает individual там, где раньше возвращало personal; существующие значения не меняются для аккаунтов, созданных до 2 сентября; действие не требуется, если вы не сравниваете строку”, отвечает на все шесть в одном предложении.

Категоризируйте записи по последствиям, а не по отделу. Три метки несут почти всю ценность: breaking, additive и fixed. Semantic Versioning уже точно определяет первые две, и заимствование его определений вместо изобретения своих означает, что читатель, знающий semver, знает и ваши метки. Keep a Changelog предлагает более длинный набор, если хотите, и его центральное правило действует здесь сильнее, чем где-либо ещё: журнал — для людей, а свалка заголовков коммитов — нет.

Чем changelog API отличается от release notes?

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

Практическое следствие в том, что эти два не могут быть одним и тем же потоком с разным стилем. Вызывающий, подписанный на всё, что вы выпускаете, в конце концов отпишется и тогда пропустит breaking change. Если публикуете один поток — фильтруйте его; если публикуете два — сделайте поток API уже и никогда не пускайте в него маркетинговую запись. Мы сравниваем обе формы бок о бок в changelog против release notes.

Где должен жить changelog API?

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

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

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

Три записи за одну неделю, в описанной выше форме:

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

Третья — тип, который чаще всего пропускают, потому что внутри это исправление бага. Для вызывающего, построившего retry вокруг этой пустой страницы, это изменение поведения, и запись — именно то, что предотвращает тикет в поддержку. Метка говорит fixed, а тело говорит, что мог бы заметить вызывающий, и это различие держит журнал честным, не раздувая каждое исправление до breaking change.

Как вызывающие на это подписываются?

Дайте им больше одного канала, потому что у них разные задачи. Поток для разработчика, которому нужно всё. Email для того, кому нужны только breaking changes. Заголовки ответа для самого кода — единственного подписчика, который никогда не забывает проверить: заголовок Sunset, определённый в RFC 8594, помещает дату вывода из эксплуатации в ответ, где клиентская библиотека может её залогировать.

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

Как написать запись для breaking change?

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

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

В changeloop изменение API становится записью, когда pull request объединяется, кто-то редактирует и утверждает черновик, и запись публикуется в ленте и виджете в тот же момент, когда вызывающего, чей отзыв из виджета стал GitHub issue, который закрывает этот pull request, оповещают об этом в том же issue. Шаг проверки — именно то, что здесь важно: changelog API — это договорной документ, и ни один черновик не должен дойти до вызывающего без того, чтобы его прочитал человек.

FAQ

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

Должен ли changelog API жить в документации или на маркетинговом сайте? В документации, прямо рядом со справочником. Читатель обычно уже там, а changelog на маркетинговом сайте склонен набирать аудиторию, для которой он не был написан.

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

Нужен ли отдельный changelog для каждой версии API? Нет, один журнал с полем версии в каждой записи легче читать и искать. Фильтрация по версии — функция страницы, а не причина разделять документ.

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

По теме на changeloop: Документация для разработчиков, Примеры changelog