site: cut docs version 0.7 and serve the in-progress docs as "dev" - #121
Conversation
The site has served one unversioned set of docs. This captures the current set as v0.7 and makes the in-progress docs a separate "dev" version, so the team can change docs/ in rossoctl/rossoctl and see the result on the public site without that work reaching readers who need the released documentation. Routes after this change: /docs/* v0.7 (latest) a frozen snapshot in versioned_docs/ /docs/dev/* dev synced from rossoctl/rossoctl:docs/ on each build What this adds: - versioned_docs/version-0.7/ and versioned_sidebars/version-0.7-sidebars.json, from `docusaurus docs:version 0.7` against the docs that main serves today. - versions.json. - A version map in docusaurus.config.ts, derived from versions.json the way llm-d/llm-d.github.io derives it. Cutting the next release therefore needs only the snapshot plus that file, and no version is hard-coded in the config. - The docsVersionDropdown navbar item, which replaces the placeholder dropdown that was commented out while the docs were unpublished. The snapshot holds the 20 pages that the site publishes, and the assets that those pages reference. `docusaurus docs:version` copies the whole folder, which would have frozen 124 files of internal notes — plans, research, retrospectives, QA matrices and developer guides — into this repo permanently. Those files are excluded from the build already, by the config or by a `draft: true` marker, so they add nothing to the snapshot. Verified against the live site: the 27 routes that v0.7 generates are identical to the 27 routes in the sitemap of www.rossoctl.dev. The version cut therefore changes no page that a reader sees today; it only moves the in-progress docs to /docs/dev/. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
✅ Deploy Preview for animated-crumble-fb8862 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
esnible
left a comment
esnible
left a comment
There was a problem hiding this comment.
The central claim is the one worth checking independently, and it holds. I fetched both sitemaps and compared path by path rather than trusting the counts:
live www.rossoctl.dev /docs/* routes: 27
deploy-preview-121 /docs/* routes (non-dev): 27
diff: IDENTICAL
deploy-preview-121 /docs/dev/* routes (new): 27
So the version cut moves no page a reader can reach today; it only adds /docs/dev/*. That is exactly what the PR asserts.
Other claims verified:
| Claim | Verified |
|---|---|
docs/ not committed; dev tracks rossoctl/rossoctl |
/docs is gitignored (.gitignore:11) and synced by scripts/sync-docs.sh; netlify.toml build is npm run sync-docs && npm run build |
| Pruned snapshot keeps every referenced asset | Extracted all 12 asset references from the snapshot markdown and cross-checked against the 18 committed assets — nothing missing |
| Cutting v0.8 needs no config edit | Simulated the version map with ["0.8","0.7"]: v0.8 to /docs/* labelled "v0.8 (latest)", v0.7 to /docs/0.7/*, dev unchanged; dropdown order ["0.8","0.7","current"] is correct |
| No version hard-coded in config | LATEST_VERSION derives from versions.json[0]; the fs.existsSync fallback keeps a pre-first-cut repo building — which is the state main is in right now |
The pruning rationale is convincing: freezing 124 files of internal working notes into this repo once per release would be a real cost, and the route comparison confirms nothing needed was dropped.
One note beyond the diff — onBrokenLinks: 'warn' (config line 50, outside this PR's hunks so I could not anchor a comment there) means a versioned snapshot can ship broken internal links without failing the build. The v0.7 snapshot's links all resolve today, but every future cut copies whatever link rot exists at that moment and freezes it, and a frozen version is the one place nobody will notice later. Worth considering 'throw', or a link-check step, before the next cut.
The merge-order reasoning is sound and worth preserving somewhere more durable than a PR body: "v0.7 has to be snapshotted from the docs as they are now, because after #2530 the old documentation is unrecoverable from the site" is a genuinely one-way door.
Author: Ibrahim2595 (MEMBER — maintainer)
Areas reviewed: Docs (versioned snapshot), TypeScript/site config, JSON
Agent/IDE config (.claude/.vscode): none
Commits: 1 commit, all signed-off: yes
CI status: passing (DCO, add-to-project, Netlify deploy preview built)
Assisted-By: Claude Code
| v, | ||
| { | ||
| label: v === LATEST_VERSION ? `v${v} (latest)` : `v${v}`, | ||
| path: v === LATEST_VERSION ? '' : v, |
There was a problem hiding this comment.
suggestion (for the v0.8 timeline, not this PR) — This line is the mechanism that relocates a version when a newer one is cut: path: '' for the latest, path: v for everything older. Correct, and the right default.
Worth planning for the consequence now rather than discovering it then. When v0.8 is cut, today's 27 URLs (/docs/getting-started/install, etc.) start serving v0.8 content, and the v0.7 content moves to /docs/0.7/getting-started/install. External links, bookmarks, and search results pointing at /docs/* will silently retarget to newer content rather than 404 — usually fine, occasionally not (a link shared in an issue thread as "how to install on 0.7" quietly becomes about 0.8).
If you want those to land on the version they were written against, that needs @docusaurus/plugin-client-redirects configured at v0.8 time. Nothing to change here; just much cheaper to decide before the cut than to retrofit after.
github-project-automation
Bot
moved this from New/ToDo
to Done
in Rossoctl Issue Prioritization
3 participants
What & why
The site serves one unversioned set of docs. This captures the current set as v0.7 and makes the in-progress docs a separate dev version.
That separation is what lets the team edit
docs/inrossoctl/rossoctland see the result on the public site immediately, without that work reaching a reader who needs the released documentation./docs/*versioned_docs/version-0.7//docs/dev/*rossoctl/rossoctl:docs/on every buildVerified against the live site
This is the check that matters, because a version cut must not change what a reader sees today.
The 27 routes that v0.7 generates are identical to the 27 routes in the sitemap of www.rossoctl.dev. Not equal in count — identical, compared path by path.
So this PR moves no page that a reader can reach today. It only adds
/docs/dev/*.What it adds
versioned_docs/version-0.7/andversioned_sidebars/version-0.7-sidebars.json, fromdocusaurus docs:version 0.7run against the docs thatmainserves right now.versions.json.docusaurus.config.ts, derived fromversions.jsonthe way llm-d/llm-d.github.io derives it. Cutting the next release then needs only the snapshot plus that file — no version is hard-coded in the config, and nobody has to remember to edit it.docsVersionDropdownnavbar item. It replaces the placeholder dropdown that was commented out while the docs were unpublished.The dropdown lists released versions newest-first, then
dev. The newest release is labelled v0.7 (latest) and carries a version badge;devcarries an unreleased banner.The snapshot is pruned, deliberately
docusaurus docs:versioncopies the wholedocs/folder. Run as-is it produced 169 files, of which 20 publish.The other 124 are internal notes — plans, research, retrospectives, QA matrices, developer guides — already excluded from the build by the config or by a
draft: truemarker. Committing them would freeze the team's working notes into this repo permanently, once per release, and they would contribute nothing to the rendered version.The snapshot therefore holds:
_category_.jsonfiles,identity-guide.mdlinks to).44 files, 1.4 MB. The route comparison above confirms nothing needed was removed.
Merge order
This PR is first in a series of three. Each one is safe to merge on its own, in this order:
.github/docs/*, dev at/docs/dev/*. dev shows today's docs..githubrossoctldevstarts showing them.This PR must come first for one reason: v0.7 has to be snapshotted from the docs as they are now. After #2530 merges, the same command would capture the new structure and the old documentation would be unrecoverable from the site.
#120 is stacked on this branch, so its diff shows only its own changes. GitHub will retarget it to
mainwhen this merges.After this
Nothing else is needed to make
devlive. Once #2530 merges,/docs/dev/*shows the new documentation, and a change todocs/inrossoctl/rossoctlappears on the site on the next build.When v0.8 is ready, cutting it is two commands and one commit:
v0.8 then becomes
(latest)at/docs/*, v0.7 moves to/docs/0.7/*, anddevstays at/docs/dev/*. The config needs no edit. Prune the new snapshot the same way, unlessdocs/is clean by then — #2530 moves the internal notes underdocs/_internal/, and #120 makessync-docs.shexclude that directory, which removes the need to prune at all.Not in this PR
/docs/*URL keeps working, because v0.7 keeps the bare/docs/base path. Redirects only become necessary when #2530 changes the paths insidedev, and then only for anyone who bookmarked adevURL. Worth a follow-up with@docusaurus/plugin-client-redirects.Acceptance tier
Checklist
Co-Authored-Bytrailer)npx tsc --noEmitpassesdocusaurus buildsucceeds with zero broken links and zero warningsAssisted-By: Claude Code