ADR-0015 · Продуктовые доки на своём домене, контрибьюторские — на Pages
Статус: принято · 2026-08-01 (issue: play-api#203). Уточняет ADR-0012.
Контекст. ADR-0012 завёл один публичный сайт доков play-api по экосистемному паттерну «сайт при репозитории» — GitHub Pages project site на jc.id.lv/<repo>. За прошедшее время сайт вырос из справочника по API в продуктовый портал для сторонних разработчиков ботов: quickstart, лестница, provably-fair, лицензирование, OpenAPI/AsyncAPI для кодогенерации. Одновременно накопился спрос на документацию совсем другой аудитории — контрибьюторов самого play-api: карта модулей, схема БД, доктрина конкурентности, конвенции тестов. Обе не помещаются в один Pages-слот репозитория: они конкурируют за навигацию и смешивают аудитории ровно так же, как ADR-0012 запрещал смешивать вики и публичный сайт.
Дополнительный аргумент — технический: project site живёт на базовом пути /<repo>, и GitHub Pages не даёт ни preview-деплоя на PR, ни _headers/_redirects, ни аналитики.
Решение. Расщепить публичную документацию по аудиториям, введя третий критерий к границе ADR-0012 (внешний продукт vs внутренняя разработка):
- Продуктовые доки для внешней аудитории — выделенный домен. Bot API переехал на
bots.jc.id.lv, деплой — assets-only Cloudflare Worker (docs/,wrangler.jsonc), корневой base. - Контрибьюторские доки — остаются на паттерне ADR-0012,
jc.id.lv/<repo>через GitHub Pages (contributor-docs/). Освободившийся слот занят именно ими. - Вики (эта) — без изменений: внутреннее, русский, ADR и роадмап. Вики приватная, поэтому в публичных доках на ADR ссылаемся только по номеру, без ссылок.
Унаследованные слаги бот-доков (/quickstart/, /reference/*, …) отдаются с Pages как redirect-страницы на bots.jc.id.lv; корень не редиректится — это индекс контрибьюторского сайта с явным указателем на Bot API.
Ключевой инвариант нового сайта: генерируемое вместо рукописного. Колоночный справочник схемы БД собирается в CI (Flyway → throwaway Postgres → tbls → Starlight-страница), результат коммитится, и отдельная джоба падает, если закоммиченное разошлось с миграциями. Тот же принцип, что уже работает для openapi.yaml: доки не могут отстать от кода, потому что выводятся из него.
Последствия.
- Внешняя аудитория получает короткий домен без базового пути, preview-деплои на PR и нормальный SEO; ссылка
bots.jc.id.lvчитается как продукт, а не как путь в чьём-то репозитории. - Экосистемный паттерн ADR-0012 не отменяется, а уточняется: он остаётся дефолтом, выделенный домен — исключение для продукта, обращённого наружу. Движок и analytics не трогаем.
- Цена: два
package.jsonв одном репо вместо одного (оба под Dependabot), два независимых CD-воркфлоу, две группы concurrency. - Разовая миграция ссылок: 13 репозиториев, 21 файл, обе исторические формы URL (
jc.id.lv/dicechess-play-apiи стараяrabestro.github.io/...). Сторонних авторов ботов на момент решения нет, поэтому сплошной слой редиректов не требовался — хватило свипа плюс best-effort редиректы для поисковиков. - Ограничение публичности: GitHub Pages не имеет приватного режима, поэтому контрибьюторский сайт документирует только то, что и так выводится из публичного репозитория — никакой топологии хостов, значений переменных окружения, эксплуатационных деталей. Это записано и в AGENTS.md, и на самом сайте.
Альтернативы (отклонены). Оставить всё одним сайтом на Pages — аудитории продолжают конкурировать за навигацию; вопрос «куда класть схему БД» остаётся без ответа. Оба сайта на выделенных поддоменах — лишний домен ради внутренней аудитории, которая приходит из README, и разрыв с экосистемным паттерном без выгоды. Контрибьюторские доки в эту вики — правильная аудитория, но неправильный язык (вики русская, репозиторий англоязычный) и приватность: контрибьютор снаружи их не увидит. Cloudflare Pages вместо Worker — Pages в режиме поддержки, для новых проектов Cloudflare рекомендует Workers static assets.