Copilot instructions

1---
2applyTo:
3  - "build.psm1"
4  - "tools/ci.psm1"
5  - ".github/**/*.yml"
6  - ".github/**/*.yaml"
7  - ".pipelines/**/*.yml"
8---
9 
10# Build Configuration Guide
11 
12## Choosing the Right Configuration
13 
14### For Testing
15 
16**Use: Default (Debug)**
17 
18```yaml
19- name: Build for Testing
20  shell: pwsh
21  run: |
22    Import-Module ./tools/ci.psm1
23    Start-PSBuild
24```
25 
26**Why Debug:**
27- Includes debugging symbols
28- Better error messages
29- Faster build times
30- Suitable for xUnit and Pester tests
31 
32**Do NOT use:**
33- `-Configuration 'Release'` (unnecessary for tests)
34- `-ReleaseTag` (not needed for tests)
35- `-CI` (unless you specifically need Pester module)
36 
37### For Release/Packaging
38 
39**Use: Release with version tag and public NuGet feeds**
40 
41```yaml
42- name: Build for Release
43  shell: pwsh
44  run: |
45    Import-Module ./build.psm1
46    Import-Module ./tools/ci.psm1
47    Switch-PSNugetConfig -Source Public
48    $releaseTag = Get-ReleaseTag
49    Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag
50```
51 
52**Why Release:**
53- Optimized binaries
54- No debug symbols (smaller size)
55- Production-ready
56 
57**Why Switch-PSNugetConfig -Source Public:**
58- Switches NuGet package sources to public feeds (nuget.org and public Azure DevOps feeds)
59- Required for CI/CD environments that don't have access to private feeds
60- Uses publicly available packages instead of Microsoft internal feeds
61 
62### For Code Coverage
63 
64**Use: CodeCoverage configuration**
65 
66```yaml
67- name: Build with Coverage
68  shell: pwsh
69  run: |
70    Import-Module ./tools/ci.psm1
71    Start-PSBuild -Configuration 'CodeCoverage'
72```
73 
74## Platform Considerations
75 
76### All Platforms
77 
78Same commands work across Linux, Windows, and macOS:
79 
80```yaml
81strategy:
82  matrix:
83    os: [ubuntu-latest, windows-latest, macos-latest]
84runs-on: ${{ matrix.os }}
85steps:
86  - name: Build PowerShell
87    shell: pwsh
88    run: |
89      Import-Module ./tools/ci.psm1
90      Start-PSBuild
91```
92 
93### Output Locations
94 
95**Linux/macOS:**
96```
97src/powershell-unix/bin/Debug/<netversion>/<runtime>/publish/
98```
99 
100**Windows:**
101```
102src/powershell-win-core/bin/Debug/<netversion>/<runtime>/publish/
103```
104 
105## Best Practices
106 
1071. Use default configuration for testing
1082. Avoid redundant parameters
1093. Match configuration to purpose
1104. Use `-CI` only when needed
1115. Always specify `-ReleaseTag` for release or packaging builds
1126. Use `Switch-PSNugetConfig -Source Public` in CI/CD for release builds
113 
114## NuGet Feed Configuration
115 
116### Switch-PSNugetConfig
117 
118The `Switch-PSNugetConfig` function in `build.psm1` manages NuGet package source configuration.
119 
120**Available Sources:**
121 
122- **Public**: Uses public feeds (nuget.org and public Azure DevOps feeds)
123  - Required for: CI/CD environments, public builds, packaging
124  - Does not require authentication
125 
126- **Private**: Uses internal PowerShell team feeds
127  - Required for: Internal development with preview packages
128  - Requires authentication credentials
129 
130- **NuGetOnly**: Uses only nuget.org
131  - Required for: Minimal dependency scenarios
132 
133**Usage:**
134 
135```powershell
136# Switch to public feeds (most common for CI/CD)
137Switch-PSNugetConfig -Source Public
138 
139# Switch to private feeds with authentication
140Switch-PSNugetConfig -Source Private -UserName $userName -ClearTextPAT $pat
141 
142# Switch to nuget.org only
143Switch-PSNugetConfig -Source NuGetOnly
144```
145 
146**When to Use:**
147 
148- **Always use `-Source Public`** before building in CI/CD workflows
149- Use before any build that will create packages for distribution
150- Use in forks or environments without access to Microsoft internal feeds
151