Документирование функциональности под фича-флагами

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

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

Как добавить предупреждение

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

Для флага из NKikimrConfig.TFeatureFlags используйте следующий сниппет:

{% if feature_flags.enable_xxx == false %}
{% note warning "Экспериментальная функциональность" %}

Функциональность находится в разработке и по умолчанию выключена флагом [`enable_xxx`](../../reference/configuration/feature_flags.md). Её поведение может измениться без сохранения обратной совместимости, а сама функциональность может так и не стать общедоступной. Включение флага может привести к ошибкам, нестабильной работе кластера или невозможности сменить версию YDB. Не включайте флаг в production-кластерах. [Подробнее](../../reference/configuration/feature_flags.md#experimental).

{% endnote %}
{% endif %}

Замените enable_xxx на имя реального флага в snake_case — в условии и в тексте предупреждения. Скорректируйте относительные пути ссылок: в примере они указаны относительно этой статьи. Для английской версии страницы используйте такой же флаг и соответствующий текст:

{% if feature_flags.enable_xxx == false %}
{% note warning "Experimental feature" %}

This feature is under development and is disabled by default by the [`enable_xxx`](../../reference/configuration/feature_flags.md) flag. Its behavior may change without backward compatibility, and the feature may never become generally available. Enabling the flag may cause errors, cluster instability, or make it impossible to change the YDB version. Do not enable this flag in production clusters. [Learn more](../../reference/configuration/feature_flags.md#experimental).

{% endnote %}
{% endif %}

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

Как выбрать переменную

Флаги определяются не только в ydb/core/protos/feature_flags.proto. Для других источников переменная включает имя типа, чтобы не смешивать одноимённые поля разных сообщений.

Имена пакетов и типов сохраняют исходный регистр; имя поля преобразуется в snake_case. Например, EnableStreamWrite становится enable_stream_write. C++-пространства имён разделяются точками в переменной документации.

Для флага из конфигурации сервиса замените условие сниппета на условие с нужным protobuf-типом. Например:

{% if proto_flags.NKikimrConfig.TTableServiceConfig.enable_stream_write == false %}
<!-- Здесь разместите предупреждение для соответствующей экспериментальной возможности. -->
{% endif %}

Генератор учитывает зарегистрированные protobuf-источники и их импорты: конфигурации сервисов, PQ, Blob Storage, аутентификации, FQ, NBS и другие сообщения. Реестр находится в ydb/docs/tools/feature_flags/sources.json. Если источник не зарегистрирован и не попадает в импорты, добавьте его в реестр. Для нового C++-источника также проверьте фильтры запуска сборки в GitHub workflows.

Наличие поля в сгенерированном каталоге не означает, что оно управляет экспериментальной функциональностью кластера:

• Ydb.FeatureFlag.Status — состояние параметра публичного API. Значение STATUS_UNSPECIFIED не равнозначно false.
• Поля Viewer описывают ответ API, а поля физического плана — данные плана запроса. Их protobuf-default не определяет доступность возможности на кластере.
• Для C++-флагов читаются только литералы constexpr bool. Вычисляемое выражение получает значение null: генератор не исполняет C++ и не определяет параметры конкретной сборки бинарного файла.

Для этих источников сначала установите смысл значения и связь с пользовательской возможностью. Не переносите на них булевое условие автоматически.

Как работает сборка

Перед сборкой Diplodoc генератор читает исходный код из того же checkout, что и документация, и добавляет значения в default-preset файла ydb/docs/presets.yaml. Поэтому документация main использует значения из main, а документация стабильной версии — из соответствующей стабильной ветки.

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

Генератор получает значения по умолчанию из protobuf-схем и поддерживаемых C++-литералов. Они не заменяют проверку конфигурации работающего кластера и не учитывают значения, которые код приложения назначает дополнительно.

Не редактируйте и не коммитьте сгенерированный блок presets.yaml. При бекпорте документации переносите сниппет с правильным именем флага; значения будут получены из исходного кода целевой ветки.

Как проверить изменение

Из корня репозитория установите зависимости и запустите генератор:

python3 -m pip install -r ydb/docs/tools/feature_flags/requirements.txt
python3 ydb/docs/tools/feature_flags/generate.py --catalog feature-flag-defaults.json

Генератор проверит имена флагов в условиях и создаст каталог feature-flag-defaults.json с исходными файлами, типами и значениями. В CI этот каталог доступен как артефакт feature-flag-defaults.

Проверьте русский и английский предпросмотр из PR. Убедитесь, что имя флага и условие одинаковы, предупреждение соответствует экспериментальному статусу, а ссылки ведут на статью и её раздел #experimental. При локальной сборке используйте инструкции в ydb/docs/README.md.

Что делать при удалении флага

При удалении protobuf-поля зарезервируйте его исходное имя через reserved. Генератор присвоит соответствующей переменной null, и предупреждение с условием == false перестанет отображаться.

Если имя нельзя сохранить в protobuf — например, удалено сообщение целиком или C++-поле — внесите ссылку в retired_references файла sources.json. Запись должна указывать пространство переменных, исходный тип и имя поля в snake_case. Пример для удалённого поля конфигурации сервиса:

{
  "namespace": "proto_flags",
  "message": "NKikimrConfig.TTableServiceConfig",
  "field": "enable_removed_example"
}

Для feature_flags имя типа в записи не требуется. Для compile_time_flags используйте полное C++-имя структуры с разделителем ::. Активное поле нельзя помечать удалённым. Не используйте этот реестр для обхода ошибки в имени: неизвестные ссылки должны обнаруживаться при сборке.

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