PowerShell · TravisEz13 · Nov 19, 2025 · Oct 20, 2025
@@ -31,22 +31,8 @@ runs:
       Import-Module .\tools\ci.psm1
       Invoke-CIBuild
     shell: pwsh
-  - name: xUnit Tests
-    if: success()
-    continue-on-error: true
-    run: |-
-      Write-Verbose -Verbose "Running xUnit tests..."
-      Import-Module .\tools\ci.psm1
-      Restore-PSOptions
-      Invoke-CIxUnit -SkipFailing
-    shell: pwsh
   - name: Upload build artifact
     uses: actions/upload-artifact@v4
     with:
       name: build
       path: ${{ runner.workspace }}/build
-  - name: Upload xunit artifact
-    uses: actions/upload-artifact@v4
-    with:
-      name: testResults-xunit
-      path: ${{ runner.workspace }}/xunit
diff --git a/.github/instructions/build-configuration-guide.md b/.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
diff --git a/.github/instructions/git-requirements-for-builds.md b/.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
+```
diff --git a/.github/instructions/start-psbuild-basics.md b/.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
+```
diff --git a/.github/instructions/troubleshooting-builds.md b/.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