Copilot instructions

1---
2applyTo:
3  - "build.psm1"
4  - "tools/ci.psm1"
5  - ".github/**/*.yml"
6  - ".github/**/*.yaml"
7---
8 
9# Log Grouping Guidelines for GitHub Actions
10 
11## Purpose
12 
13Guidelines for using `Write-LogGroupStart` and `Write-LogGroupEnd` to create collapsible log sections in GitHub Actions CI/CD runs.
14 
15## Key Principles
16 
17### 1. Groups Cannot Be Nested
18 
19GitHub Actions does not support nested groups. Only use one level of grouping.
20 
21**❌ Don't:**
22```powershell
23Write-LogGroupStart -Title "Outer Group"
24Write-LogGroupStart -Title "Inner Group"
25# ... operations ...
26Write-LogGroupEnd -Title "Inner Group"
27Write-LogGroupEnd -Title "Outer Group"
28```
29 
30**✅ Do:**
31```powershell
32Write-LogGroupStart -Title "Operation A"
33# ... operations ...
34Write-LogGroupEnd -Title "Operation A"
35 
36Write-LogGroupStart -Title "Operation B"
37# ... operations ...
38Write-LogGroupEnd -Title "Operation B"
39```
40 
41### 2. Groups Should Be Substantial
42 
43Only create groups for operations that generate substantial output (5+ lines). Small groups add clutter without benefit.
44 
45**❌ Don't:**
46```powershell
47Write-LogGroupStart -Title "Generate Resource Files"
48Write-Log -message "Run ResGen"
49Start-ResGen
50Write-LogGroupEnd -Title "Generate Resource Files"
51```
52 
53**✅ Do:**
54```powershell
55Write-Log -message "Run ResGen (generating C# bindings for resx files)"
56Start-ResGen
57```
58 
59### 3. Groups Should Represent Independent Operations
60 
61Each group should be a logically independent operation that users might want to expand/collapse separately.
62 
63**✅ Good examples:**
64- Install Native Dependencies
65- Install .NET SDK
66- Build PowerShell
67- Restore NuGet Packages
68 
69**❌ Bad examples:**
70- Individual project restores (too granular)
71- Small code generation steps (too small)
72- Sub-steps of a larger operation (would require nesting)
73 
74### 4. One Group Per Iteration Is Excessive
75 
76Avoid putting log groups inside loops where each iteration creates a separate group.  This would probably cause nesting.
77 
78**❌ Don't:**
79```powershell
80$projects | ForEach-Object {
81    Write-LogGroupStart -Title "Restore Project: $_"
82    dotnet restore $_
83    Write-LogGroupEnd -Title "Restore Project: $_"
84}
85```
86 
87**✅ Do:**
88```powershell
89Write-LogGroupStart -Title "Restore All Projects"
90$projects | ForEach-Object {
91    Write-Log -message "Restoring $_"
92    dotnet restore $_
93}
94Write-LogGroupEnd -Title "Restore All Projects"
95```
96 
97## Usage Pattern
98 
99```powershell
100Write-LogGroupStart -Title "Descriptive Operation Name"
101try {
102    # ... operation code ...
103    Write-Log -message "Status updates"
104}
105finally {
106    # Ensure group is always closed
107}
108Write-LogGroupEnd -Title "Descriptive Operation Name"
109```
110 
111## When to Use Log Groups
112 
113Use log groups for:
114- Major build phases (bootstrap, restore, build, test, package)
115- Installation operations (dependencies, SDKs, tools)
116- Operations that produce 5+ lines of output
117- Operations where users might want to collapse verbose output
118 
119Don't use log groups for:
120- Single-line operations
121- Code that's already inside another group
122- Loop iterations with minimal output per iteration
123- Diagnostic or debug output that should always be visible
124 
125## Examples from build.psm1
126 
127### Good Usage
128 
129```powershell
130function Start-PSBootstrap {
131    # Multiple independent operations, each with substantial output
132    Write-LogGroupStart -Title "Install Native Dependencies"
133    # ... apt-get/yum/brew install commands ...
134    Write-LogGroupEnd -Title "Install Native Dependencies"
135 
136    Write-LogGroupStart -Title "Install .NET SDK"
137    # ... dotnet installation ...
138    Write-LogGroupEnd -Title "Install .NET SDK"
139}
140```
141 
142### Avoid
143 
144```powershell
145# Too small - just 2-3 lines
146Write-LogGroupStart -Title "Generate Resource Files (ResGen)"
147Write-Log -message "Run ResGen"
148Start-ResGen
149Write-LogGroupEnd -Title "Generate Resource Files (ResGen)"
150```
151 
152## GitHub Actions Syntax
153 
154These functions emit GitHub Actions workflow commands:
155- `Write-LogGroupStart` → `::group::Title`
156- `Write-LogGroupEnd` → `::endgroup::`
157 
158In the GitHub Actions UI, this renders as collapsible sections with the specified title.
159 
160## Testing
161 
162Test log grouping locally:
163```powershell
164$env:GITHUB_ACTIONS = 'true'
165Import-Module ./build.psm1
166Write-LogGroupStart -Title "Test"
167Write-Log -Message "Content"
168Write-LogGroupEnd -Title "Test"
169```
170 
171Output should show:
172```
173::group::Test
174Content
175::endgroup::
176```
177 
178## References
179 
180- [GitHub Actions: Grouping log lines](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#grouping-log-lines)
181- `build.psm1`: `Write-LogGroupStart` and `Write-LogGroupEnd` function definitions
182