Skip to content

Commit b959ba6

Browse files
Copilotvicperdana
Copilot
and
vicperdana
committed
docs: add monorepo migration guide
Co-authored-by: vicperdana <7114832+vicperdana@users.noreply.github.com>
1 parent 102e1fd commit b959ba6

1 file changed

Lines changed: 181 additions & 0 deletions

File tree

‎MONOREPO_MIGRATION.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Monorepo Migration Guide
2+
3+
## Overview
4+
5+
This repository has been restructured to serve as a monorepo for the complete PSDocs ecosystem, consolidating:
6+
- **PSDocs** (core engine from microsoft/PSDocs)
7+
- **PSDocs.Azure** (existing content, now in packages/psdocs-azure/)
8+
- **VS Code Extension** (from microsoft/PSDocs-vscode)
9+
10+
## Repository Structure
11+
12+
```
13+
packages/
14+
├── psdocs/ # PSDocs engine (to be added via git subtree)
15+
├── psdocs-azure/ # Azure IaC documentation generator (existing content)
16+
└── vscode-extension/ # VS Code extension (to be added via git subtree)
17+
18+
docs/
19+
├── psdocs/ # PSDocs engine docs (to be added via git subtree)
20+
├── psdocs-azure/ # PSDocs.Azure docs (existing content)
21+
└── vscode/ # VS Code extension docs (to be added via git subtree)
22+
23+
build/
24+
└── common.ps1 # Shared build utilities
25+
26+
.github/workflows/
27+
├── ci.yml # Main CI workflow with path-based filtering
28+
├── release-psdocs.yml # Release workflow for PSDocs engine
29+
├── release-psdocs-azure.yml # Release workflow for PSDocs.Azure
30+
└── release-vscode.yml # Release workflow for VS Code extension
31+
```
32+
33+
## Post-Merge Steps
34+
35+
After this PR is merged, the following git subtree commands need to be run locally to add the other repositories with their full history:
36+
37+
### 1. Clone the repository
38+
39+
```bash
40+
git clone https://github.com/Azure/PSDocs.Azure.git
41+
cd PSDocs.Azure
42+
```
43+
44+
### 2. Add PSDocs engine
45+
46+
```bash
47+
git subtree add --prefix=packages/psdocs https://github.com/microsoft/PSDocs.git main --squash -m "feat: add PSDocs engine from microsoft/PSDocs"
48+
```
49+
50+
### 3. Add VS Code extension
51+
52+
```bash
53+
git subtree add --prefix=packages/vscode-extension https://github.com/microsoft/PSDocs-vscode.git main --squash -m "feat: add VS Code extension from microsoft/PSDocs-vscode"
54+
```
55+
56+
### 4. Push changes
57+
58+
```bash
59+
git push origin main
60+
```
61+
62+
## Building the Monorepo
63+
64+
### Build all packages
65+
66+
```powershell
67+
./build.ps1 -Build
68+
```
69+
70+
### Build specific package
71+
72+
```powershell
73+
# Build PSDocs engine only
74+
./build.ps1 -Package psdocs -Build
75+
76+
# Build PSDocs.Azure (also builds PSDocs if needed)
77+
./build.ps1 -Package psdocs-azure -Build -Test
78+
79+
# Build VS Code extension
80+
./build.ps1 -Package vscode -Build
81+
```
82+
83+
### Clean build artifacts
84+
85+
```powershell
86+
./build.ps1 -Clean
87+
```
88+
89+
## CI/CD Workflows
90+
91+
### CI Workflow
92+
93+
The CI workflow (`.github/workflows/ci.yml`) uses path-based filtering to only build packages that have changed:
94+
95+
- Changes to `packages/psdocs/**` trigger the PSDocs build
96+
- Changes to `packages/psdocs-azure/**` trigger the PSDocs.Azure build (which depends on PSDocs)
97+
- Changes to `packages/vscode-extension/**` trigger the VS Code extension build
98+
99+
### Release Workflows
100+
101+
Each component has its own release workflow triggered by version-tagged commits:
102+
103+
- **PSDocs**: Tag format `psdocs-v{version}` (e.g., `psdocs-v0.10.0`)
104+
- **PSDocs.Azure**: Tag format `psdocs-azure-v{version}` (e.g., `psdocs-azure-v0.4.0`)
105+
- **VS Code Extension**: Tag format `vscode-v{version}` (e.g., `vscode-v1.1.0`)
106+
107+
## Versioning Strategy
108+
109+
Each component is versioned independently:
110+
111+
- Each package maintains its own CHANGELOG.md
112+
- Version tags are prefixed to identify the component
113+
- Releases are published separately to their respective platforms:
114+
- PSDocs and PSDocs.Azure → PowerShell Gallery
115+
- VS Code Extension → Visual Studio Marketplace
116+
117+
## Development Workflow
118+
119+
### Working on PSDocs.Azure
120+
121+
1. Make changes in `packages/psdocs-azure/`
122+
2. Test locally: `./build.ps1 -Package psdocs-azure -Build -Test`
123+
3. Commit and push - CI will automatically build and test
124+
4. Tag for release: `git tag psdocs-azure-v{version}`
125+
126+
### Working on PSDocs Engine
127+
128+
1. Make changes in `packages/psdocs/`
129+
2. Test locally: `./build.ps1 -Package psdocs -Build -Test`
130+
3. Test PSDocs.Azure still works: `./build.ps1 -Package psdocs-azure -Test`
131+
4. Tag for release: `git tag psdocs-v{version}`
132+
133+
### Working on VS Code Extension
134+
135+
1. Make changes in `packages/vscode-extension/`
136+
2. Test locally: `./build.ps1 -Package vscode -Build`
137+
3. Tag for release: `git tag vscode-v{version}`
138+
139+
## Migration Notes
140+
141+
### Path Updates
142+
143+
All documentation and template paths have been updated in the main README:
144+
- `docs/` → `docs/psdocs-azure/`
145+
- `templates/` → `packages/psdocs-azure/templates/`
146+
- `examples/` → `packages/psdocs-azure/examples/`
147+
148+
### Build Artifacts
149+
150+
Build artifacts are now generated in:
151+
- `packages/psdocs/out/` - PSDocs engine
152+
- `packages/psdocs-azure/out/` - PSDocs.Azure module
153+
- `packages/vscode-extension/*.vsix` - VS Code extension package
154+
155+
### Gitignore Updates
156+
157+
The `.gitignore` has been updated to exclude:
158+
- `packages/*/out/` - Build artifacts from all packages
159+
- `packages/*/node_modules/` - Node.js dependencies
160+
- `packages/*/*.vsix` - VS Code extension packages
161+
- `*.nupkg` - NuGet packages
162+
163+
## Future Subtree Updates
164+
165+
To pull updates from the source repositories later:
166+
167+
```bash
168+
# Update PSDocs engine
169+
git subtree pull --prefix=packages/psdocs https://github.com/microsoft/PSDocs.git main --squash
170+
171+
# Update VS Code extension
172+
git subtree pull --prefix=packages/vscode-extension https://github.com/microsoft/PSDocs-vscode.git main --squash
173+
```
174+
175+
## Questions?
176+
177+
For questions about:
178+
- PSDocs engine: See `packages/psdocs/README.md` (after subtree merge)
179+
- PSDocs.Azure: See `packages/psdocs-azure/src/PSDocs.Azure/README.md`
180+
- VS Code extension: See `packages/vscode-extension/README.md` (after subtree merge)
181+
- Monorepo structure: File an issue on this repository

0 commit comments

Comments
 (0)