PR Migration Verification: docs-site → lean-spec-docs

Status: ✅ Complete · Priority: High · Created: 2025-11-17 · Tags: migration, docs, verification

Project: lean-spec
Team: Core Development

Overview

Successfully migrated PRs #66-69 from the old lean-spec repository to the new lean-spec-docs repository using cherry-pick approach (Option 1). These PRs contained substantial documentation improvements that were created before the docs-site migration to a separate repository.

Problem: After migrating docs-site to lean-spec-docs repo, discovered 4 unmerged PRs (#66-69) with ~4,500+ lines of documentation improvements that needed to be migrated.

Solution: Used git cherry-pick approach to extract and apply docs-site changes from each PR to the new repository, preserving all work without losing any content.

Migration Summary

Total Changes

21 files changed: 4,032 insertions(+), 7 deletions(-)
4 PRs migrated: #66, #67, #68, #69
Branch created: migrate-prs-66-69 in lean-spec-docs repo
Branch pushed: Successfully pushed to origin

PR #66: Terminology Glossary (295 lines)

Spec: 088-core-concepts-terminology-only
Status: Complete
Commit: ae12682

Changes:

Created docs/guide/terminology.mdx with 16 essential SDD terms
Updated sidebar positions for all Core Concepts files (1→2, 2→3, 3→4, 4→5, 5→6, 4→7)
Added terminology as first item in Core Concepts sidebar
Added terminology note to first-principles.mdx
Added Quick Start tip to understanding.mdx
Added terminology links to getting-started.mdx and understanding.mdx

Files modified: 9 files

New: docs/guide/terminology.mdx
Updated: ai-agent-memory.mdx, context-engineering.mdx, first-principles.mdx, getting-started.mdx, limits-and-tradeoffs.mdx, philosophy.mdx, understanding.mdx, sidebars.ts

PR #67: Step-by-Step SDD Tutorials (1,676 lines)

Spec: 089-sdd-practical-tutorials
Status: Complete
Commit: 808a141

Changes:

Created 4 progressive tutorials:
- docs/tutorials/your-first-spec.mdx (326 lines)
- docs/tutorials/sdd-workflow-feature-development.mdx (369 lines)
- docs/tutorials/managing-multiple-specs.mdx (454 lines)
- docs/tutorials/working-with-teams.mdx (527 lines)
Added Tutorials section to sidebar (after Introduction, before Core Concepts)
Added Quick Start button on homepage linking to first tutorial
Changed existing Get Started button to secondary style

Files modified: 6 files

New: 4 tutorial files in docs/tutorials/
Updated: sidebars.ts, src/pages/index.tsx

PR #68: Dogfooding Case Studies (~2,500 lines)

Spec: 090-leanspec-sdd-case-studies
Status: Complete
Commit: d8c6955

Changes:

Created 5 case study pages:
- docs/case-studies/index.mdx (113 lines) - Overview
- docs/case-studies/simple-feature-token-validation.mdx (254 lines) - Spec 071
- docs/case-studies/complex-feature-web-sync.mdx (375 lines) - Spec 082
- docs/case-studies/refactoring-monorepo-core.mdx (580 lines) - Spec 067
- docs/case-studies/cross-team-official-launch.mdx (513 lines) - Spec 043
Added Case Studies section to sidebar (before roadmap/faq)
Added case studies CTA section on homepage
Chinese translations for homepage elements in i18n/zh-Hans/code.json

Files modified: 8 files

New: 5 case study files in docs/case-studies/
Updated: sidebars.ts, src/pages/index.tsx, i18n/zh-Hans/code.json

PR #69: Chinese Localization (149 lines)

Spec: 091-chinese-localization-strategy
Status: Complete (docs-site portion)
Commit: 3b059ef

Changes:

Created i18n/zh-Hans/TERMINOLOGY_GLOSSARY.md with standardized Chinese translations
Comprehensive glossary for consistent terminology across all translations
Includes core concepts, first principles, status/priority terms, CLI commands, etc.

Note: Web app i18n infrastructure (packages/web locales, hooks, components) from PR #69 applies to main lean-spec repo, not docs-site, so only the terminology glossary was migrated.

Files modified: 1 file

New: i18n/zh-Hans/TERMINOLOGY_GLOSSARY.md

Post-Migration QA Fix (ee70869, 2025-11-17)

After verification we found zh-Hans anchor references missing for the new terminology links. Commit ee70869 adds:

Explicit anchor IDs on guide/first-principles translation so cross-links resolve
Translated lean-spec tokens reference section to surface /reference/cli#lean-spec-tokens
FAQ link update to reuse the new anchor slug
pnpm build now passes without broken-anchor warnings for en + zh-Hans

This commit is part of the same migrate-prs-66-69 branch and must be included in the docs-site PR.

Design

Migration Approach

Method: Git cherry-pick with manual file extraction

Process:

Added old lean-spec repo as remote in docs-site submodule
Fetched PR branches from old repo
For each PR:
- Extracted files from specific commits using git show <commit>:<path>
- Applied changes manually to avoid path conflicts
- Updated references (sidebar positions, links)
- Tested build after each PR
- Committed with descriptive message and PR reference
Pushed all commits to new branch in lean-spec-docs repo

Why manual extraction vs direct cherry-pick?

Path differences: PR commits had docs-site/ prefix, new repo doesn't
Merge conflicts: PRs were based on different base branches
Selective migration: Some PRs had non-docs changes (specs/, packages/)
Build verification: Could test incrementally

Branch Structure

lean-spec-docs (new repo)
├── main (0f0522f)
└── migrate-prs-66-69 (3b059ef) ← Migration branch
    ├── ae12682 - PR #66: Terminology glossary
    ├── 808a141 - PR #67: Tutorials
    ├── d8c6955 - PR #68: Case studies
    └── 3b059ef - PR #69: Chinese glossary

lean-spec (old repo)
└── docs-site/ (submodule)
    └── pointing to lean-spec-docs @ migrate-prs-66-69

Plan

Test

Build Verification

Build succeeds with PR #66 changes (terminology)
Build succeeds with PR #67 changes (tutorials)
Build succeeds with PR #68 changes (case studies)
Build succeeds with PR #69 changes (Chinese glossary)
Final build succeeds with all changes
Both English and Chinese locales build successfully
pnpm build (2025-11-17) after ee70869 → no broken anchors; warning resolved by zh-Hans fixes

Content Verification

All 21 files present in migration branch
Terminology glossary accessible from sidebar
4 tutorials accessible from Tutorials section
5 case studies accessible from Case Studies section
Homepage Quick Start button links to first tutorial
Homepage case studies CTA section present
Chinese translations present in i18n files

Git Verification

5 commits on migrate-prs-66-69 branch (includes QA fix ee70869)
Each commit references source PR
Commit messages descriptive and detailed
Branch successfully pushed to origin
No merge conflicts

Next Steps for Verification Session

0. Update docs-site Submodule Pointer

cd /home/marvin/projects/codervisor/lean-spec
git add docs-site
git commit -m "chore: point docs-site to ee70869 (spec 095 QA fix)"

Verify:

Root repo references ee70869
Include this commit with any follow-up PR in main repo

1. Review Migration Branch

cd docs-site
git checkout migrate-prs-66-69
git log --oneline --stat

Verify:

4 commits present
Commit messages reference PRs
File changes match summary above

2. Test Documentation Build

npm run build
npm run serve

Verify:

Build completes without errors
Navigate to Terminology (/docs/guide/terminology)
Navigate to Tutorials section (/docs/tutorials/your-first-spec)
Navigate to Case Studies section (/docs/case-studies)
Check homepage Quick Start button
Check homepage case studies section
Test Chinese locale (zh-Hans)

3. Create Pull Request

# Visit: https://github.com/codervisor/lean-spec-docs/pull/new/migrate-prs-66-69

PR Description Template:

## Migrate PRs #66-69 from lean-spec to lean-spec-docs

Migrates documentation improvements from 4 unmerged PRs that were created before docs-site migration.

### Changes Summary
- **PR #66**: Terminology glossary (295 lines)
- **PR #67**: Step-by-step tutorials (1,676 lines)  
- **PR #68**: Dogfooding case studies (2,500 lines)
- **PR #69**: Chinese terminology glossary (149 lines)

**Total**: 21 files changed, 4,032 insertions(+), 7 deletions(-)

### Verification
- ✅ All builds pass (EN + zh-Hans) — confirmed via `pnpm build` on 2025-11-17 after `ee70869`
- ✅ No breaking changes
- ✅ All links functional
- ✅ Each PR tracked in separate commit

### Original PRs
- codervisor/lean-spec#66 (spec 088)
- codervisor/lean-spec#67 (spec 089)
- codervisor/lean-spec#68 (spec 090)
- codervisor/lean-spec#69 (spec 091)

Closes #[issue-number-if-exists]

4. After Merge: Update Main Repo

cd /home/marvin/projects/codervisor/lean-spec
git checkout main
git submodule update --remote docs-site
git add docs-site
git commit -m "chore: update docs-site submodule to include migrated PRs #66-69"
git push origin main

5. Close Old PRs in lean-spec Repo

For each PR #66, #67, #68, #69, add comment:

This PR has been successfully migrated to the new docs repository at:
https://github.com/codervisor/lean-spec-docs/pull/[new-pr-number]

All documentation changes from this PR are now tracked in lean-spec-docs.

Closing as the docs-site has been migrated to its own repository.

Then close each PR.

Notes

Migration Success Factors

Incremental approach: Migrated one PR at a time with testing
Build verification: Tested after each PR to catch issues early
Descriptive commits: Each commit explains what was migrated and references source PR
Manual extraction: Avoided complex merge conflicts by extracting files manually
Preserved content: Zero content loss, all 4,500+ lines migrated successfully

Challenges Encountered

Path differences: PRs had docs-site/ prefix, required manual path adjustment
Base branch differences: PRs based on different branches, some included/excluded prior changes
Web app vs docs-site: PR #69 had both web app and docs-site changes, needed separation

Technical Details

Remote added: git remote add old-repo https://github.com/codervisor/lean-spec.git
PR fetch pattern: git fetch old-repo pull/{N}/head:pr-{N}
File extraction: git show <commit>:<path> > <target>
Build tool: Docusaurus with i18n support
Languages: English (en), Chinese (zh-Hans)

Repository Links

Old repo: https://github.com/codervisor/lean-spec
New repo: https://github.com/codervisor/lean-spec-docs
Migration branch: https://github.com/codervisor/lean-spec-docs/tree/migrate-prs-66-69
Create PR: https://github.com/codervisor/lean-spec-docs/pull/new/migrate-prs-66-69