Copilot instructions

1---
2applyTo:
3  - ".github/**/*.yml"
4  - ".github/**/*.yaml"
5---
6 
7# Build and Checkout Prerequisites for PowerShell CI
8 
9This document describes the checkout and build prerequisites used in PowerShell's CI workflows. It is intended for GitHub Copilot sessions working with the build system.
10 
11## Overview
12 
13The PowerShell repository uses a standardized build process across Linux, Windows, and macOS CI workflows. Understanding the checkout configuration and the `Sync-PSTags` operation is crucial for working with the build system.
14 
15## Checkout Configuration
16 
17### Fetch Depth
18 
19All CI workflows that build or test PowerShell use `fetch-depth: 1000` in the checkout step:
20 
21```yaml
22- name: checkout
23  uses: actions/checkout@v5
24  with:
25    fetch-depth: 1000
26```
27 
28**Why 1000 commits?**
29- The build system needs access to Git history to determine version information
30- `Sync-PSTags` requires sufficient history to fetch and work with tags
31- 1000 commits provides a reasonable balance between clone speed and having enough history for version calculation
32- Shallow clones (fetch-depth: 1) would break versioning logic
33 
34**Exceptions:**
35- The `changes` job uses default fetch depth (no explicit `fetch-depth`) since it only needs to detect file changes
36- The `analyze` job (CodeQL) uses `fetch-depth: '0'` (full history) for comprehensive security analysis
37- Linux packaging uses `fetch-depth: 0` to ensure all tags are available for package version metadata
38 
39### Workflows Using fetch-depth: 1000
40 
41- **Linux CI** (`.github/workflows/linux-ci.yml`): All build and test jobs
42- **Windows CI** (`.github/workflows/windows-ci.yml`): All build and test jobs  
43- **macOS CI** (`.github/workflows/macos-ci.yml`): All build and test jobs
44 
45## Sync-PSTags Operation
46 
47### What is Sync-PSTags?
48 
49`Sync-PSTags` is a PowerShell function defined in `build.psm1` that ensures Git tags from the upstream PowerShell repository are synchronized to the local clone.
50 
51### Location
52 
53- **Function Definition**: `build.psm1` (line 36-76)
54- **Called From**: 
55  - `.github/actions/build/ci/action.yml` (Bootstrap step, line 24)
56  - `tools/ci.psm1` (Invoke-CIInstall function, line 146)
57 
58### How It Works
59 
60```powershell
61Sync-PSTags -AddRemoteIfMissing
62```
63 
64The function:
651. Searches for a Git remote pointing to the official PowerShell repository:
66   - `https://github.com/PowerShell/PowerShell`
67   - `git@github.com:PowerShell/PowerShell`
68 
692. If no upstream remote exists and `-AddRemoteIfMissing` is specified:
70   - Adds a remote named `upstream` pointing to `https://github.com/PowerShell/PowerShell.git`
71 
723. Fetches all tags from the upstream remote:
73```bash
74   git fetch --tags --quiet upstream
75```
76 
774. Sets `$script:tagsUpToDate = $true` to indicate tags are synchronized
78 
79### Why Sync-PSTags is Required
80 
81Tags are critical for:
82- **Version Calculation**: `Get-PSVersion` uses `git describe --abbrev=0` to find the latest tag
83- **Build Numbering**: CI builds use tag-based versioning for artifacts
84- **Changelog Generation**: Release notes are generated based on tags
85- **Package Metadata**: Package versions are derived from Git tags
86 
87Without synchronized tags:
88- Version detection would fail or return incorrect versions
89- Builds might have inconsistent version numbers
90- The build process would error when trying to determine the version
91 
92### Bootstrap Step in CI Action
93 
94The `.github/actions/build/ci/action.yml` includes this in the Bootstrap step:
95 
96```yaml
97- name: Bootstrap
98  if: success()
99  run: |-
100    Write-Verbose -Verbose "Running Bootstrap..."
101    Import-Module .\tools\ci.psm1
102    Invoke-CIInstall -SkipUser
103    Write-Verbose -Verbose "Start Sync-PSTags"
104    Sync-PSTags -AddRemoteIfMissing
105    Write-Verbose -Verbose "End Sync-PSTags"
106  shell: pwsh
107```
108 
109**Note**: `Sync-PSTags` is called twice:
1101. Once by `Invoke-CIInstall` (in `tools/ci.psm1`)
1112. Explicitly again in the Bootstrap step
112 
113This redundancy ensures tags are available even if the first call encounters issues.
114 
115## Best Practices for Copilot Sessions
116 
117When working with the PowerShell CI system:
118 
1191. **Always use `fetch-depth: 1000` or greater** when checking out code for build or test operations
1202. **Understand that `Sync-PSTags` requires network access** to fetch tags from the upstream repository
1213. **Don't modify the fetch-depth without understanding the impact** on version calculation
1224. **If adding new CI workflows**, follow the existing pattern:
123   - Use `fetch-depth: 1000` for build/test jobs
124   - Call `Sync-PSTags -AddRemoteIfMissing` during bootstrap
125   - Ensure the upstream remote is properly configured
126 
1275. **For local development**, developers should:
128   - Have the upstream remote configured
129   - Run `Sync-PSTags -AddRemoteIfMissing` before building
130   - Or use `Start-PSBuild` which handles this automatically
131 
132## Related Files
133 
134- `.github/actions/build/ci/action.yml` - Main CI build action
135- `.github/workflows/linux-ci.yml` - Linux CI workflow
136- `.github/workflows/windows-ci.yml` - Windows CI workflow
137- `.github/workflows/macos-ci.yml` - macOS CI workflow
138- `build.psm1` - Contains Sync-PSTags function definition
139- `tools/ci.psm1` - CI-specific build functions that call Sync-PSTags
140 
141## Summary
142 
143The PowerShell CI system depends on:
1441. **Adequate Git history** (fetch-depth: 1000) for version calculation
1452. **Synchronized Git tags** via `Sync-PSTags` for accurate versioning
1463. **Upstream remote access** to fetch official repository tags
147 
148These prerequisites ensure consistent, accurate build versioning across all CI platforms.
149