Что такое спецификация
dagstack/config-spec — нормативный источник истины по конфигурации в экосистеме dagstack. Он фиксирует, что должно выполняться в любой реализации (dagstack/config-python, dagstack/config-typescript, планируемый dagstack/config-go) — и почему именно так.
Чем раздел «Спецификация» отличается от руководств
| Раздел | Аудитория | Что даёт |
|---|---|---|
| Концепции | Разработчик приложений | Объясняет, как конфигурация работает сегодня в терминах конкретного языка. |
| Руководства | Разработчик приложений | Шаг за шагом проводит по типичной задаче. |
| Спецификация (этот раздел) | Автор реализации / ревьюер | Объясняет, почему принято решение; фиксирует нормативные гарантии. |
ADR
В v1.0 один ADR:
- ADR-0001: YAML-конфигурация с интерполяцией env — формат передачи, слои, интерполяция env, абстракция ConfigSource, модель ошибок, подписки, канонический JSON и артефакты спецификации.
Дополнительные ADR появятся по мере развития экосистемы (составные профили, параметризованные переопределения, валидационные webhook-вызовы и так далее).
Нормативный источник
Страницы этого раздела — описательное прозаическое резюме ADR. Формальный нормативный текст лежит в dagstack/config-spec. Если работаешь над изменениями внутри реализации, читай нормативную версию: она покрывает все edge case'ы, правила сериализации и требования к сообщениям об ошибках.
Как меняется спецификация
- Открой issue в
dagstack/config-spec. - Подай PR с новым ADR или ревизией существующего.
- Architect-review плюс sign-off от мейнтейнеров каждой реализации (каждая реализация подтверждает, что сможет выкатить изменение).
- После merge — обнови реализации и резюме в этом разделе.
Связанные спецификации
dagstack/plugin-system-spec— plugin-system читает секции плагинов через стек конфигурации.dagstack/logger-spec— логгер читает свою секцию из конфига.dagstack/tenancy-spec— модель tenancy настраивается через конфиг.