131 lines
13 KiB
Markdown
131 lines
13 KiB
Markdown
# P81 — ноябрь 2024: удаление устаревшего API/пути
|
||
|
||
## Область пакета
|
||
|
||
Заменяются только три overlay-статьи:
|
||
|
||
- <code>editorial-2024-11-practice-deprecation</code> — «Устаревший API нельзя удалить по дате в календаре».
|
||
- <code>editorial-2024-11-mechanism-deprecation</code> — «Почему telemetry не равна списку пользователей».
|
||
- <code>editorial-2024-11-field-deprecation</code> — «Последний consumer: доказуемое удаление».
|
||
|
||
Все имена, даты, счётчики, classes, outcomes и actions внутри статей и fixture
|
||
являются fixed synthetic in-memory значениями. Пакет не выполняет source search,
|
||
API requests, telemetry reading, access-log query, customer lookup, Git, CI,
|
||
network или production action. Он не обещает отсутствие hidden consumers.
|
||
|
||
## Исследование и историческая граница
|
||
|
||
Проверка ссылок выполнена 31.07.2026 обычным HTTPS GET и direct curl:
|
||
все четыре URL вернули HTTP 200 без авторизации и без TLS bypass. Эта дата проверки не
|
||
меняет историческую границу публикации: все закреплённые версии были доступны
|
||
до ноября 2024.
|
||
|
||
| Источник | Дата / версия | URL | Узко поддерживаемое утверждение | Граница утверждения |
|
||
| --- | --- | --- | --- | --- |
|
||
| IETF RFC 8594 | May 2019 | https://datatracker.ietf.org/doc/rfc8594/ | <code>Sunset</code> сообщает, что конкретный URI вероятно станет недоступен в указанную дату; это hint о lifecycle. | Не доказывает фактическую доступность до или после даты, не перечисляет consumers, не задаёт миграционный процесс. |
|
||
| IETF draft deprecation header | revision 09, 27.09.2024 | https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header-09 | <code>Deprecation</code> сообщает, что resource уже deprecated или будет deprecated; link relation может вести к документации и guide. | На ноябрь 2024 это Internet-Draft, не RFC. Header не меняет behavior resource и не является user list. |
|
||
| OpenAPI Specification | v3.1.0, versioned official URL | https://spec.openapis.org/oas/v3.1.0.html | <code>deprecated: true</code> в Operation Object объявляет operation устаревшей; consumers SHOULD refrain from usage. | Не доказывает, что generated clients обновлены, runtime usage прекратился или replacement совместим. |
|
||
| Semantic Versioning | 2.0.0, versioned official URL | https://semver.org/spec/v2.0.0.html | Public API должен быть declared; deprecated public functionality требует minor increment, incompatible public change — major increment. | Это правило versioning заявленного API, не policy удаления, telemetry model или authority для отключения endpoint. |
|
||
|
||
## Проход 1 — факты и техника
|
||
|
||
**Проверен предмет утверждений.**
|
||
|
||
- Разделены declaration в OpenAPI, runtime lifecycle signal, Sunset boundary и
|
||
отдельный removal change. Нигде не сказано, что header, дата или один график
|
||
доказывают отсутствие consumers.
|
||
- RFC 8594 использован только для Sunset: предполагаемая недоступность URI и
|
||
его hint-семантика. Текст не называет timestamp гарантийным SLA.
|
||
- Draft-09 прямо помечен Internet-Draft на историческую дату; он не выдан за
|
||
опубликованный RFC. Его утверждение ограничено signal и documentation link.
|
||
- SemVer и OpenAPI не подменяют consumer map: они объясняют contract and
|
||
versioning vocabulary, а не фактическое использование API.
|
||
- Во всех трёх статьях real telemetry, customer list, traffic count, incident,
|
||
source search and production outcome исключены прямо в тексте и в модели.
|
||
|
||
**Проверен пример.**
|
||
|
||
- <code>createFixedSyntheticDeprecationInput</code> принимает только три fixed case id.
|
||
- <code>inspectSyntheticDeprecation</code> строит только canonical report из frozen
|
||
objects; отсутствуют file, Git, network, CI, clock, telemetry, customer-list
|
||
and production effects.
|
||
- <code>planSyntheticDeprecationReview</code> принимает только exact canonical report и
|
||
создаёт human-review draft, а не action against an API.
|
||
- <code>restoreSyntheticDeprecationReview</code> выбрасывает только canonical in-memory
|
||
draft. Он явно не выдаётся за rollback deployed route.
|
||
- Fixture покрывает exact input/report/draft contracts, dense arrays, unknown
|
||
fields, forged records, active/unknown/migrated states, cyclic input,
|
||
cyclic report rejection and direct canonical JSON cycle rejection.
|
||
|
||
**Вердикт:** пройдено. Источники не расширены до несуществующих гарантий, а
|
||
synthetic model не притворяется операционным доказательством.
|
||
|
||
## Проход 2 — редактура и голос
|
||
|
||
Ноябрь 2024 остаётся уровнем системного практика, а не автора 2027:
|
||
системная граница названа через contract, owner, compatibility, review and
|
||
restore boundary, но нет деклараций о масштабе организации, универсальной
|
||
policy или выдуманных metrics.
|
||
|
||
| Статья | Проблема и цена в первых двух абзацах | Основной текст | Практический артефакт | Проверяемый финал |
|
||
| --- | --- | ---: | --- | --- |
|
||
| practice | Календарная дата выдаётся за доказательство, неизвестный client получает отказ. | 9 393 знака | consumer map, deprecation record, removal gate | Заполнить шесть колонок для одной operation и остановиться на первой unknown row. |
|
||
| mechanism | Нулевой signal превращают в user list, hidden client выпадает из выбранного окна. | 10 864 знака | evidence matrix, lifecycle timeline, pure fixture | Составить пять evidence rows и назвать blind zone каждой. |
|
||
| field | Named integrations migrated, но hidden caller не доказан отсутствующим; удаление может сломать compatibility. | 10 614 знаков | три fixed cases, removal gate, checklist | Выдать честный active / unknown / migrated verdict и зафиксировать stop condition. |
|
||
|
||
Редакторская вычитка:
|
||
|
||
- В первых двух абзацах каждой статьи есть situation and cost, без вводной о
|
||
«важности API».
|
||
- Каркас следует формуле «симптом → причина → проверка → действие».
|
||
- Каждая статья содержит figure с содержательным <code>alt</code> и caption, HTML table,
|
||
ordered route, reproducible code/example, limitations, sources and next step.
|
||
- Термины <code>telemetry</code> и <code>removal gate</code> раскрыты при первом содержательном
|
||
появлении; English names остаются только там, где они называют code or
|
||
protocol artifact.
|
||
- Удалены обещания «последний consumer найден» и «rollback доступен» без
|
||
boundary. Состояние <code>unknown</code> сохранено как честный результат.
|
||
- Объём находится внутри 5 000–15 000 знаков, а audit:draft подтверждает
|
||
наличие требуемой структуры.
|
||
|
||
**Вердикт:** пройдено. Тон короткий и технический, каждый большой абзац
|
||
добавляет symptom, mechanism, check, limitation или next action.
|
||
|
||
## Проход 3 — визуал и выпуск
|
||
|
||
Проверены три ручные SVG:
|
||
|
||
| Asset | Смысл | 375 px |
|
||
| --- | --- | --- |
|
||
| <code>deprecation-2024-consumer-map.svg</code> | contract → known/unknown consumer map → closed gate | 375×291, читаемо после центрирования нижней плашки. |
|
||
| <code>deprecation-2024-timeline.svg</code> | warning → deprecated → sunset → removal, с границами каждого состояния | 375×291, читаемо. |
|
||
| <code>deprecation-2024-removal-gate.svg</code> | active / unknown / migrated → human review → separate change | 375×291, читаемо после сокращения нижней подписи. |
|
||
|
||
Проверки:
|
||
|
||
- <code>node --check web/scripts/upgrade-2024-11.mjs</code> — PASS.
|
||
- <code>node web/scripts/upgrade-2024-11.mjs --verify-fixture</code> — PASS, 34/34 assertions.
|
||
- <code>npm run audit:draft -- scripts/upgrade-2024-11.mjs</code> — PASS для трёх slug.
|
||
- <code>xmllint --noout</code> для трёх SVG — PASS.
|
||
- SVG safety scan — чисто: нет <code>script</code>, <code>foreignObject</code>, <code>javascript:</code>,
|
||
<code>data:image</code> и event-handler attributes.
|
||
- Sharp render на ширине 375 px и ручная визуальная проверка — PASS.
|
||
|
||
В первом visual pass обнаружен выход нижней плашки consumer map за <code>viewBox</code>;
|
||
геометрия исправлена и оба затронутых SVG повторно проверены на 375 px.
|
||
|
||
Общий build намеренно не запускался: это самостоятельный draft-пакет, а
|
||
пользователь запретил трогать registry, README, очередь, articles.json,
|
||
staging, commits and publishing. Регистрация overlay, full build и выпуск
|
||
остаются задачей интегратора после отдельного review.
|
||
|
||
**Вердикт:** пройдено для draft-пакета. Git and publication state не изменены.
|
||
|
||
## Выпуск после трёх независимых проходов
|
||
|
||
1. **Факты и техника.** Редактор повторно проверил RFC 8594, draft-09 от 27.09.2024, OpenAPI 3.1.0 и SemVer 2.0.0. Sunset и Deprecation остаются hints и не меняют behaviour endpoint; draft-09 на историческую дату действительно был Internet-Draft; OpenAPI/SemVer описывают контракт и версию, но не список users. `node --check` и fixture — **PASS 34/34**.
|
||
2. **Редактура и голос.** Три статьи различают consumer map, виды evidence и removal gate. Тексты не обещают найти последнего consumer: `unknown` остаётся допустимым результатом. Объёмы — **9 393**, **10 864**, **10 614** знаков; в каждом тексте есть problem/cost, две таблицы, пример, ограничения и проверяемый следующий шаг.
|
||
3. **Визуал и выпуск.** XML/safety scan, Sharp-render и ручная проверка на 375 px подтвердили читаемость consumer map, timeline и removal gate после исправления нижней плашки. После подключения overlay `audit:articles` подтвердил 1 figure, 2 table и 1 code example на каждый slug; registry содержит **238** уникальных ревизий. `npm run build` успешно создал **374** страницы.
|
||
|
||
В выпуск включаются только пять файлов ноября, обновления registry/production README и эта приёмка. Пользовательские изменения, черновики декабря/января и исходный `articles.json` исключены.
|