42 lines
11 KiB
Markdown
42 lines
11 KiB
Markdown
# P75 · 2024-05 · Шаблоны для команд — три самостоятельных прохода ревью
|
||
|
||
## Рамка sidecar-пакета
|
||
|
||
- Archive slugs: <code>editorial-2024-05-practice-platform-templates</code>, <code>editorial-2024-05-mechanism-platform-templates</code>, <code>editorial-2024-05-field-platform-templates</code>.
|
||
- Голос: M7, май 2024. Автор пишет коротко и прикладно: сначала ситуация и цена, затем симптом, причина, проверка и действие; он называет owner, границу инструмента, rollback и следующий шаг. В текст не добавлены вымышленные incident, метрики, adoption, скорость, usage или CI-result.
|
||
- Созданы ровно пять sidecar-файлов: этот review, import-safe script и три локальные SVG. Overlay, README, очередь, archive JSON, Git, staging, commit/push и чужие файлы не менялись.
|
||
- Fixture содержит только заранее записанные marked synthetic records в памяти Node. Он не читает template, repository, файлы, usage, issue, interview, CI log, environment, clock, сеть, HTTP или production state. PASS говорит лишь о согласованности учебных records и отрицательных веток.
|
||
|
||
## Проход 1 — факты, источники и модель
|
||
|
||
- Источники сверены 31.07.2026 и ограничены тем, что было доступно не позднее мая 2024. [Backstage v1.25.0: Software Templates](https://github.com/backstage/backstage/blob/v1.25.0/docs/features/software-templates/index.md) — первичный tagged snapshot: template может загрузить skeleton, подставить переменные и опубликовать результат; при ошибке видны шаги, отмена передаёт abort signal. Материал не превращает эти возможности в claim о скорости разработки, качестве generated output или безопасности custom action.
|
||
- [Backstage v1.25.0: Adding your own Templates](https://github.com/backstage/backstage/blob/v1.25.0/docs/features/software-templates/adding-templates.md) показывает Template entity с owner, type, parameters и последовательными steps. В статье это граница scaffolder-механизма: документация не определяет политику конкретной команды, credential boundary, допустимость всех action или критерий отказа от template.
|
||
- [GitHub Enterprise Server 3.12: Creating a template repository](https://docs.github.com/en/enterprise-server@3.12/repositories/creating-and-managing-repositories/creating-a-template-repository) фиксирует: новая repository получает структуру и файлы template, но созданные ветви имеют несвязанную историю. Поэтому текст говорит о риске самостоятельных copies и не обещает автоматическую синхронизацию base template с fork-ами.
|
||
- Модель держит один versioned base contract: known owner, internal HTTP service, approved runtime и internal data class. Она различает три фиксированных case: совпадение с golden path; одно named extension с owner, boundary и rollback; отказ для one-off regulated migration без стабильного shape, owner и policy. Эти case не описывают реальные сервисы.
|
||
- Input contract закрыт: marker synthetic, точный scope, fixed-memory-only mode и известный case id. Extra field, request path, file-like field, usage-like field, иной scope, scan mode и неизвестный case отдельно отклоняются. Fixture не может стать скрытым reader для template, repository, usage, issue, interview, CI или сети.
|
||
- Главная приёмка заменила allow-list ключей на exact own-key contract для input, report и decision draft. Canonical comparison безопасно отвергает циклический внешний report, а rollback не принимает разрежённый список actions. Это не создаёт capability для реального template; это не даёт учебному примеру сломаться или принять неаудируемую форму.
|
||
- Plan повторно создаёт canonical report из embedded record и сравнивает весь report, а не только verdict. Подмена decision, исчезновение extension или добавление repositoryPath возвращают rejection. Rollback принимает лишь canonical synthetic draft и возвращает явное отсутствие операций над template, repository, files, catalog, CI и сетью.
|
||
- На самостоятельном model review добавлена отдельная отрицательная ветка для usage-like input. До неё общий extra-field guard уже защищал модель, но явная assertion делает границу «не читать и не утверждать adoption» проверяемой, а не только описанной в комментарии.
|
||
|
||
## Проход 2 — язык, объём и голос
|
||
|
||
- Все три статьи начинают с ситуации и цены. Practice показывает, как переключатели превращают template в набор несовместимых стартовых точек. Mechanism показывает цену открытого input contract. Field разбирает три synthetic requests и цену общего действия Create для разных классов решений.
|
||
- В каждом материале есть последовательность «симптом → причина → проверка → действие», а не общая рекомендация. У practice действие — оставить только повторяемый base contract; у mechanism — закрыть input и отличить plan от operation; у field — выбрать golden path, named extension либо explicit decline.
|
||
- Таблицы отвечают на рабочие вопросы: что входит в base contract, чем различаются механизмы, как три requests получают разные outcomes. Примеры помечены synthetic и прямо перечисляют, что модель не читает. В каждой статье есть ordered route, ограничение, rollback и следующий шаг.
|
||
- Основной текст без раздела источников: practice — 10 288 знаков, mechanism — 11 646 знаков, field — 11 039 знаков. Все материалы входят в обязательный диапазон 5 000–15 000 и целевой коридор 8–11 тыс. с небольшим оправданным запасом у mechanism, где отдельно объяснены три технических слоя.
|
||
- Речь вычитана на M7: short technical claims привязаны к договору, owner-у или источнику. Слова golden path, extension, decline, repository template, scaffolder, invariant и rollback не служат украшением. Нет обещания, что template сам обеспечит adoption, безопасность, совместимость, скорость, production approval или синхронизацию копий.
|
||
|
||
## Проход 3 — визуал, безопасность и выпуск
|
||
|
||
- Три SVG разделяют три разных вопроса: base facts и golden path; controlled escape hatch; цикл решения, evidence и версии policy. У каждого рисунка есть содержательный alt в статье и подпись, которая отделяет схему от реального состояния template, CI, usage и production.
|
||
- XML validation трёх SVG — PASS. SVG safety scan — чисто: нет script, foreignObject, external URL, data:image или event-handler атрибутов. Все изображения статичны, не принимают input и не тянут внешние ресурсы.
|
||
- Sharp-render каждого SVG на 375 px и ручной просмотр — PASS. Заголовки, карточки, стрелки, нижние ограничения и красно-жёлто-зелёные развилки читаются; текст не обрезан, блоки не перекрываются. В первой схеме прямо отделён новый policy от поля формы, во второй видны три outcomes, в третьей нет ложного графика adoption.
|
||
- Финальные проверки: <code>node --check web/scripts/upgrade-2024-05.mjs</code> — PASS; fixed memory-only fixture — PASS 27/27 assertions; <code>cd web && npm run audit:draft -- scripts/upgrade-2024-05.mjs</code> — PASS для трёх slug; import-safe export не содержит date или author; XML — PASS; SVG safety — чисто; Sharp 375 px — PASS.
|
||
- Пакет намеренно не интегрирован: overlay, README и очередь не менялись; commit и push не выполнялись. Реальные analysis, credentials, action execution, dry run, CI, validation, evidence collection и rollout находятся за границей P75.
|
||
|
||
## Выпуск после трёх проходов
|
||
|
||
- Главный редактор подключил ровно три майские ревизии в `web/data/editorial-revisions.mjs`, не меняя архивный `articles.json`, и обновил счётчик производства до 229 из 358 материалов.
|
||
- После подключения `npm run audit:articles -- <три slug>` подтвердил объём, figure, таблицу и пример каждой статьи; registry содержит 220 уникальных ревизий без повторов slug.
|
||
- `npm run build` завершился успешно: Next.js сгенерировал 374 статические страницы. В выпуск не включены пользовательские правки и неинтегрированные sidecar-пакеты июня и июля.
|