From e1693554982d302d1ee7fb380379f97637c33df7 Mon Sep 17 00:00:00 2001 From: vitya Date: Thu, 27 Aug 2026 09:44:02 +0300 Subject: [PATCH] =?UTF-8?q?docs(runbook):=20sched-publish-runbook=20(dev?= =?UTF-8?q?=E2=86=92pub,=20CI,=20Pages)=20+=20=D0=B8=D0=BD=D0=B4=D0=B5?= =?UTF-8?q?=D0=BA=D1=81;=20Docus=20Pages-=D0=B3=D1=80=D0=B0=D0=B1=D0=BB?= =?UTF-8?q?=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .wiki/concepts/runbooks-index.md | 6 ++ .wiki/concepts/sched-publish-runbook.md | 93 +++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 .wiki/concepts/sched-publish-runbook.md diff --git a/.wiki/concepts/runbooks-index.md b/.wiki/concepts/runbooks-index.md index 2bab1dc..f6bcd2c 100644 --- a/.wiki/concepts/runbooks-index.md +++ b/.wiki/concepts/runbooks-index.md @@ -35,6 +35,12 @@ updated: 2026-08-26 | oCIS / owncloud | [`ocis-on-vds-deploy-recipe.md`](ocis-on-vds-deploy-recipe.md) | deploy recipe + gotchas | | Локальный стенд sched-pipelines (sched + воркеры @apilki, мок-тест) | [`sched-pipelines-local-stack-runbook.md`](sched-pipelines-local-stack-runbook.md) | команды стенда, таймаут-сценарий (deadline-stop), gotchas 1-7 | +## Публикация на GitHub (OSS) + +| Проект / операция | Ранбук | Что покрывает | +|---|---|---| +| sched → GitHub (dev=Gitea, pub=github.com/schedjs/sched) | [`sched-publish-runbook.md`](sched-publish-runbook.md) | топология dev/pub, синк курируемой копии, выбеливание, CI (unit+Pages), verify, rollback, gotchas (baseURL/ipx/favicon/logo.svg/yarn.lock) | + ## Инфраструктурные ранбуки | Операция | Ранбук | Что покрывает | diff --git a/.wiki/concepts/sched-publish-runbook.md b/.wiki/concepts/sched-publish-runbook.md new file mode 100644 index 0000000..1037398 --- /dev/null +++ b/.wiki/concepts/sched-publish-runbook.md @@ -0,0 +1,93 @@ +--- +title: sched — публикация на GitHub (private-dev-public-publish, CI, Pages, синк dev→pub) +type: concept +tags: [sched, runbook, publish, github, pages, private-dev-public-publish, docus, ci] +related: [concepts/runbooks-index.md, concepts/docus-github-pages-pitfalls.md] +updated: 2026-08-27 +--- + +# sched → GitHub: публикация и синк (runbook) + +> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.** +> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять. +> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. +> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют. + +Публикация **sched** (шедулер, OSS, MIT) на GitHub по паттерну +private-dev-public-publish: разработка в приватном Gitea, наружу — курируемая +копия. Первый паблиш — 2026-08-27 (task:1149, по «го» vitya). + +## Топология + +| Роль | Папка | Origin | Мета | +|---|---|---|---| +| dev | `~/projects/sched` | `git.kzntsv.site/victor/sched` (Gitea) | `.wiki/.tasks/.agents` внутри | +| pub | `~/projects/sched-upstream` | `github.com/schedjs/sched` (main) | нет | + +## Артефакты + +- **Репо pub:** `schedjs/sched` (PUBLIC, MIT, 12 topics: cron/scheduler/job-queue/task-scheduler/background-jobs/self-hosted/nodejs/typescript/queue/devtools/mcp/docker; description+homepage `https://schedjs.github.io/sched`). +- **Сайт доков:** `https://schedjs.github.io/sched/` (Pages, workflow `ci.yml` → docs job; llms.txt/llms-full.txt). +- **CI:** `.github/workflows/ci.yml` — test (unit, без БД) + docs (Pages). Конфиг юнит-сьюта: `vitest.ci.config.ts`. +- **Доки:** `docs/` (Docus 5.12.3 на Nuxt), dist = `docs/dist` (трекается, Pages-сборка). +- **Storage-тесты с БД:** локально (docker: mongo 27017, pg 5433 `postgres:test`, mysql 3308 `root:test`, mariadb 3307 `root:test`). + +## Синк dev → pub (курируемая копия) + +1. **Список файлов:** `git -C ~/projects/sched ls-files` минус исключения: + `^\.wiki/|^\.tasks/|^\.agents/|^AGENTS\.md$|^CLAUDE\.md$|^branding/pora-|^pngtree-|^327274997_|^cat-clock-`. + Untracked в dev (canva/istock/logo.ai/logo.png/logo.svg/черновики) НЕ копируются. +2. **Копировать** в `~/projects/sched-upstream` (mkdir -p + cp по списку). +3. **Выбелить** (dev-приватное → публичное), файлы в pub-копии: + - `.yarnrc.yml` → `npmRegistryServer: "https://registry.npmjs.org"`, без токена; + - `docs/nuxt.config.ts` + `docs/modules/sched-links.ts` → дефолты `github.com/schedjs/sched`, `registry.npmjs.org`, `ghcr.io/schedjs` (env-оверрайд сохранён); + - `apps/daemon/Dockerfile` → секрет `id=npm_token` (не verdaccio_token), комменты; + - `docker-compose.dev.yml` → убрать NPM_REGISTRY/NPM_TOKEN (публичный npm); + - `CHANGELOG.md` → «→ npm» вместо verdaccio, docker-образ без registry.kzntsv; + - `scripts/publish-check.mjs` + `publish-check.test.mjs` → `ghcr.io/schedjs/sched-daemon`; + - `examples/*/generate.ps1`, README, test → убрать «verdaccio subpath export». +4. **dist:** `rm -rf docs/dist && cp -r dev/docs/dist` + скраб остатков `git.kzntsv` (в т.ч. JSON-экранированных `\u002F`). `docs/dist/logo.svg` НЕ коммитить (user: svg не едет; источник в корне dev untracked). +5. **Проверка:** `grep -rnE 'git\.kzntsv|verdaccio|vds\.kzntsv|registry\.kzntsv|VERDACCIO'` → 0; мета → 0; один чистый коммит + push main. + +## CI (workflow ci.yml) + +- **test (unit):** checkout → setup-node 24 → corepack enable → `yarn install --immutable` → `yarn workspaces foreach --all -pt --exclude docs run build` → `yarn tsc --noEmit` → `yarn vitest run --config vitest.ci.config.ts` (исключает `packages/storage-*/test/**` — им нужны живые БД). +- **docs:** на push в main: install → `yarn workspace docs build` → upload-pages-artifact (docs/dist) → deploy-pages. Pages включён (`gh api repos/schedjs/sched/pages -X POST -f build_type=workflow`). +- **Ручной запуск:** `workflow_dispatch`. + +## Verify (после синка/деплоя) + +- `https://schedjs.github.io/sched/` → meta-refresh на `/sched/docs/introduction` (200), CSS (`/sched/_nuxt/…`), favicon (`/sched/favicon.ico` 200), лого (full URL `https://schedjs.github.io/sched/logo.png` 200), llms.txt 200. +- Футер: 1 иконка GitHub (не 2). +- `gh run list` зелёный; `gh repo view` topics/description. + +## Rollback + +- **Репо:** содержимое pub = курируемая копия; откат = revert коммита pub (история чистая). +- **Pages:** перезапуск предыдущего успешного deploy-pages (Pages → последний деплой) или push реверта. +- **CI-конфиг:** фиксы в dev → синк → push. + +## Gotchas + +1. **`app.baseURL: '/sched/'`** обязателен (Pages-subpath), но Docus игнорирует его для двух ссылок: index meta-refresh (`url=/docs/introduction`) и favicon (`href="/favicon.ico"`) → пост-фикс в `scripts/docs-dist.mjs` (запускается после generate; срабатывает и в CI). +2. **NuxtImg двойная база лого:** header logo `'/logo.png'` → `/_ipx/_/sched/logo.png` (404, _ipx не генерится статически). Фикс: полный URL в `header.logo.light/dark` (`https://schedjs.github.io/sched/logo.png`) — ipx пропускает внешние. +3. **Футер: 2 GitHub-иконки** — Docus сам подставляет github из git-remote + explicit `socials.github`. Убрать explicit (pub remote = github.com → 1 иконка). В dev-сборке (Gitea remote) футер покажет Gitea-ссылку — при синке dist скрабить. +4. **`docs/dist/logo.svg` регенерируется** из `docs/public/logo.svg` при каждой сборке (2026-08-27: вынесен в корень dev, untracked) — не коммитить в pub. +5. **CI: dist нет в git** (gitignored) → `build` до `tsc` (cross-package types через dist). +6. **corepack vs setup-node `cache: yarn`** — кэш дёргает системный yarn 1 → падает на packageManager. Кэш не использовать. +7. **mariadb:11 первый старт** дольше health-окна GH Actions (76s+) — healthcheck не вешать; ждать готовности node-скриптом на драйверах (pg/mysql2/mongodb) или юнит-only CI. +8. **yarn.lock** в Berry-формате без URL; может быть устаревшим (nodemailer) — `yarn install` в dev, синк. До npm-паблиша `@sched/mcp@npm:^0.4.0` резолвится в workspace (transparent) — install с npmjs работает. +9. **Процесс-раннер в тестах:** спавнит с чистым env (без PATH) → `['node', …]` падает ENOENT на Linux CI → в real-spawn тестах `process.execPath`. + +## Осталось (на 2026-08-27) + +- npm-паблиш `@sched/*` (первым core 0.53.0 → npmjs; до него публичный yarn install работает, но `@sched/core` на npmjs нет — консьюмеры не поставят); +- task:720 `pkg-repo-metadata` (repository/homepage/bugs/author в манифесты); +- Context7-сабмит (Pages живы); README npm-бейдж после паблиша; +- schedjs.com — фаза SaaS (CNAME → Pages), обновить llms.domain и header.logo URL. + +## Связи + +- `concepts/runbooks-index.md` — индекс (строка sched). +- Shared wiki (mappa): Docus-подводные камни — `docus-github-pages-pitfalls` (тема создана из этого опыта). +- Скил `private-dev-public-publish` (глобальный) — общая топология двух репо.