MegaBites-AI/Windows-powershell

1---2applyTo:3  - "build.psm1"4  - "tools/ci.psm1"5  - ".github/**/*.yml"6  - ".github/**/*.yaml"7---8 9# Log Grouping Guidelines for GitHub Actions10 11## Purpose12 13Guidelines for using `Write-LogGroupStart` and `Write-LogGroupEnd` to create collapsible log sections in GitHub Actions CI/CD runs.14 15## Key Principles16 17### 1. Groups Cannot Be Nested18 19GitHub Actions does not support nested groups. Only use one level of grouping.20 21**❌ Don't:**22```powershell23Write-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```powershell32Write-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 Substantial42 43Only create groups for operations that generate substantial output (5+ lines). Small groups add clutter without benefit.44 45**❌ Don't:**46```powershell47Write-LogGroupStart -Title "Generate Resource Files"48Write-Log -message "Run ResGen"49Start-ResGen50Write-LogGroupEnd -Title "Generate Resource Files"51```52 53**✅ Do:**54```powershell55Write-Log -message "Run ResGen (generating C# bindings for resx files)"56Start-ResGen57```58 59### 3. Groups Should Represent Independent Operations60 61Each group should be a logically independent operation that users might want to expand/collapse separately.62 63**✅ Good examples:**64- Install Native Dependencies65- Install .NET SDK66- Build PowerShell67- Restore NuGet Packages68 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 Excessive75 76Avoid putting log groups inside loops where each iteration creates a separate group.  This would probably cause nesting.77 78**❌ Don't:**79```powershell80$projects | ForEach-Object {81    Write-LogGroupStart -Title "Restore Project: $_"82    dotnet restore $_83    Write-LogGroupEnd -Title "Restore Project: $_"84}85```86 87**✅ Do:**88```powershell89Write-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 Pattern98 99```powershell100Write-LogGroupStart -Title "Descriptive Operation Name"101try {102    # ... operation code ...103    Write-Log -message "Status updates"104}105finally {106    # Ensure group is always closed107}108Write-LogGroupEnd -Title "Descriptive Operation Name"109```110 111## When to Use Log Groups112 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 output117- Operations where users might want to collapse verbose output118 119Don't use log groups for:120- Single-line operations121- Code that's already inside another group122- Loop iterations with minimal output per iteration123- Diagnostic or debug output that should always be visible124 125## Examples from build.psm1126 127### Good Usage128 129```powershell130function Start-PSBootstrap {131    # Multiple independent operations, each with substantial output132    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### Avoid143 144```powershell145# Too small - just 2-3 lines146Write-LogGroupStart -Title "Generate Resource Files (ResGen)"147Write-Log -message "Run ResGen"148Start-ResGen149Write-LogGroupEnd -Title "Generate Resource Files (ResGen)"150```151 152## GitHub Actions Syntax153 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## Testing161 162Test log grouping locally:163```powershell164$env:GITHUB_ACTIONS = 'true'165Import-Module ./build.psm1166Write-LogGroupStart -Title "Test"167Write-Log -Message "Content"168Write-LogGroupEnd -Title "Test"169```170 171Output should show:172```173::group::Test174Content175::endgroup::176```177 178## References179 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 definitions182