mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-31 04:45:23 +08:00
9b3bb30445
The migrated workflows required LANGBOT_WIKI_PUSH_TOKEN, which only exists in the langbot-docs repository. The existing RELEASE_UPLOAD_GITHUB_TOKEN was verified to authenticate as the owner with repo scope plus push/admin on LangBot, langbot-docs, langbot-landing-page and the production fork, and it can push the Wiki, so publication now falls back to it when the dedicated secret is absent. Also retarget the cutover notes at the master branch. Co-Authored-By: Mika (Multica) <[email protected]> Co-authored-by: multica-agent <[email protected]>
70 lines
4.3 KiB
Markdown
70 lines
4.3 KiB
Markdown
# Documentation subtree and publication
|
|
|
|
Public docs live in `LangBot/docs/`. The former internal `docs/` directory is
|
|
`dev-docs/` (27 top-level entries, 87 tracked files at migration). Do not merge
|
|
this migration using GitHub squash or rebase: use a merge commit to retain the
|
|
subtree parent and original signed commits. Imported history is reachable through
|
|
the subtree merge's second parent. Use `git log <imported-docs-sha> -- <file>`
|
|
(with the original path relative to the docs repository) to see original authors.
|
|
A path-limited `git log docs/` or `--follow` does not reliably traverse the
|
|
unrelated-history import. The imported commit is
|
|
`51dddcb3f891d60bc38645e88b2dbd515344da81` (888 commits, including 452 signed
|
|
commit objects, all retained without rewriting).
|
|
|
|
## Local checks
|
|
|
|
With Node.js 24, run `npm ci`, `npm run typecheck`, `npm test`, and `npm run build`
|
|
inside `docs/`. Output is `docs/dist/`. The site remains mounted at `/docs/` with
|
|
canonical URL `https://langbot.app/docs`.
|
|
|
|
## Cutover after the PR is reviewed and merged
|
|
|
|
1. Pause the legacy `sync-blog-articles.yml` workflow in `langbot-app/langbot-docs`
|
|
and let any running writer finish. Freeze direct commits to that repository.
|
|
Pause its legacy Wiki and landing sync workflows too, avoiding duplicate
|
|
publishers while switching ownership. Do not push disabling commits directly
|
|
to the mirror.
|
|
2. Fetch mirror `main` and confirm it is an ancestor of the new subtree split.
|
|
If it advanced since import, integrate it with an **unsquashed**
|
|
`git subtree pull --prefix=docs <mirror-url> main` through another reviewed PR
|
|
before cutover; reapply the inert mirror workflow files if necessary. Never
|
|
force-push or rewrite the mirror history.
|
|
3. The publication jobs read `LANGBOT_WIKI_PUSH_TOKEN` and fall back to the
|
|
existing `RELEASE_UPLOAD_GITHUB_TOKEN` when that secret is absent. The fallback
|
|
was verified on a scratch branch: it authenticates as the repository owner
|
|
with `repo` scope and push+admin on `LangBot`, `langbot-docs`,
|
|
`langbot-landing-page` and the production fork, and it can clone and push the
|
|
Wiki. It does not carry the `workflow` scope, so it cannot push changes to
|
|
`.github/workflows/**` in the mirror; the split only rewrites `docs/**`
|
|
content, so this is fine unless a future change edits the inert mirror stubs.
|
|
Adding a dedicated `LANGBOT_WIKI_PUSH_TOKEN` with the same access keeps the
|
|
blast radius of the fallback credential out of the docs pipeline. Do not
|
|
weaken branch protection to accommodate this migration.
|
|
4. Set LangBot repository variable `DOCS_MIRROR_ENABLED=true`. Dispatch
|
|
`sync-landing-submodule.yml` on master. It fetches full master history, runs
|
|
`git subtree split --prefix=docs`, verifies the current mirror head is an
|
|
ancestor, pushes without force, then advances only landing's `docs` gitlink.
|
|
The first split replaces legacy mirror workflows with inert manual stubs.
|
|
5. Dispatch `sync-github-wiki.yml` and `sync-blog-articles.yml` in LangBot.
|
|
The blog job now commits only docs article paths to LangBot master using the
|
|
dedicated token, so its push triggers the mirror and Wiki workflows.
|
|
6. Confirm the `docs` gitlink in `langbot-app/langbot-landing-page`, then confirm
|
|
production fork `RockChinQ/LangBot-LandingPage-Vue` matches upstream. This is
|
|
the actual fork in the existing sync script (not the similarly named fork
|
|
mentioned in the original migration proposal). Observe Cloudflare Pages
|
|
deployment and check `https://langbot.app/docs/`, localized pages, assets,
|
|
sitemap and canonical URLs. Verify Wiki pages after publication.
|
|
|
|
The four root workflows own publication and validation. Nested workflow stubs
|
|
are intentionally inert when split into the mirror. No direct writes should be
|
|
made to the mirror after cutover; all edits belong in LangBot `docs/`.
|
|
|
|
`docs/context7.json` continues to identify `langbot-app/langbot-docs` because that
|
|
repository remains available with the same tree layout and original history.
|
|
Verify Context7 ingestion after the first mirror update; no library re-registration
|
|
is needed merely to relocate the authoring source.
|
|
|
|
Disable `DOCS_MIRROR_ENABLED` to pause publishers if cutover fails. A failed
|
|
mirror ancestry check must be investigated and reconciled, never bypassed by a
|
|
force push. Do not restore direct mirror writers while LangBot is authoritative.
|