Перейти к основному содержимому

ADR 0073 — Публикуемый путь называет окружение, а не ветку

  • Статус: принят
  • Дата: 2026-08-13
  • Пересматривает: ADR 0071

Контекст​

ADR 0071 поместил три ступени в /brabo/<branch>/ и устранил асимметрию, существовавшую со времён ADR 0034. Чего он не поставил под вопрос, так это тождества двух вещей: сегмент URL был именем ветки, через интерполяцию $GITHUB_REF_NAME.

Это оставило стабильную документацию по адресу https://daneiel.github.io/brabo/main/, а main — слово того, кто коммитит. Тот, кто читает документацию, не выбирает ветку — он выбирает, насколько зрел текст, который будет читать. qa и dev работают как адрес по совпадению: они одновременно имя ветки и имя окружения. main нигде не является именем окружения.

Запрос пришёл от владельца продукта одной фразой: «main не может иметь путь /main, изменить на /prd».

Решение​

1. main публикуется в /brabo/prd/​

Две другие остаются в /brabo/qa/ и /brabo/dev/. Публикация остаётся симметричной по механизму — меняется то, что карта ветка→путь начинает существовать, а не быть тождественной функцией, записанной как интерполяция строки.

веткапубликуемый путь
main/brabo/prd/
qa/brabo/qa/
dev/brabo/dev/

2. Карта живёт в одном месте на процесс, и каждый выводит из неё остальное​

Это три независимых процесса, и у каждого своя единственная точка:

  • .github/workflows/docs-deploy.yml — шаг «Какая ступень и куда она публикует» испускает branch, caminho и base. baseUrl и подкаталог выходят оттуда вместе; их разделение — это то, как они начинают расходиться, а baseUrl, который не совпадает с каталогом, отдаёт HTML и больше ничего.
  • website/docusaurus.config.ts — таблица DEGRAUS несёт branch, caminho и метку. Селектор navbar и baseUrl по умолчанию читают из неё.
  • scripts/docs/landing.mjs — та же таблица, с caminho (каталог в дереве), отделённым от branch (откуда берётся тег, штампующий версию ступени). Это пара, которая обманывает больше всего: версия /prd/ берётся из тегов main, и замена одного на другое сделала бы так, что /prd/ казался бы никогда не опубликованным.

Что не выводится из пути: E_PRODUCAO остаётся DOCS_BRANCH === 'main'. Пункт 4 ADR 0071 фиксирует, почему выводить окружение из строки пути — это связанность, проявляющаяся только при изменении пути, — а этот ADR и есть изменение пути. Подтвердить это было самым важным тестом изменения: DOCS_BRANCH=main по-прежнему без noIndex; dev по-прежнему с ним.

3. /brabo/main/ переписывается через 404.html, а не сохраняется​

Каталог main/ сегодня опубликован. Поскольку дерево собирается и пушится с keep_files: false, он становится сиротой и исчезает при первом push, — и каждая сохранённая ссылка на /brabo/main/architecture сломалась бы.

Выход — тот же, что ADR 0071 использовал для ссылок старого корня, и по той же причине (держать копию сайта по двум адресам — значит дублировать публикацию при каждом push): 404.html корня переписывает префикс. /brabo/main/<algo> → /brabo/prd/<algo>.

Деталь, которая не является деталью: это собственный случай, а не общее перенаправление. Защита от петли ADR 0071 игнорировала любой путь, начинающийся с main|qa|dev, и с main вне дерева она сделала бы ровно неправильную вещь — вернула бы 404 для единственного пути, которому нужна обработка. Защита начинает покрывать только существующие пути (prd|qa|dev), а main обрабатывается до неё. Без собственного случая общее перенаправление дало бы /brabo/prd/main/<algo>.

4. Переход засевает /prd/ из gh-pages:main​

То же рассуждение, что в пункте 6 ADR 0071. gh-pages:prd рождается только тогда, когда main пройдёт конвейер после этого изменения, а первый push dev или qa приходит раньше: без семени /brabo/prd/ отвечал бы 404 днями, а 404.html отправлял бы всех именно туда.

Содержимое gh-pages:main — буквально сборка main. Оно засевает /prd/ — переписанным, и эта часть была обнаружена при симуляции сборки против настоящей gh-pages: baseUrl, встроенный в ту сборку, указывает на /brabo/main/, а 404.html из пункта 3 не спасает подресурсы. Его скрипт выполняется при навигации; <script src> или <link rel=stylesheet>, попавший в 404, получает HTML со статусом 404 и молча проваливается. Без переписывания /prd/ отдавал бы текст без CSS, без поиска и без гидратации — «загружает HTML и больше ничего», который docusaurus.config.ts описывает как самый коварный режим отказа этой публикации.

Переписывание — это sed с /brabo/main/ на /brabo/prd/ в ТЕКСТОВЫХ файлах семени, содержащих строку (542 из 634 в симуляции). Бинарный файл исключается через grep -I: sed -i в одном из них может добавить недостающий завершающий перевод строки и испортить его.

При первой публикации main нормальный путь берёт управление, и блок больше не выполняется.

Аналогичный блок ADR 0071 (засев /main/ из старого корня) был удалён в том же commit. Он уже выполнил свою роль — сегодняшняя gh-pages содержит main/, qa/ и dev/, — а его условие (существование FETCH_HEAD:index.html) стало совпадать с индексом, генерируемым самой landing: если бы его оставили, он превратил бы корневую страницу в ступень.

Последствия​

  • Ссылка на /brabo/main/… начинает стоить одного перенаправления навсегда. Это объявленная цена перемещения публичного адреса, и она меньше, чем цена дублирования сайта или поломки сохранённых ссылок.
  • qa и dev становятся совпадением, а не правилом. Тот, кто захочет переименовать один из них завтра, тронет таблицу и ничего больше — это и было структурным изменением, а не значение prd само по себе.
  • Корень не меняет роли. Он остаётся генерируемым индексом, перечисляющим все три, теперь канонизирующим на /prd/; About репозитория, README и AuthLayout.tsx указывают на него и остаются верными.
  • noIndex по-прежнему привязан к ветке. Никакого нового окружения не создаётся, и никакая настройка GitHub Pages не меняется: источником остаётся ветка gh-pages в папке / (root).
  • Ещё одна ступень — это ещё одна строка в трёх таблицах, а не поиск интерполированного $GITHUB_REF_NAME.

Отвергнутые альтернативы​

  • Публиковать в /prd/ и сохранить /main/ как копию. Сохраняет ссылки без перенаправления ценой дублирования всего сайта при каждой публикации и двух индексируемых адресов с одним содержимым — та же альтернатива, которую ADR 0071 уже отверг для корня.
  • Переименовать ветку main в prd. Решило бы вопрос тождества, сохранив интерполяцию, и обменяло бы публичный адрес на поломку в rulesets, конвейере релиза, backmerge и в каждой ссылке на main в репозитории. Словарь того, кто коммитит, — не проблема; проблема — словарь того, кто читает.
  • Перенаправлять /brabo/main/ на сервере. У GitHub Pages нет правил перенаправления; 404.html корня — существующий механизм.
  • Оставить как было. Это альтернатива, от которой отказывается запрос, и у неё есть слабый аргумент «за» (main уже был опубликован) против сильного «против»: адрес обращается к тому, кто читает, а не к тому, кто коммитит.