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

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

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

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

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

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

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

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

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

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