Migration playbook
Who this is for: Maintainers bringing in-scope material from legacy homes (wikis, other repositories, chat or meeting exports, ad-hoc docs) into this knowledge base under docs/.
What this page is: An ordered procedure so migrated content lands on the right path (default vs archive), matches the structure contract, keeps relative links valid, and updates navigation in the same change set as new or promoted default-path pages.
What this page is not: A catalog of legacy URLs, a mandate to migrate everything at once, or the full specification of optional “migrated vs net-new” labeling—that normative detail lives in the contribution guide under Corpus provenance (optional) (with origin in YAML front matter and the structure contract as the shape authority).
Before you start
Skim these—they are normative for how pages must read and where they belong:
- Structure contract — YAML front matter, heading ladder, link style, default vs archive in front matter.
- Page templates and topic-page.md — default scaffold for net-new topic files.
- CONTRIBUTING.md — scope, Archive (
docs/archive/), Starting from a template, Substantive documentation PRs / Reviewing new and revised doc pages, and API documentation and OpenAPI boundary (migrated pages must not become OpenAPI or path/method dumps). - Default path vs archive — policy summary for current default-path truth vs
docs/archive/for history and deliberation.
Default path vs archive (placement)
Every migration PR should decide explicitly:
| Destination | Use when |
|---|---|
Default path (docs/*.md outside archive/) | Material is current governed guidance readers and agents should treat as routine truth. |
docs/archive/ | Material is historical, superseded, or deliberative—see Archive (docs/archive/) for naming, audience: archive, and when to use the archive README and supersession patterns. |
If unsure, read Default path vs archive and the archive table in CONTRIBUTING.md before choosing a path.
NFR-SC1 — index and hub stay in sync
Do not add or promote a discoverable default-path topical page without updating docs/index.md (usually a new row under Curated pages) and any hub section that should list the topic—in the same pull request as the new or moved page. Same rule as Keeping this index current and Keeping the hub complete.
Migration phases (do in order)
1. Select the slice
- Define one coherent batch (one topic, one epic-sized chapter, or one superseded narrative) so the PR stays reviewable.
- Confirm the content is in scope for this corpus per What belongs here (in scope) and What belongs here vs elsewhere—defer per-app implementation detail and authoritative API contracts to the right repos and DevDoc.
2. Map to target paths and hub titles
- Choose filenames (
lowercase-hyphenated.md) and directory (defaultdocs/vsdocs/archive/...). - Align the page title and hub listing text with how Curated pages should describe the destination.
- If the material replaces older default-path guidance, plan Supersession on the default path and provenance per Provenance for substantive meaning changes.
3. Move or rewrite for the structure contract
- Net-new default-path topic pages: start from topic-page.md per Starting from a template.
- Fill or adjust YAML front matter to match YAML front matter; respect Provenance and ownership where
owner/last_updatedapply. - Trim spec-style API content; link out per API documentation and OpenAPI boundary.
4. Fix internal relative links
- After files move, update every intra-repo relative link (including links from other
docs/pages that pointed at old paths). - Prefer stable, descriptive link text—Markdown syntax.
5. Same PR — update docs/index.md and hubs
- Add or adjust Curated pages rows for each new default-path navigable page.
- Update any topic hub or index section that must mention the new destination.
- If you cannot ship the index update in the same PR, treat that as an exception: follow Keeping the hub complete (follow-up issue and no silent orphan pages).
Verify before merge
- From
docs/index.md, open each Curated pages link (including new rows)—confirm targets exist and render as intended (manual pass; automatedmarkdown-link-checkis optional Epic 7 tooling—do not add a Node toolchain here only for this playbook). - For playbook-only PRs: confirm new links to
docs/migration.mdand any CONTRIBUTING cross-links resolve. - For PRs that move real content: repeat the index smoke check and spot-check inbound links from touched pages.
References
| Topic | Where |
|---|---|
| Structure and front matter | Structure contract |
| Scaffolds | Page templates |
| Contribution rules, archive, substantive PRs, API boundary | CONTRIBUTING.md |
| Default vs archive policy | Default path vs archive |
| Archive browsing and classification | Archive README |
| Hub and curated list | Documentation hub |