From 5313a2e50f98516c024b77e1e93745d0a6529672 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:25:58 +0000
Subject: [PATCH 1/7] Initial plan


From 0b64a4aa6b0df492849f34ff016551c6416d292b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:31:51 +0000
Subject: [PATCH 2/7] Add .github/copilot-instructions.md for repository
 guidance

Co-authored-by: mthalman <15789599+mthalman@users.noreply.github.com>
---
 .github/copilot-instructions.md | 163 ++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..9368d428f
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,163 @@
+# GitHub Copilot Instructions for dotnet/docker-tools
+
+This repository contains common tools for .NET Docker repositories, with the primary tool being **ImageBuilder** - a specialized .NET application for building, testing, and publishing Docker images across multiple platforms and architectures.
+
+## Repository Structure
+
+- **`src/`** - Contains the ImageBuilder tool and its components
+  - `ImageBuilder/` - Main tool source code (C# .NET)
+  - `ImageBuilder.Models/` - Data models and manifest schema
+  - `ImageBuilder.Tests/` - Unit tests
+  - `Dockerfile.linux` and `Dockerfile.windows` - ImageBuilder container images
+- **`eng/docker-tools/`** - Shared infrastructure synchronized across all .NET Docker repositories
+  - **`DEV-GUIDE.md`** - **CRITICAL**: Comprehensive developer guide for using the docker-tools infrastructure (see Developer Guide section below)
+  - PowerShell scripts for local development (`build.ps1`, `Invoke-ImageBuilder.ps1`)
+  - Azure Pipelines templates for CI/CD
+- **`documentation/`** - User-facing documentation
+  - `manifest-file.md` - Manifest schema documentation
+  - `base-image-dependency-flow.md` - Base image update automation
+
+## Developer Guide Maintenance
+
+**IMPORTANT**: The `eng/docker-tools/DEV-GUIDE.md` file is the authoritative guide for developers using this infrastructure. When making changes to the docker-tools infrastructure:
+
+1. **Always update DEV-GUIDE.md** when you modify:
+   - PowerShell scripts in `eng/docker-tools/`
+   - Azure Pipeline templates
+   - ImageBuilder commands or parameters
+   - Build/test/publish workflows
+   - Any infrastructure behavior or conventions
+
+2. **Keep examples current**: The DEV-GUIDE.md contains practical examples and workflows - ensure they remain accurate and functional.
+
+3. **Document breaking changes**: If changes affect consuming repositories (dotnet-docker, dotnet-buildtools-prereqs-docker, dotnet-framework-docker), clearly document migration steps.
+
+## Coding Standards
+
+### C# Code (.cs files)
+
+- **License header required**: All C# files must start with:
+  ```csharp
+  // Licensed to the .NET Foundation under one or more agreements.
+  // The .NET Foundation licenses this file to you under the MIT license.
+  ```
+- **Indentation**: 4 spaces (no tabs)
+- **Braces**: Allman style - opening braces on new lines
+- **Field naming**:
+  - Private/internal fields: `_camelCase` prefix
+  - Static fields: `s_camelCase` prefix
+  - Constants: `PascalCase`
+- **Avoid `this.`** unless necessary
+- **Use `var`** only when type is clear
+- **Prefer keywords** over BCL types (e.g., `string` not `String`)
+- **TreatWarningsAsErrors**: Enabled - all warnings must be resolved
+- **LangVersion**: Uses latest C# language features
+
+### PowerShell Scripts (.ps1 files)
+
+- Follow existing patterns in `eng/docker-tools/` scripts
+- Use `Invoke-ImageBuilder.ps1` as the central entry point for ImageBuilder operations
+- Support common filtering parameters: `-OS`, `-Architecture`, `-Version`, `-Paths`
+
+### JSON and YAML
+
+- **JSON**: 2-space indentation
+- **YAML**: 2-space indentation
+- Manifest files follow the schema defined in `src/ImageBuilder/Models/Manifest/`
+
+### Other Files
+
+- **Final newline**: All files must end with a newline
+- **Trim trailing whitespace**: Required
+- **Line endings**:
+  - Shell scripts (`.sh`): LF
+  - Batch files (`.cmd`, `.bat`): CRLF
+
+## Building and Testing
+
+### Build the entire repository
+```bash
+# Linux/Mac
+./build.sh
+
+# Windows
+build.cmd
+```
+
+This runs: restore → build → test → pack
+
+### Build ImageBuilder container image
+```bash
+# From root
+pwsh -wd ./src -f src/build.ps1
+```
+
+### Run tests
+```bash
+# From root
+./build.sh --test
+
+# From src/
+pwsh -f run-tests.ps1
+```
+
+## ImageBuilder Architecture
+
+ImageBuilder is a CLI tool that orchestrates Docker image builds using manifest files (`manifest.json`). Key concepts:
+
+- **Manifest schema**: Defined in `src/ImageBuilder/Models/Manifest/Manifest.cs`
+- **Image info files**: Track build metadata (`ImageArtifactDetails` class)
+- **Multi-platform support**: Handles Linux (Alpine, Ubuntu, Azure Linux) and Windows (Server Core, Nano Server)
+- **Multi-architecture**: Supports amd64, arm64, arm32
+- **Dependency graphs**: Builds images in correct order based on base image dependencies
+
+## Infrastructure Synchronization
+
+**Critical**: Files in `eng/docker-tools/` are synchronized across repositories by automation. Changes made directly in consuming repositories will be overwritten.
+
+- **To modify infrastructure**: Submit changes to this repository (dotnet/docker-tools)
+- **Consuming repos**: dotnet-docker, dotnet-buildtools-prereqs-docker, dotnet-framework-docker
+- **Sync frequency**: Updates are pushed automatically when merged to main
+
+## Common Workflows
+
+### Local Development
+```bash
+# Build specific images locally
+./eng/docker-tools/build.ps1 -OS "alpine" -Architecture "arm64"
+
+# Run ImageBuilder directly
+./eng/docker-tools/Invoke-ImageBuilder.ps1 "build --help"
+```
+
+### CI/CD Pipeline
+- **Public PRs**: Build and test in dry-run mode (no registry pushes)
+- **Official builds**: Build → Test → Publish to Microsoft Artifact Registry (MAR)
+- **Matrix generation**: `generateBuildMatrix` command creates parallel build jobs
+- **Stages control**: Use `stages` variable to run specific pipeline stages
+
+## Key Files to Keep in Sync
+
+When updating functionality, these files often need coordinated changes:
+
+1. **ImageBuilder source code** (`src/ImageBuilder/`)
+2. **Pipeline templates** (`eng/docker-tools/templates/`)
+3. **PowerShell scripts** (`eng/docker-tools/*.ps1`)
+4. **DEV-GUIDE.md** - Document changes here!
+5. **Manifest schema docs** (`documentation/manifest-file.md`)
+
+## Additional Context
+
+- **.NET SDK Version**: Defined in `global.json` (currently 9.0.300)
+- **Arcade SDK**: Uses Microsoft.DotNet.Arcade.Sdk for build infrastructure
+- **Testing**: xUnit for unit tests
+- **Container registry**: Uses Azure Container Registry (ACR) for staging
+- **Final publishing**: Microsoft Artifact Registry (MAR) and Docker Hub
+
+## Remember
+
+- Keep DEV-GUIDE.md updated with infrastructure changes
+- Maintain backward compatibility when possible for consuming repositories
+- Test changes locally before submitting PRs
+- Follow existing code patterns and conventions
+- All warnings are treated as errors - fix them

From 597629711d9c464c5c903160b90e4a716de1a650 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:34:33 +0000
Subject: [PATCH 3/7] Fix PowerShell code block syntax and use explicit
 -WorkingDirectory parameter

Co-authored-by: mthalman <15789599+mthalman@users.noreply.github.com>
---
 .github/copilot-instructions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 9368d428f..ac7cb993b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -89,7 +89,7 @@ This runs: restore → build → test → pack
 ### Build ImageBuilder container image
 ```bash
 # From root
-pwsh -wd ./src -f src/build.ps1
+pwsh -WorkingDirectory ./src -f src/build.ps1
 ```
 
 ### Run tests
@@ -122,7 +122,7 @@ ImageBuilder is a CLI tool that orchestrates Docker image builds using manifest
 ## Common Workflows
 
 ### Local Development
-```bash
+```powershell
 # Build specific images locally
 ./eng/docker-tools/build.ps1 -OS "alpine" -Architecture "arm64"
 

From 159e3c306d4d328306018d15e9d17d94e1d4e699 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:36:56 +0000
Subject: [PATCH 4/7] Simplify build and test command examples in
 copilot-instructions.md

Co-authored-by: mthalman <15789599+mthalman@users.noreply.github.com>
---
 .github/copilot-instructions.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ac7cb993b..50e03b782 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -87,18 +87,23 @@ build.cmd
 This runs: restore → build → test → pack
 
 ### Build ImageBuilder container image
-```bash
-# From root
-pwsh -WorkingDirectory ./src -f src/build.ps1
+```powershell
+# From src/ directory
+./build.ps1
+
+# Or from root directory
+pwsh -f ./src/build.ps1
 ```
 
 ### Run tests
 ```bash
-# From root
+# From root - runs restore, build, test, and pack
 ./build.sh --test
+```
 
-# From src/
-pwsh -f run-tests.ps1
+```powershell
+# From src/ - runs ImageBuilder tests specifically
+./run-tests.ps1
 ```
 
 ## ImageBuilder Architecture

From 2d2bb6ccfa6f85c0ff7fe53ecb6e6b3b72266431 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 17:20:57 +0000
Subject: [PATCH 5/7] Add code review guidelines section with documentation
 update reminders

Co-authored-by: lbussell <36081148+lbussell@users.noreply.github.com>
---
 .github/copilot-instructions.md | 38 +++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 50e03b782..81f9dccb0 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -32,6 +32,44 @@ This repository contains common tools for .NET Docker repositories, with the pri
 
 3. **Document breaking changes**: If changes affect consuming repositories (dotnet-docker, dotnet-buildtools-prereqs-docker, dotnet-framework-docker), clearly document migration steps.
 
+## Code Review Guidelines
+
+When making changes to this repository, always consider which documentation needs to be updated alongside your code changes. Common patterns:
+
+### Changes to Shared Pipeline Templates
+
+When modifying files in `eng/docker-tools/` (PowerShell scripts, Azure Pipeline templates, workflow changes):
+- **Update `eng/docker-tools/DEV-GUIDE.md`** with any new commands, changed parameters, or updated workflows
+- Ensure examples in DEV-GUIDE.md remain accurate and functional
+- Document any breaking changes that affect consuming repositories
+
+### Changes to Repository Build Scripts
+
+When modifying `build.sh`, `build.cmd`, or the build process:
+- **Update `README.md` section "Building locally"** to reflect new build commands or options
+- Keep instructions accurate for both Windows and Linux/Mac users
+- Document any new prerequisites or environment requirements
+
+### Changes to ImageBuilder
+
+When modifying ImageBuilder source code (`src/ImageBuilder/`), build scripts, or processes:
+- **Update `src/README.md`** to reflect changes in:
+  - How to build the ImageBuilder container image
+  - New commands or command options
+  - Changed build processes or requirements
+- Update `documentation/manifest-file.md` if manifest schema changes
+- Ensure code examples and usage patterns remain current
+
+### General Documentation Updates
+
+Always ask yourself:
+- Does this change affect how developers use the tool?
+- Does this change affect the build or test process?
+- Does this change require updates to examples or workflows in documentation?
+- Are there breaking changes that need to be communicated?
+
+If the answer to any of these is "yes", update the relevant documentation as part of your PR.
+
 ## Coding Standards
 
 ### C# Code (.cs files)

From 7586446f94c1e48f85d29acaf1254c21d087a8a5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 18:35:02 +0000
Subject: [PATCH 6/7] Remove hardcoded SDK version number from
 copilot-instructions.md

Co-authored-by: mthalman <15789599+mthalman@users.noreply.github.com>
---
 .github/copilot-instructions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 81f9dccb0..489f38257 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -191,7 +191,7 @@ When updating functionality, these files often need coordinated changes:
 
 ## Additional Context
 
-- **.NET SDK Version**: Defined in `global.json` (currently 9.0.300)
+- **.NET SDK Version**: Defined in `global.json`
 - **Arcade SDK**: Uses Microsoft.DotNet.Arcade.Sdk for build infrastructure
 - **Testing**: xUnit for unit tests
 - **Container registry**: Uses Azure Container Registry (ACR) for staging

From c9e8a17aa653d6b44e860d95e74db26e2862b669 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Dec 2025 18:53:43 +0000
Subject: [PATCH 7/7] Remove code formatting and style preferences from
 copilot-instructions.md

Co-authored-by: lbussell <36081148+lbussell@users.noreply.github.com>
---
 .github/copilot-instructions.md | 41 ---------------------------------
 1 file changed, 41 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 489f38257..aceeea963 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -70,47 +70,6 @@ Always ask yourself:
 
 If the answer to any of these is "yes", update the relevant documentation as part of your PR.
 
-## Coding Standards
-
-### C# Code (.cs files)
-
-- **License header required**: All C# files must start with:
-  ```csharp
-  // Licensed to the .NET Foundation under one or more agreements.
-  // The .NET Foundation licenses this file to you under the MIT license.
-  ```
-- **Indentation**: 4 spaces (no tabs)
-- **Braces**: Allman style - opening braces on new lines
-- **Field naming**:
-  - Private/internal fields: `_camelCase` prefix
-  - Static fields: `s_camelCase` prefix
-  - Constants: `PascalCase`
-- **Avoid `this.`** unless necessary
-- **Use `var`** only when type is clear
-- **Prefer keywords** over BCL types (e.g., `string` not `String`)
-- **TreatWarningsAsErrors**: Enabled - all warnings must be resolved
-- **LangVersion**: Uses latest C# language features
-
-### PowerShell Scripts (.ps1 files)
-
-- Follow existing patterns in `eng/docker-tools/` scripts
-- Use `Invoke-ImageBuilder.ps1` as the central entry point for ImageBuilder operations
-- Support common filtering parameters: `-OS`, `-Architecture`, `-Version`, `-Paths`
-
-### JSON and YAML
-
-- **JSON**: 2-space indentation
-- **YAML**: 2-space indentation
-- Manifest files follow the schema defined in `src/ImageBuilder/Models/Manifest/`
-
-### Other Files
-
-- **Final newline**: All files must end with a newline
-- **Trim trailing whitespace**: Required
-- **Line endings**:
-  - Shell scripts (`.sh`): LF
-  - Batch files (`.cmd`, `.bat`): CRLF
-
 ## Building and Testing
 
 ### Build the entire repository