Copilot instructions

1---
2applyTo:
3  - ".github/actions/**/*.yml"
4  - ".github/workflows/**/*.yml"
5---
6 
7# Build and Packaging Steps Pattern
8 
9## Important Rule
10 
11**Build and packaging must run in the same step OR you must save and restore PSOptions between steps.**
12 
13## Why This Matters
14 
15When `Start-PSBuild` runs, it creates PSOptions that contain build configuration details (runtime, configuration, output path, etc.). The packaging functions like `Start-PSPackage` and `Invoke-CIFinish` rely on these PSOptions to know where the build output is located and how it was built.
16 
17GitHub Actions steps run in separate PowerShell sessions. This means PSOptions from one step are not available in the next step.
18 
19## Pattern 1: Combined Build and Package (Recommended)
20 
21Run build and packaging in the same step to keep PSOptions in memory:
22 
23```yaml
24- name: Build and Package
25  run: |-
26    Import-Module ./tools/ci.psm1
27    $releaseTag = Get-ReleaseTag
28    Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag
29    Invoke-CIFinish
30  shell: pwsh
31```
32 
33**Benefits:**
34- Simpler code
35- No need for intermediate files
36- PSOptions automatically available to packaging
37 
38## Pattern 2: Separate Steps with Save/Restore
39 
40If you must separate build and packaging into different steps:
41 
42```yaml
43- name: Build PowerShell
44  run: |-
45    Import-Module ./tools/ci.psm1
46    $releaseTag = Get-ReleaseTag
47    Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag
48    Save-PSOptions -PSOptionsPath "${{ runner.workspace }}/psoptions.json"
49  shell: pwsh
50
51- name: Create Packages
52  run: |-
53    Import-Module ./tools/ci.psm1
54    Restore-PSOptions -PSOptionsPath "${{ runner.workspace }}/psoptions.json"
55    Invoke-CIFinish
56  shell: pwsh
57```
58 
59**When to use:**
60- When you need to run other steps between build and packaging
61- When build and packaging require different permissions or environments
62 
63## Common Mistakes
64 
65### ❌ Incorrect: Separate steps without save/restore
66 
67```yaml
68- name: Build PowerShell
69  run: |-
70    Start-PSBuild -Configuration 'Release'
71  shell: pwsh
72
73- name: Create Packages
74  run: |-
75    Invoke-CIFinish  # ❌ FAILS: PSOptions not available
76  shell: pwsh
77```
78 
79### ❌ Incorrect: Using artifacts without PSOptions
80 
81```yaml
82- name: Download Build Artifacts
83  uses: actions/download-artifact@v4
84  with:
85    name: build
86
87- name: Create Packages
88  run: |-
89    Invoke-CIFinish  # ❌ FAILS: PSOptions not restored
90  shell: pwsh
91```
92 
93## Related Functions
94 
95- `Start-PSBuild` - Builds PowerShell and sets PSOptions
96- `Save-PSOptions` - Saves PSOptions to a JSON file
97- `Restore-PSOptions` - Loads PSOptions from a JSON file
98- `Get-PSOptions` - Gets current PSOptions
99- `Set-PSOptions` - Sets PSOptions
100- `Start-PSPackage` - Creates packages (requires PSOptions)
101- `Invoke-CIFinish` - Calls packaging (requires PSOptions on Linux/macOS)
102 
103## Examples
104 
105### Linux Packaging Action
106 
107```yaml
108- name: Build and Package
109  run: |-
110    Import-Module ./tools/ci.psm1
111    $releaseTag = Get-ReleaseTag
112    Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag
113    Invoke-CIFinish
114  shell: pwsh
115```
116 
117### Windows Packaging Workflow
118 
119```yaml
120- name: Build and Package
121  run: |
122    Import-Module .\tools\ci.psm1
123    Invoke-CIFinish -Runtime ${{ matrix.runtimePrefix }}-${{ matrix.architecture }} -channel ${{ matrix.channel }}
124  shell: pwsh
125```
126 
127Note: `Invoke-CIFinish` for Windows includes both build and packaging in its logic when `Stage` contains 'Build'.
128