av
26256cdb06
- Инструментарий проекта спеками не нормируется: capability toolchain удалена, норму шага сверки версий Go держат его проверки в scripts. - Перечень capability в архитектуре и ревью сокращён до четырёх, решение ADR-2026-08-12-spec-norms-build-toolchain помечено устаревшим.
67 lines
5.8 KiB
Markdown
67 lines
5.8 KiB
Markdown
# ADR-2026-08-12. Спекой нормируется и инструмент сборки, а не только поведение сервиса
|
||
|
||
- **Дата:** 2026-08-12
|
||
- **Источник:** [openspec/changes/archive/2026-08-12-go-1-26-upgrade/design.md](../../openspec/changes/archive/2026-08-12-go-1-26-upgrade/design.md), раздел `Decisions`, Решение 2
|
||
- **Статус:** устарело — 2026-08-13 владелец решил обратное: инструментарию в
|
||
спеках не место. Capability `toolchain` упразднена, замены у неё нет, норму
|
||
шага держат его проверки в `scripts/check_go_version_test.go`
|
||
|
||
## Решение
|
||
|
||
Заведена capability `toolchain` — четвёртая, и первая, которая описывает **не
|
||
поведение сервиса** для его потребителей, а поведение инструмента, которым сервис
|
||
собирают. Потребитель у неё другой: тот, кто собирает.
|
||
|
||
Требование о согласованности объявленной версии Go живёт нормой в
|
||
`openspec/specs/toolchain/spec.md`, а не прозой в памятке. *Уточнено 2026-08-13:
|
||
файла по этому адресу больше нет, ссылка снята — capability упразднена, см.
|
||
статус записи.*
|
||
|
||
## Почему
|
||
|
||
Три существующие capability — `intake`, `pipeline`, `storage` — все про то, что
|
||
сервис делает для своих потребителей, а преамбула `architecture.md` прямо
|
||
говорила «поведение системы здесь не описывается — нормативно оно живёт в
|
||
`openspec/specs/`». Согласованность версий сборки под это определение не
|
||
подходит, и натяжение признано прямо в источнике:
|
||
|
||
> Признаём натяжение: три существующие capability описывают поведение сервиса для
|
||
> его потребителей, а `toolchain` описывает поведение инструмента разработки.
|
||
> Потребитель у него другой — тот, кто собирает сервис. Правило `config.yaml`
|
||
> говорит «поведение **или домен** системы»; инструмент сборки — домен, и именно
|
||
> как домен он здесь и назван.
|
||
|
||
Очевидные пути отвергнуты оба:
|
||
|
||
> **Отвергнуто: дописать в `pipeline`.** `pipeline` нормирует прогон воркера и
|
||
> захват задачи — поведение работающего сервиса. Версия сборщика с ним не
|
||
> меняется вместе.
|
||
>
|
||
> **Отвергнуто: обойтись без дельта-спеки.** Изменение вводит проверяемое
|
||
> требование — «расхождение роняет набор проверок», — и требование без дома
|
||
> проверяется только памятью того, кто его завёл. Обещание «образ собирается» уже
|
||
> один раз жило в трёх документах и во всех трёх было неверным.
|
||
|
||
Последнее и есть довод, перевесивший чистоту определения: дефект 2026-08-12
|
||
случился именно потому, что утверждение о версии сборки жило только прозой, в
|
||
трёх местах сразу, и никто не отвечал за его истинность.
|
||
|
||
## Последствия
|
||
|
||
- `+` у правила о версиях есть нормативный дом со сценариями, и по нему видно, что
|
||
проверено, а что оставлено человеку. Три требования, двадцать два сценария.
|
||
- `+` следующая задача про инструмент сборки знает, куда дописывать, и не заводит
|
||
вторую спеку о том же.
|
||
- `−` определение capability в проекте стало шире, чем «поведение сервиса», и
|
||
граница теперь проходит по слову «домен». Следующее пограничное решение будет
|
||
ссылаться на этот прецедент — в том числе тогда, когда ссылаться не стоило бы.
|
||
- `−` асимметрия: четыре однородных шага гейта живут в двух разных домах. У трёх
|
||
плагинных (`docs.py`, `tasks.py`, `openspec.py`) нормативного дома нет вовсе,
|
||
только строка в памятке; у четвёртого есть спека. Либо дома появятся у
|
||
остальных, либо асимметрия останется навсегда.
|
||
- `−` имя `toolchain` выбрано в том числе из-за настройки среды разработчика:
|
||
первая редакция звалась `build`, и глобальный запрет чтения каталогов с таким
|
||
именем сделал спеку нечитаемой для проходов ревью. Имя, выбранное под
|
||
ограничение инструмента, а не под предмет, — слабое основание, и при следующем
|
||
пересмотре его стоит перепроверить.
|