127 lines
8.2 KiB
Markdown
127 lines
8.2 KiB
Markdown
# P79 — сентябрь 2024: ADR / инженерные решения
|
||
|
||
## Scope и source report
|
||
|
||
Пакет заменяет только три overlay-статьи:
|
||
|
||
- editorial-2024-09-practice-adr-decisions
|
||
- editorial-2024-09-mechanism-adr-decisions
|
||
- editorial-2024-09-field-adr-decisions
|
||
|
||
Исторические ссылки закреплены до сентября 2024, а не оставлены на
|
||
меняющемся старом URL:
|
||
|
||
1. [Michael Nygard, Documenting Architecture Decisions — snapshot 22.08.2024](https://web.archive.org/web/20240822200738id_/https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) — первичный текст о context, decision, status, consequences и supersede.
|
||
2. [Nygard ADR template mirror — immutable commit 93f7e465, 18.10.2023](https://github.com/architecture-decision-record/architecture-decision-record/blob/93f7e465ad32f37091508674c5cba838c099b08a/locales/en/templates/decision-record-template-by-michael-nygard/index.md) — закреплённая проверка формы Title, Status, Context, Decision, Consequences.
|
||
3. [MADR 3.0.0 template — immutable commit 97fb8ed, 09.10.2022](https://raw.githubusercontent.com/adr/madr/97fb8edec60b8dc70b8166ef62de34c4e26b46c0/template/adr-template.md) — status, date, decision drivers, alternatives, outcome, consequences и validation.
|
||
|
||
Все три URL проверены обычным curl -I -L --fail без --insecure,
|
||
TLS bypass или авторизации: каждый завершился 200.
|
||
|
||
Факты из источников ограничены формой и lifecycle ADR. Варианты, веса,
|
||
scores, owners, identifiers, signals и outcomes в P79 — только fixed
|
||
synthetic in-memory objects. Они не читают и не описывают files, code, Git,
|
||
CI, сеть, production, interviews или metrics.
|
||
|
||
## Проход 1 — факты и техника
|
||
|
||
Проверено:
|
||
|
||
- Каждая статья называет scope ADR, alternatives, последствия, owner и
|
||
reassessment вместо обещания, что record сам делает решение правильным.
|
||
- Правило supersede сформулировано безопасно: сначала proposed successor,
|
||
затем human acceptance, только потом link Superseded; это не rollback
|
||
implementation.
|
||
- upgrade-2024-09.mjs не импортирует filesystem или network API. Input,
|
||
report и draft имеют exact-key contract; fixture проверяет unknown fields,
|
||
dense arrays, forged nested values, cyclic JSON, forged draft и отсутствие
|
||
external effect.
|
||
- Фикстура использует 33 assertions и не изменяет внешний state.
|
||
|
||
Команды и результат:
|
||
|
||
~~~text
|
||
node --check scripts/upgrade-2024-09.mjs
|
||
PASS
|
||
|
||
node scripts/upgrade-2024-09.mjs --verify-fixture
|
||
PASS fixture: 33/33 assertions
|
||
|
||
curl -I -L --fail --silent --show-error --max-time 30 <each source URL>
|
||
200 for all 3 pinned URLs
|
||
~~~
|
||
|
||
Вердикт: PASS. Нет неподтверждённых production claim, доступ к реальным
|
||
данным не встроен в учебный пример.
|
||
|
||
## Проход 2 — редактура и голос
|
||
|
||
Проверено:
|
||
|
||
- Автор сентября 2024 говорит как системный практик: начинает с конкретной
|
||
поломки или стоимости, отделяет evidence от assumption, называет owner и
|
||
next step.
|
||
- В каждом тексте есть цепочка
|
||
симптом → причина → проверка → действие, meaningful figure, HTML table,
|
||
воспроизводимый example, limitations и concrete next step.
|
||
- Нет общих формул из audit blacklist; предложения не выдают synthetic score
|
||
за metric или real team decision.
|
||
- Основной текст находится в диапазоне 5 000–15 000 знаков.
|
||
|
||
Команда и результат:
|
||
|
||
~~~text
|
||
npm run audit:draft -- scripts/upgrade-2024-09.mjs
|
||
PASS editorial-2024-09-practice-adr-decisions: 9650 body chars
|
||
PASS editorial-2024-09-mechanism-adr-decisions: 10890 body chars
|
||
PASS editorial-2024-09-field-adr-decisions: 10934 body chars
|
||
~~~
|
||
|
||
npm напечатал известные warnings о внешних user-config
|
||
store-dir, cache-dir, public-hoist-pattern; команда завершилась с
|
||
кодом 0, конфигурация не менялась.
|
||
|
||
Вердикт: PASS. Объём, problem/cost в первых двух абзацах и тон автора
|
||
соответствуют редакционному стандарту.
|
||
|
||
## Проход 3 — визуал и выпуск
|
||
|
||
Проверено:
|
||
|
||
- Три SVG автономны и содержат meaningful title, description, alt и caption
|
||
в статьях.
|
||
- В source нет script, foreignObject, javascript:, data:image или
|
||
event handlers.
|
||
- Все три схемы вручную открыты после рендера на ширине 375 px; длинные
|
||
подписи разбиты, нет обрезанных строк.
|
||
- Registry, README, articles.json, build, staging, commit и push намеренно
|
||
не затрагивались.
|
||
|
||
Команды и результат:
|
||
|
||
~~~text
|
||
xmllint --noout public/assets/editorial/2024/adr-decisions-2024-decision-flow.svg \
|
||
public/assets/editorial/2024/adr-decisions-2024-alternatives-matrix.svg \
|
||
public/assets/editorial/2024/adr-decisions-2024-reassessment-loop.svg
|
||
PASS
|
||
|
||
rg -n -i '<(script|foreignObject)\b|javascript:|data:image|(?:^|[[:space:]])on[a-z]+=' <three SVG paths>
|
||
PASS (no matches)
|
||
|
||
Sharp resize width=375
|
||
PASS decision-flow: 375x583
|
||
PASS alternatives-matrix: 375x500
|
||
PASS reassessment-loop: 375x510
|
||
~~~
|
||
|
||
Вердикт: PASS. Общий build не запускался по ограничению пакета. Пакет
|
||
остаётся draft: его не stage, commit или publish.
|
||
|
||
## Выпуск после трёх независимых проходов
|
||
|
||
1. **Факты и техника.** Редактор повторно открыл все три источника без TLS bypass. Оригинал Nygard сегодня доступен, но уже менялся после сентября 2024; поэтому в статье остаётся снимок Wayback от 22.08.2024 как исторически закреплённая копия первичного текста. Immutable templates подтвердили поля status/context/decision/consequences и decision drivers/options/outcome/validation. `node --check` и закрытая fixture — **PASS 33/33**.
|
||
2. **Редактура и голос.** Из публичной прозы удалены служебное имя партии `P79` и нерелевантная формулировка «AWS-like generic process»; они заменены словами «материал», «учебная модель» и ясной границей универсального процесса. Три статьи решают разные задачи: запись решения, сравнение альтернатив и reassessment. После правки объёмы — **9 659**, **10 869**, **10 955** знаков.
|
||
3. **Визуал и выпуск.** XML/safety scan, Sharp-render и ручной просмотр трёх SVG на 375 px подтвердили читаемость контраста, стрелок, матрицы и подписей. После подключения overlay `audit:articles` подтвердил по одной figure, table и code example на каждый slug; registry содержит **229** уникальных ревизий. `npm run build` прошёл: **374** статические страницы.
|
||
|
||
В выпуск включаются только пять файлов сентября, обновления registry/production README и эта приёмка. Пользовательские изменения, черновики августа и октября, а также исходный `articles.json` в него не включаются.
|