FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add GitHub Copilot instruction files for PowerShell CI build system (… · PowerShell/PowerShell@eeefcd7 · GitHub

/ PowerShell Public

Commit eeefcd7

Browse files
Copilot
and
TravisEz13
authored
Add GitHub Copilot instruction files for PowerShell CI build system (#26253)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: TravisEz13 <10873629+TravisEz13@users.noreply.github.com> Co-authored-by: Travis Plunk <travis.plunk@microsoft.com>
1 parent dbc09a1 commit eeefcd7

7 files changed

Lines changed: 392 additions & 162 deletions

‎.github/instructions/build-checkout-prerequisites.instructions.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
applyTo:
3+
- ".github/**/*.yml"
4+
- ".github/**/*.yaml"
5+
---
6+
7+
# Build and Checkout Prerequisites for PowerShell CI
8+
9+
This 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+
13+
The 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+
19+
All 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
61+
Sync-PSTags -AddRemoteIfMissing
62+
```
63+
64+
The function:
65+
1. Searches for a Git remote pointing to the official PowerShell repository:
66+
- `https://github.com/PowerShell/PowerShell`
67+
- `git@github.com:PowerShell/PowerShell`
68+
69+
2. If no upstream remote exists and `-AddRemoteIfMissing` is specified:
70+
- Adds a remote named `upstream` pointing to `https://github.com/PowerShell/PowerShell.git`
71+
72+
3. Fetches all tags from the upstream remote:
73+
```bash
74+
git fetch --tags --quiet upstream
75+
```
76+
77+
4. Sets `$script:tagsUpToDate = $true` to indicate tags are synchronized
78+
79+
### Why Sync-PSTags is Required
80+
81+
Tags 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+
87+
Without 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+
94+
The `.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:
110+
1. Once by `Invoke-CIInstall` (in `tools/ci.psm1`)
111+
2. Explicitly again in the Bootstrap step
112+
113+
This redundancy ensures tags are available even if the first call encounters issues.
114+
115+
## Best Practices for Copilot Sessions
116+
117+
When working with the PowerShell CI system:
118+
119+
1. **Always use `fetch-depth: 1000` or greater** when checking out code for build or test operations
120+
2. **Understand that `Sync-PSTags` requires network access** to fetch tags from the upstream repository
121+
3. **Don't modify the fetch-depth without understanding the impact** on version calculation
122+
4. **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+
127+
5. **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+
143+
The PowerShell CI system depends on:
144+
1. **Adequate Git history** (fetch-depth: 1000) for version calculation
145+
2. **Synchronized Git tags** via `Sync-PSTags` for accurate versioning
146+
3. **Upstream remote access** to fetch official repository tags
147+
148+
These prerequisites ensure consistent, accurate build versioning across all CI platforms.

.github/instructions/build-configuration-guide.md renamed to .github/instructions/build-configuration-guide.instructions.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
---
2+
applyTo:
3+
- "build.psm1"
4+
- "tools/ci.psm1"
5+
- ".github/**/*.yml"
6+
- ".github/**/*.yaml"
7+
---
8+
19
# Build Configuration Guide
210

311
## Choosing the Right Configuration

‎.github/instructions/git-requirements-for-builds.md‎

Lines changed: 0 additions & 71 deletions
This file was deleted.

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL