Add copilot instructions (#1405)

* Add copilot instructions

* Update .github/copilot-instructions.md

Co-authored-by: Matt Thalman <[email protected]>

* Fix linter issues and respond to code review feedback

---------

Co-authored-by: Matt Thalman <[email protected]>

Author: MichaelSimons

.github/copilot-instructions.md

@@ -0,0 +1,72 @@
+# .NET Source Build Reference Packages - Copilot Instructions
+
+This file contains AI-specific guidance for working with this repository.
+All general documentation is maintained in the [README.md](../README.md) to avoid duplication.
+
+## Critical Safety Rules
+
+### Absolute Prohibitions
+
+- **NEVER** modify files inside `src/externalPackages/src/` (these are git submodules)
+- **NEVER** delete or recreate `Customizations.props` or `Customizations.cs` files
+- **NEVER** suggest adding preview/RC packages
+- **NEVER** ignore build failures in `./build.sh -sb`
+
+### Before Making Changes
+
+- **ALWAYS** check if a package has existing customizations before regenerating
+- **ALWAYS** validate commands work on Linux (primary platform for source-build)
+- **ALWAYS** preserve intentional code comments explaining manual fixes
+
+## Workflow Patterns
+
+### When User Asks to "Add a Package"
+
+1. Determine package type first: External, Reference, Targeting, or Text-only
+2. For Reference packages: Use `./generate.sh --package name,version`
+3. For External packages: Requires submodule + project creation + patches1
+4. Check README for detailed workflows
+
+### When Regenerating Packages
+
+```bash
+# Check for existing customizations first
+find src/referencePackages/src/package.name/version -name "Customizations.*"
+```
+
+- If customizations exist, preserve them during regeneration
+- The generate script will preserve them
+
+### When Build Fails
+
+1. Try building individual package: `./build.sh -sb --projects /full/path/to/package.csproj`
+2. Check for compilation errors that need `Customizations.props` (NoWarn entries)
+3. Look for API issues that need `Customizations.cs` (partial class additions)
+4. Always add explanatory comments for manual fixes needed in the generated source files outside of Customizations files
+
+## Decision Support
+
+### Customizations.props vs Customizations.cs
+
+- **Customizations.props**: MSBuild properties, NoWarn suppressions, additional source files
+- **Customizations.cs**: Additional types, members for partial classes, conditional compilation
+
+### External Package Changes
+
+- Always create patches via `extract-patches.sh` - never suggest direct file edits
+- Patches live in `src/externalPackages/patches/<component>/`
+- Test patches with `git am` before suggesting
+
+## Validation Checklist
+
+After any package changes:
+
+- [ ] `./build.sh -sb` succeeds
+- [ ] Check `artifacts/packages/*` for expected output
+- [ ] Verify no new files in submodule directories
+- [ ] Confirm Customizations files preserved if they existed
+
+## 🔗 References
+
+- All build commands and detailed processes are in the [README.md](../README.md)
+- Generator issues: [docs/known_generator_issues.md](../docs/known_generator_issues.md)

README.md

@@ -1,6 +1,7 @@
 # .NET Source Build Assets
 
 This repository contains source, tools, and infrastructure for auxilary packages required to [build .NET from source](https://github.com/dotnet/source-build).
+This repository is often referred to as `SBRP`.
 
 This repo supports the following package types:
 
@@ -44,6 +45,7 @@ to .NET. The following sections describe how to add/upgrade the various types of
 ### External
 
 #### Adding a New External Component
+
 1. Add the repo as a submodule to `./src/externalPackages/src`
 
     ```bash
@@ -52,7 +54,7 @@ to .NET. The following sections describe how to add/upgrade the various types of
     ```
 
 1. Define a [project](src/externalPackages/projects) for the new component.
-   The project is responsible for building the submodule with the appropriate configuration for source build. 
+   The project is responsible for building the submodule with the appropriate configuration for source build.
    See the [existing projects](src/externalPackages/projects) for examples.
 
 1. [Build](#building) locally and resolve any build errors.
@@ -109,7 +111,7 @@ the maintenance burden when [updating a component to a newer version](#updating-
 
     1. From the root directory of the submodule, run [extract-patches.sh](src/externalPackages/patches/extract-patches.sh)/[extract-patches.ps1](src/externalPackages/patches/extract-patches.ps1).
        The script will prepare a patch based on the base sha of the submodule and the latest committed changes.
-       The patch will be added to patches/<component>/*.patch
+       The patch will be added to `patches/<component>/*.patch`
 
 1. To apply a patch, or multiple patches, use `git am` while inside the submodule directory.
    For example, to apply *all* `humanizer` patches: