Refactor: Centralize xUnit tests into reusable workflow and remove legacy verification (#26243)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: TravisEz13 <10873629+TravisEz13@users.noreply.github.com>

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

@@ -0,0 +1,95 @@
+# Build Configuration Guide
+
+## Choosing the Right Configuration
+
+### For Testing
+
+**Use: Default (Debug)**
+
+```yaml
+- name: Build for Testing
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    Start-PSBuild
+```
+
+**Why Debug:**
+- Includes debugging symbols
+- Better error messages
+- Faster build times
+- Suitable for xUnit and Pester tests
+
+**Do NOT use:**
+- `-Configuration 'Release'` (unnecessary for tests)
+- `-ReleaseTag` (not needed for tests)
+- `-CI` (unless you specifically need Pester module)
+
+### For Release/Packaging
+
+**Use: Release with version tag**
+
+```yaml
+- name: Build for Release
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    $releaseTag = Get-ReleaseTag
+    Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag
+```
+
+**Why Release:**
+- Optimized binaries
+- No debug symbols (smaller size)
+- Production-ready
+
+### For Code Coverage
+
+**Use: CodeCoverage configuration**
+
+```yaml
+- name: Build with Coverage
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    Start-PSBuild -Configuration 'CodeCoverage'
+```
+
+## Platform Considerations
+
+### All Platforms
+
+Same commands work across Linux, Windows, and macOS:
+
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, windows-latest, macos-latest]
+runs-on: ${{ matrix.os }}
+steps:
+  - name: Build PowerShell
+    shell: pwsh
+    run: |
+      Import-Module ./tools/ci.psm1
+      Start-PSBuild
+```
+
+### Output Locations
+
+**Linux/macOS:**
+```
+src/powershell-unix/bin/Debug/<netversion>/<runtime>/publish/
+```
+
+**Windows:**
+```
+src/powershell-win-core/bin/Debug/<netversion>/<runtime>/publish/
+```
+
+## Best Practices
+
+1. Use default configuration for testing
+2. Avoid redundant parameters
+3. Match configuration to purpose
+4. Use `-CI` only when needed
+5. Always specify `-ReleaseTag` for release or packaging builds

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

@@ -0,0 +1,71 @@
+# Git Requirements for Building PowerShell
+
+## Fetch Depth
+
+**Required:** `fetch-depth: 1000`
+
+The PowerShell build process uses `git describe --abbrev=60 --long` to generate version information. This requires access to git history and tags.
+
+### Problem
+
+Without sufficient fetch depth, builds fail with:
+```
+error MSB3073: The command "git describe --abbrev=60 --long" exited with code 128.
+```
+
+### Solution
+
+Always use `fetch-depth: 1000` in the checkout step:
+
+```yaml
+- name: Checkout
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 1000
+```
+
+## Tag Synchronization
+
+**Required:** `Sync-PSTags -AddRemoteIfMissing`
+
+The build process needs git tags to properly version the build.
+
+### Problem
+
+Without tag synchronization:
+- Version information is incorrect
+- Build versioning fails
+
+### Solution
+
+Include tag synchronization in the bootstrap step:
+
+```yaml
+- name: Bootstrap
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    Sync-PSTags -AddRemoteIfMissing
+```
+
+## Complete Example
+
+```yaml
+steps:
+  - name: Checkout
+    uses: actions/checkout@v4
+    with:
+      fetch-depth: 1000
+
+  - name: Setup .NET
+    uses: actions/setup-dotnet@v4
+    with:
+      global-json-file: ./global.json
+
+  - name: Bootstrap
+    shell: pwsh
+    run: |
+      Import-Module ./tools/ci.psm1
+      Invoke-CIInstall -SkipUser
+      Sync-PSTags -AddRemoteIfMissing
+```

.github/instructions/start-psbuild-basics.md

@@ -0,0 +1,92 @@
+# Start-PSBuild Basics
+
+## Purpose
+
+`Start-PSBuild` builds PowerShell from source. It's defined in `build.psm1` and used in CI/CD workflows.
+
+## Default Usage
+
+For most scenarios, use with no parameters:
+
+```powershell
+Import-Module ./tools/ci.psm1
+Start-PSBuild
+```
+
+**Default behavior:**
+- Configuration: `Debug`
+- PSModuleRestore: Enabled
+- Runtime: Auto-detected for platform
+
+## Common Configurations
+
+### Debug Build (Default)
+
+```powershell
+Start-PSBuild
+```
+
+Use for:
+- Testing (xUnit, Pester)
+- Development
+- Debugging
+
+### Release Build
+
+```powershell
+Start-PSBuild -Configuration 'Release'
+```
+
+Use for:
+- Production packages
+- Distribution
+- Performance testing
+
+### Code Coverage Build
+
+```powershell
+Start-PSBuild -Configuration 'CodeCoverage'
+```
+
+Use for:
+- Code coverage analysis
+- Test coverage reports
+
+## Common Parameters
+
+### -Configuration
+
+Values: `Debug`, `Release`, `CodeCoverage`, `StaticAnalysis`
+
+Default: `Debug`
+
+### -CI
+
+Restores Pester module for CI environments.
+
+```powershell
+Start-PSBuild -CI
+```
+
+### -PSModuleRestore
+
+Now enabled by default. Use `-NoPSModuleRestore` to skip.
+
+### -ReleaseTag
+
+Specifies version tag for release builds:
+
+```powershell
+$releaseTag = Get-ReleaseTag
+Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag
+```
+
+## Workflow Example
+
+```yaml
+- name: Build PowerShell
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    Start-PSBuild
+```

.github/instructions/troubleshooting-builds.md

@@ -0,0 +1,92 @@
+# Troubleshooting Build Issues
+
+## Git Describe Error
+
+**Error:**
+```
+error MSB3073: The command "git describe --abbrev=60 --long" exited with code 128.
+```
+
+**Cause:** Insufficient git history (shallow clone)
+
+**Solution:** Add `fetch-depth: 1000` to checkout step
+
+```yaml
+- name: Checkout
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 1000
+```
+
+## Version Information Incorrect
+
+**Symptom:** Build produces wrong version numbers
+
+**Cause:** Git tags not synchronized
+
+**Solution:** Run `Sync-PSTags -AddRemoteIfMissing`:
+
+```yaml
+- name: Bootstrap
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    Invoke-CIInstall -SkipUser
+    Sync-PSTags -AddRemoteIfMissing
+```
+
+## PowerShell Binary Not Built
+
+**Error:**
+```
+Exception: CoreCLR pwsh.exe was not built
+```
+
+**Causes:**
+1. Build failed (check logs)
+2. Wrong configuration used
+3. Build output location incorrect
+
+**Solutions:**
+1. Check build logs for errors
+2. Verify correct configuration for use case
+3. Use default parameters: `Start-PSBuild`
+
+## Module Restore Issues
+
+**Symptom:** Slow build or module restore failures
+
+**Causes:**
+- Network issues
+- Module cache problems
+- Package source unavailable
+
+**Solutions:**
+1. Retry the build
+2. Check network connectivity
+3. Use `-NoPSModuleRestore` if modules not needed
+4. Clear package cache if persistent
+
+## .NET SDK Not Found
+
+**Symptom:** Build can't find .NET SDK
+
+**Solution:** Ensure .NET setup step runs first:
+
+```yaml
+- name: Setup .NET
+  uses: actions/setup-dotnet@v4
+  with:
+    global-json-file: ./global.json
+```
+
+## Bootstrap Failures
+
+**Symptom:** Invoke-CIInstall fails
+
+**Causes:**
+- Missing dependencies
+- Network issues
+- Platform-specific requirements not met
+
+**Solution:** Check prerequisites for your platform in build system docs

.github/instructions/workflow-prerequisites.md

@@ -0,0 +1,91 @@
+# Workflow Prerequisites for Building PowerShell
+
+## Required Steps Before Start-PSBuild
+
+These steps must run before calling `Start-PSBuild`:
+
+### 1. Checkout
+
+```yaml
+- name: Checkout
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 1000  # Required for version generation
+```
+
+### 2. Setup .NET
+
+```yaml
+- name: Setup .NET
+  uses: actions/setup-dotnet@v4
+  with:
+    global-json-file: ./global.json
+```
+
+### 3. Bootstrap
+
+```yaml
+- name: Bootstrap
+  shell: pwsh
+  run: |
+    Import-Module ./tools/ci.psm1
+    Invoke-CIInstall -SkipUser
+    Sync-PSTags -AddRemoteIfMissing
+```
+
+## Complete Prerequisites Example
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1000
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: ./global.json
+
+      - name: Bootstrap
+        shell: pwsh
+        run: |
+          Import-Module ./tools/ci.psm1
+          Invoke-CIInstall -SkipUser
+          Sync-PSTags -AddRemoteIfMissing
+
+      - name: Build PowerShell
+        shell: pwsh
+        run: |
+          Import-Module ./tools/ci.psm1
+          Start-PSBuild
+```
+
+## Why Each Step Matters
+
+**Checkout with fetch-depth:**
+- Build needs git history for versioning
+- Without it: `git describe` fails
+
+**Setup .NET:**
+- Provides SDK for building
+- Uses version from global.json
+
+**Bootstrap:**
+- Installs dependencies
+- Syncs git tags
+- Prepares build environment
+
+## Optional Steps
+
+### Environment Capture (Debugging)
+
+```yaml
+- name: Capture Environment
+  run: |
+    Get-ChildItem -Path env: | Out-String -width 9999 -Stream | Write-Verbose -Verbose
+  shell: pwsh
+```