docs(runbook): sched-publish-runbook (dev→pub, CI, Pages) + индекс; Docus Pages-грабли
This commit is contained in:
@@ -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) |
|
||||
|
||||
## Инфраструктурные ранбуки
|
||||
|
||||
| Операция | Ранбук | Что покрывает |
|
||||
|
||||
93
.wiki/concepts/sched-publish-runbook.md
Normal file
93
.wiki/concepts/sched-publish-runbook.md
Normal file
@@ -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` (глобальный) — общая топология двух репо.
|
||||
Reference in New Issue
Block a user