MegaBites-AI/Windows-powershell

1---2applyTo:3  - ".github/**/*.yml"4  - ".github/**/*.yaml"5---6 7# Build and Checkout Prerequisites for PowerShell CI8 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## Overview12 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 Configuration16 17### Fetch Depth18 19All CI workflows that build or test PowerShell use `fetch-depth: 1000` in the checkout step:20 21```yaml22- name: checkout23  uses: actions/checkout@v524  with:25    fetch-depth: 100026```27 28**Why 1000 commits?**29- The build system needs access to Git history to determine version information30- `Sync-PSTags` requires sufficient history to fetch and work with tags31- 1000 commits provides a reasonable balance between clone speed and having enough history for version calculation32- Shallow clones (fetch-depth: 1) would break versioning logic33 34**Exceptions:**35- The `changes` job uses default fetch depth (no explicit `fetch-depth`) since it only needs to detect file changes36- The `analyze` job (CodeQL) uses `fetch-depth: '0'` (full history) for comprehensive security analysis37- Linux packaging uses `fetch-depth: 0` to ensure all tags are available for package version metadata38 39### Workflows Using fetch-depth: 100040 41- **Linux CI** (`.github/workflows/linux-ci.yml`): All build and test jobs42- **Windows CI** (`.github/workflows/windows-ci.yml`): All build and test jobs  43- **macOS CI** (`.github/workflows/macos-ci.yml`): All build and test jobs44 45## Sync-PSTags Operation46 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### Location52 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 Works59 60```powershell61Sync-PSTags -AddRemoteIfMissing62```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   ```bash74   git fetch --tags --quiet upstream75   ```76 774. Sets `$script:tagsUpToDate = $true` to indicate tags are synchronized78 79### Why Sync-PSTags is Required80 81Tags are critical for:82- **Version Calculation**: `Get-PSVersion` uses `git describe --abbrev=0` to find the latest tag83- **Build Numbering**: CI builds use tag-based versioning for artifacts84- **Changelog Generation**: Release notes are generated based on tags85- **Package Metadata**: Package versions are derived from Git tags86 87Without synchronized tags:88- Version detection would fail or return incorrect versions89- Builds might have inconsistent version numbers90- The build process would error when trying to determine the version91 92### Bootstrap Step in CI Action93 94The `.github/actions/build/ci/action.yml` includes this in the Bootstrap step:95 96```yaml97- name: Bootstrap98  if: success()99  run: |-100    Write-Verbose -Verbose "Running Bootstrap..."101    Import-Module .\tools\ci.psm1102    Invoke-CIInstall -SkipUser103    Write-Verbose -Verbose "Start Sync-PSTags"104    Sync-PSTags -AddRemoteIfMissing105    Write-Verbose -Verbose "End Sync-PSTags"106  shell: pwsh107```108 109**Note**: `Sync-PSTags` is called twice:1101. Once by `Invoke-CIInstall` (in `tools/ci.psm1`)1112. Explicitly again in the Bootstrap step112 113This redundancy ensures tags are available even if the first call encounters issues.114 115## Best Practices for Copilot Sessions116 117When working with the PowerShell CI system:118 1191. **Always use `fetch-depth: 1000` or greater** when checking out code for build or test operations1202. **Understand that `Sync-PSTags` requires network access** to fetch tags from the upstream repository1213. **Don't modify the fetch-depth without understanding the impact** on version calculation1224. **If adding new CI workflows**, follow the existing pattern:123   - Use `fetch-depth: 1000` for build/test jobs124   - Call `Sync-PSTags -AddRemoteIfMissing` during bootstrap125   - Ensure the upstream remote is properly configured126 1275. **For local development**, developers should:128   - Have the upstream remote configured129   - Run `Sync-PSTags -AddRemoteIfMissing` before building130   - Or use `Start-PSBuild` which handles this automatically131 132## Related Files133 134- `.github/actions/build/ci/action.yml` - Main CI build action135- `.github/workflows/linux-ci.yml` - Linux CI workflow136- `.github/workflows/windows-ci.yml` - Windows CI workflow137- `.github/workflows/macos-ci.yml` - macOS CI workflow138- `build.psm1` - Contains Sync-PSTags function definition139- `tools/ci.psm1` - CI-specific build functions that call Sync-PSTags140 141## Summary142 143The PowerShell CI system depends on:1441. **Adequate Git history** (fetch-depth: 1000) for version calculation1452. **Synchronized Git tags** via `Sync-PSTags` for accurate versioning1463. **Upstream remote access** to fetch official repository tags147 148These prerequisites ensure consistent, accurate build versioning across all CI platforms.149