--- metadata: - name: generator content: Diplodoc Platform v5.64.0 alternate: - https://ydb.tech/docs/en/contributor/documentation/feature-flags.md - https://ydb.tech/docs/ru/contributor/documentation/feature-flags.md - href: https://ydb.tech/docs/ru/contributor/documentation/feature-flags.md type: text/markdown title: Markdown version - href: https://ydb.tech/docs/ru/llms.txt?revision=40ebe20deddcd92d9c8cee412661fa2650bb1562&version=v26.3 rel: describedby sourcePath: ru/core/contributor/documentation/feature-flags.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt?revision=40ebe20deddcd92d9c8cee412661fa2650bb1562&version=v26.3 # Документирование функциональности под фича-флагами Документирование экспериментальной функциональности под [фича-флагами](https://ydb.tech/docs/ru/reference/configuration/feature_flags.md) включает условное предупреждение на каждой странице, где она описана. Предупреждение объясняет риски и отображается, пока соответствующий флаг выключен по умолчанию в версии YDB, для которой собирается документация. Не каждый выключенный флаг означает экспериментальную функциональность. Если флаг управляет стабильной возможностью, которая нужна не всем, опишите её как обычную настройку. Экспериментальный статус и связь возможности с конкретным флагом согласуйте с владельцем функциональности. ## Как добавить предупреждение {#add-warning} Добавьте плашку в начало страницы или раздела об экспериментальной функциональности. Если возможность описана на нескольких страницах, плашка нужна на каждой из них. Изменение документации экспериментальной функциональности без такого предупреждения считается неполным. Для флага из `NKikimrConfig.TFeatureFlags` используйте следующий сниппет: ```markdown {% 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 — в условии и в тексте предупреждения. Скорректируйте относительные пути ссылок: в примере они указаны относительно этой статьи. Для английской версии страницы используйте такой же флаг и соответствующий текст: ```markdown {% 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 %} ``` Если доступность зависит от нескольких флагов, условие должно соответствовать проверкам в реализации. Не выбирайте флаг только по сходству его имени с названием возможности. ## Как выбрать переменную {#variable-name} Флаги определяются не только в `ydb/core/protos/feature_flags.proto`. Для других источников переменная включает имя типа, чтобы не смешивать одноимённые поля разных сообщений. | Источник | Пример переменной | | --- | --- | | `NKikimrConfig.TFeatureFlags` | `feature_flags.enable_xxx` | | `NKikimrConfig.TTableServiceConfig` | `proto_flags.NKikimrConfig.TTableServiceConfig.enable_stream_write` | | Вложенные protobuf-сообщения | `proto_flags....` | | Зарегистрированные C++-структуры | `compile_time_flags.NActors.NFeatures.TCommonFeatureFlags.probe_spin_cycles` | Имена пакетов и типов сохраняют исходный регистр; имя поля преобразуется в snake_case. Например, `EnableStreamWrite` становится `enable_stream_write`. C++-пространства имён разделяются точками в переменной документации. Для флага из конфигурации сервиса замените условие сниппета на условие с нужным protobuf-типом. Например: ```markdown {% 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++ и не определяет параметры конкретной сборки бинарного файла. Для этих источников сначала установите смысл значения и связь с пользовательской возможностью. Не переносите на них булевое условие автоматически. ## Как работает сборка {#build} Перед сборкой Diplodoc генератор читает исходный код из того же checkout, что и документация, и добавляет значения в `default`-preset файла `ydb/docs/presets.yaml`. Поэтому документация `main` использует значения из `main`, а документация стабильной версии — из соответствующей стабильной ветки. | Значение в переменной | Результат условия `== false` | | --- | --- | | `false` | Предупреждение отображается. | | `true` | Предупреждение скрыто. | | `null`, включая зарегистрированный удалённый флаг | Предупреждение скрыто. | | Неизвестное имя флага или типа | Проверка имён завершает сборку с ошибкой. | Отсутствие предупреждения само по себе не доказывает готовность функциональности: `null` также может означать неопределённое значение. Статус возможности проверяют по её реализации и документации. Генератор получает значения по умолчанию из protobuf-схем и поддерживаемых C++-литералов. Они не заменяют проверку конфигурации работающего кластера и не учитывают значения, которые код приложения назначает дополнительно. Не редактируйте и не коммитьте сгенерированный блок `presets.yaml`. При бекпорте документации переносите сниппет с правильным именем флага; значения будут получены из исходного кода целевой ветки. ## Как проверить изменение {#validation} Из корня репозитория установите зависимости и запустите генератор: ```bash 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`. ## Что делать при удалении флага {#removed-flags} При удалении protobuf-поля зарезервируйте его исходное имя через `reserved`. Генератор присвоит соответствующей переменной `null`, и предупреждение с условием `== false` перестанет отображаться. Если имя нельзя сохранить в protobuf — например, удалено сообщение целиком или C++-поле — внесите ссылку в `retired_references` файла `sources.json`. Запись должна указывать пространство переменных, исходный тип и имя поля в snake_case. Пример для удалённого поля конфигурации сервиса: ```json { "namespace": "proto_flags", "message": "NKikimrConfig.TTableServiceConfig", "field": "enable_removed_example" } ``` Для `feature_flags` имя типа в записи не требуется. Для `compile_time_flags` используйте полное C++-имя структуры с разделителем `::`. Активное поле нельзя помечать удалённым. Не используйте этот реестр для обхода ошибки в имени: неизвестные ссылки должны обнаруживаться при сборке. После удаления флага проверьте актуальность описания самой возможности. Уберите ненужный сниппет при следующей правке страницы. Если возможность по-прежнему экспериментальная, замените условие проверкой актуального флага или сохраните безусловное предупреждение.