Skip to content

Commit 9ac66b7

Browse files
author
Marvin Zhang
committed
feat: add README for migrating docs-site to separate repository as submodule
1 parent 11ca0d6 commit 9ac66b7

File tree

1 file changed

+145
-0
lines changed
  • specs/092-docs-site-submodule-migration

1 file changed

+145
-0
lines changed

‎specs/092-docs-site-submodule-migration/README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
status: planned
3+
created: '2025-11-17'
4+
tags:
5+
- infrastructure
6+
- docs
7+
- monorepo
8+
priority: high
9+
created_at: '2025-11-17T04:54:37.212Z'
10+
updated_at: '2025-11-17T04:55:16.581Z'
11+
---
12+
13+
# Migrate docs-site to separate repository as submodule
14+
15+
> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-17 · **Tags**: infrastructure, docs, monorepo
16+
17+
**Project**: lean-spec
18+
**Team**: Core Development
19+
20+
## Overview
21+
22+
The `docs-site/` directory is currently nested in the lean-spec monorepo. This causes unnecessary Vercel deployments whenever any part of the monorepo changes, even when documentation hasn't been modified.
23+
24+
Migrating docs-site to a separate repository with git submodule integration will:
25+
- Decouple docs deployment from CLI/core development
26+
- Reduce unnecessary CI/CD runs and Vercel builds
27+
- Enable independent versioning and release cycles for documentation
28+
- Maintain single source of truth while allowing separate workflows
29+
30+
## Design
31+
32+
### Repository Structure
33+
34+
**New repository**: `codervisor/lean-spec-docs`
35+
- Standalone Docusaurus project
36+
- Independent deployment to Vercel
37+
- Own package.json, dependencies, CI/CD
38+
39+
**Main repository**: `codervisor/lean-spec`
40+
- Add `docs-site/` as git submodule pointing to `lean-spec-docs`
41+
- Update build scripts to handle submodule
42+
- Update CONTRIBUTING.md with submodule workflow
43+
44+
### Migration Strategy
45+
46+
1. **Create new repository**
47+
- Create `codervisor/lean-spec-docs` on GitHub
48+
- Initialize with existing `docs-site/` content
49+
- Set up Vercel deployment for new repo
50+
- Configure build settings (same as current)
51+
52+
2. **Remove from monorepo**
53+
- Remove `docs-site/` directory from lean-spec
54+
- Update root `package.json` workspaces config
55+
- Update `turbo.json` to remove docs-site tasks
56+
- Remove docs-site from `pnpm-workspace.yaml`
57+
58+
3. **Add as submodule**
59+
- `git submodule add https://github.com/codervisor/lean-spec-docs.git docs-site`
60+
- Configure submodule to track `main` branch
61+
- Update `.gitmodules` with branch tracking
62+
63+
4. **Update workflows**
64+
- GitHub Actions: Skip docs builds unless docs changed
65+
- Update CONTRIBUTING.md with submodule commands
66+
- Add documentation for working with submodules
67+
68+
### Vercel Configuration
69+
70+
**Current setup**: Single Vercel project for entire monorepo
71+
**New setup**: Separate Vercel projects
72+
- `lean-spec` monorepo: Deploy only if CLI/core changes
73+
- `lean-spec-docs`: Deploy only on docs changes
74+
75+
### Developer Workflow
76+
77+
**Clone with submodule**:
78+
```bash
79+
git clone --recurse-submodules https://github.com/codervisor/lean-spec.git
80+
```
81+
82+
**Update docs**:
83+
```bash
84+
cd docs-site
85+
git checkout main
86+
git pull
87+
cd ..
88+
git add docs-site
89+
git commit -m "chore: update docs submodule"
90+
```
91+
92+
**Work on docs**:
93+
```bash
94+
cd docs-site
95+
# Make changes, commit to lean-spec-docs
96+
git push
97+
cd ..
98+
git add docs-site
99+
git commit -m "chore: update docs submodule pointer"
100+
```
101+
102+
## Plan
103+
104+
- [ ] Create `codervisor/lean-spec-docs` repository on GitHub
105+
- [ ] Copy `docs-site/` content to new repository
106+
- [ ] Set up Vercel deployment for new docs repo
107+
- [ ] Test docs build and deployment independently
108+
- [ ] Remove `docs-site/` from lean-spec monorepo
109+
- [ ] Update workspace configs (package.json, pnpm-workspace.yaml, turbo.json)
110+
- [ ] Add docs-site as git submodule
111+
- [ ] Update CONTRIBUTING.md with submodule workflow
112+
- [ ] Update GitHub Actions to skip docs builds
113+
- [ ] Test full workflow: clone, build, deploy
114+
- [ ] Document submodule best practices in README
115+
116+
## Test
117+
118+
- [ ] New docs repo builds successfully on Vercel
119+
- [ ] Docs deploy independently when pushed to lean-spec-docs
120+
- [ ] Main repo builds without docs-site directory
121+
- [ ] Submodule clone works: `git clone --recurse-submodules`
122+
- [ ] Submodule update works: `git submodule update --remote`
123+
- [ ] CI/CD skips docs builds when only CLI/core changes
124+
- [ ] Developers can work on docs independently
125+
126+
## Notes
127+
128+
### Alternatives Considered
129+
130+
**Keep in monorepo**: Simpler but causes unnecessary deployments and tight coupling
131+
132+
**Separate repo without submodule**: Loses visibility in main repo, harder to track docs version
133+
134+
**Monorepo with conditional Vercel deploys**: Possible but requires complex CI configuration, still coupled in git history
135+
136+
### Open Questions
137+
138+
- Should we keep docs versioned with CLI releases or independently?
139+
- Do we want to enforce docs updates as part of CLI PRs?
140+
- Should submodule track `main` or specific release tags?
141+
142+
### References
143+
144+
- Current Vercel config: `vercel.json`, `docs-site/vercel.json`
145+
- Git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules

0 commit comments

Comments
 (0)