Skip to content

Commit 36aeba6

Browse files
CopilotCopilot
authored
Restructure repository as monorepo for PSDocs ecosystem consolidation (#407)
Transform PSDocs.Azure into a monorepo consolidating the complete PSDocs ecosystem: PSDocs core engine, PSDocs.Azure, and the VS Code extension. Repository structure: - packages/psdocs/ — PSDocs engine (git subtree from microsoft/PSDocs) - packages/psdocs-azure/ — Azure IaC documentation generator - packages/vscode-extension/ — VS Code extension (git subtree from microsoft/PSDocs-vscode) Build system: - Root build.ps1 orchestrator with per-package InvokeBuild scripts - Path-based CI filtering: only changed packages trigger builds - Independent versioning with prefixed tags (psdocs-v*, psdocs-azure-v*, vscode-v*) CI/CD workflows: - ci.yml: Main CI with cross-platform test matrix (linux, windows, macOS) - codeql.yml: CodeQL, PSRule, and DevSkim security analysis - vscode-ci.yml: VS Code extension CI migrated from Azure DevOps - release-*.yml: Per-package release workflows - All actions pinned to SHA hashes per org policy Documentation: - Consolidated flat docs/ structure for MkDocs site - Added MONOREPO_MIGRATION.md migration guide - Added 4 GitHub Copilot skills for development workflows Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vicperdana <7114832+vicperdana@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent b6a9e63 commit 36aeba6

343 files changed

Lines changed: 33505 additions & 41 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/copilot-instructions.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Copilot Instructions for PSDocs.Azure Monorepo
2+
3+
## Code Review Guidelines
4+
5+
When performing a code review, prioritize CI/CD correctness, build scripts, and monorepo structure changes.
6+
7+
### Focus review comments on:
8+
- `build.ps1` - Root build orchestrator
9+
- `build/common.ps1` - Shared build utilities
10+
- `.github/workflows/**` - CI/CD workflows
11+
- `.github/skills/**` - Copilot skills
12+
- `packages/psdocs-azure/**` - Core PSDocs.Azure module
13+
- `MONOREPO_MIGRATION.md` - Migration documentation
14+
15+
### Treat these paths as imported/vendored (git subtree). Do not leave review comments unless there is a critical security issue:
16+
- `packages/psdocs/**` - Imported from microsoft/PSDocs
17+
- `packages/vscode-extension/**` - Imported from microsoft/PSDocs-vscode (except `.github/workflows/` changes)
18+
19+
## Build System
20+
21+
This is a PowerShell-based monorepo using InvokeBuild:
22+
23+
```powershell
24+
# Build all packages
25+
./build.ps1 -Build
26+
27+
# Build specific package
28+
./build.ps1 -Package psdocs-azure -Build -Test
29+
```
30+
31+
## Versioning
32+
33+
Each component uses independent versioning with prefixed tags:
34+
- PSDocs: `psdocs-v{version}`
35+
- PSDocs.Azure: `psdocs-azure-v{version}`
36+
- VS Code Extension: `vscode-v{version}`
37+
38+
## CI/CD
39+
40+
Path-based filtering triggers builds only for changed packages:
41+
- `packages/psdocs/**` → PSDocs build
42+
- `packages/psdocs-azure/**` → PSDocs.Azure build
43+
- `packages/vscode-extension/**` → VS Code extension build

‎.github/skills/devops-build.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# DevOps & Build Expert Skill
2+
3+
You are an expert in **DevOps, CI/CD pipelines, and build systems** for the PSDocs ecosystem. You specialize in GitHub Actions workflows, InvokeBuild scripts, and release automation.
4+
5+
## Model
6+
7+
Use `claude-sonnet-4.5` for balanced speed and quality.
8+
9+
## Scope
10+
11+
This skill focuses on:
12+
- GitHub Actions workflow creation and maintenance
13+
- InvokeBuild script development
14+
- Release workflow configuration
15+
- Path-based CI filtering for monorepo
16+
- Build orchestration across packages
17+
18+
## Repository Structure
19+
20+
### Workflows
21+
```
22+
.github/workflows/
23+
├── ci.yml # Main CI workflow (path-based filtering)
24+
├── build.yaml # Build workflow
25+
├── analyze.yaml # Code analysis
26+
├── docs.yaml # Documentation build
27+
├── stale.yaml # Stale issue management
28+
├── release-psdocs.yml # PSDocs release (tag: psdocs-v*)
29+
├── release-psdocs-azure.yml # PSDocs.Azure release (tag: psdocs-azure-v*)
30+
└── release-vscode.yml # VS Code release (tag: vscode-v*)
31+
```
32+
33+
### Build Scripts
34+
```
35+
build.ps1 # Root build orchestrator
36+
build/common.ps1 # Shared build utilities
37+
scripts/pipeline-deps.ps1 # Dependency installation
38+
39+
packages/psdocs-azure/
40+
└── pipeline.build.ps1 # Package-specific InvokeBuild script
41+
```
42+
43+
## CI/CD Architecture
44+
45+
### Path-Based Filtering
46+
The monorepo uses path-based triggers to only build changed packages:
47+
48+
```yaml
49+
on:
50+
push:
51+
paths:
52+
- 'packages/psdocs/**' # Triggers PSDocs build
53+
- 'packages/psdocs-azure/**' # Triggers PSDocs.Azure build
54+
- 'packages/vscode-extension/**' # Triggers VS Code build
55+
```
56+
57+
### Version Tags
58+
Release workflows are triggered by version-prefixed tags:
59+
- `psdocs-v{version}` → Release PSDocs to PowerShell Gallery
60+
- `psdocs-azure-v{version}` → Release PSDocs.Azure to PowerShell Gallery
61+
- `vscode-v{version}` → Release VS Code extension to Marketplace
62+
63+
### Build Dependencies
64+
- PSDocs.Azure depends on PSDocs core
65+
- Build order: `psdocs` → `psdocs-azure` → `vscode` (if applicable)
66+
67+
## Nested Sub-Agent Usage
68+
69+
### Workflow Analysis
70+
```
71+
Use explore agents to analyze existing workflows:
72+
- explore: "Analyze .github/workflows/build.yaml for job structure"
73+
- explore: "Find all GitHub Actions used in this repository"
74+
```
75+
76+
### Syntax Validation
77+
```
78+
Use task agents for validation:
79+
- task: "actionlint .github/workflows/*.yml" (if available)
80+
- task: "yamllint .github/workflows/" (if available)
81+
```
82+
83+
### Build Testing
84+
```
85+
Use task agents to test build scripts:
86+
- task: "./build.ps1 -Build" to verify full build
87+
- task: "pwsh -c 'Invoke-Build -WhatIf'" to preview tasks
88+
```
89+
90+
## GitHub Actions Best Practices
91+
92+
### Security
93+
- Pin action versions with full SHA: `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683`
94+
- Use minimal permissions: `permissions: { contents: read }`
95+
- Never expose secrets in logs
96+
97+
### Performance
98+
- Use caching for dependencies (npm, NuGet, PSGallery)
99+
- Run jobs in parallel when possible
100+
- Use matrix strategy for cross-platform testing
101+
102+
### Monorepo Patterns
103+
```yaml
104+
jobs:
105+
detect-changes:
106+
runs-on: ubuntu-latest
107+
outputs:
108+
psdocs: ${{ steps.filter.outputs.psdocs }}
109+
psdocs-azure: ${{ steps.filter.outputs.psdocs-azure }}
110+
steps:
111+
- uses: dorny/paths-filter@v2
112+
id: filter
113+
with:
114+
filters: |
115+
psdocs:
116+
- 'packages/psdocs/**'
117+
psdocs-azure:
118+
- 'packages/psdocs-azure/**'
119+
```
120+
121+
## InvokeBuild Patterns
122+
123+
### Task Structure
124+
```powershell
125+
# pipeline.build.ps1
126+
task Clean {
127+
Remove-Item -Path ./out -Recurse -Force -ErrorAction SilentlyContinue
128+
}
129+
130+
task Build Clean, {
131+
dotnet build -c Release
132+
}
133+
134+
task Test Build, {
135+
Invoke-Pester -Configuration @{ Run = @{ Path = './tests' } }
136+
}
137+
138+
task . Build, Test
139+
```
140+
141+
### Common Tasks
142+
- `Clean` - Remove build artifacts
143+
- `Build` - Compile code
144+
- `Test` - Run tests
145+
- `Analyze` - Run PSScriptAnalyzer
146+
- `Pack` - Create NuGet/module package
147+
148+
## Build Commands
149+
150+
```powershell
151+
# Root orchestrator
152+
./build.ps1 -Build # Build all packages
153+
./build.ps1 -Package psdocs-azure -Build -Test
154+
./build.ps1 -Clean # Clean all
155+
156+
# Direct InvokeBuild (in package directory)
157+
Invoke-Build # Run default task
158+
Invoke-Build -Task Build,Test # Run specific tasks
159+
Invoke-Build -WhatIf # Preview tasks
160+
161+
# Install dependencies
162+
./scripts/pipeline-deps.ps1
163+
```
164+
165+
## Common Tasks
166+
167+
### Adding a New Workflow
168+
1. Create `.github/workflows/<name>.yaml`
169+
2. Define triggers (push, pull_request, workflow_dispatch)
170+
3. Set minimal permissions
171+
4. Pin action versions
172+
5. Test with `act` locally if available
173+
174+
### Modifying Build Scripts
175+
1. Update appropriate `pipeline.build.ps1`
176+
2. Test locally with `Invoke-Build`
177+
3. Verify CI passes
178+
4. Update `build/common.ps1` for shared utilities
179+
180+
### Adding Path Filters
181+
```yaml
182+
on:
183+
push:
184+
paths:
185+
- 'packages/<package>/**'
186+
- '!packages/<package>/**/*.md' # Exclude docs-only changes
187+
```
188+
189+
## Output Format
190+
191+
When making changes:
192+
1. **Summary** - What CI/CD change was made
193+
2. **Affected Workflows** - Which workflows were modified
194+
3. **Testing** - How to verify the workflow works
195+
4. **Security** - Any security considerations

0 commit comments

Comments
 (0)