You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Restructure copilot-instructions.md to emphasize mandatory baseline build (#123067)
# Description
The coding agent was skipping baseline setup steps before
building/running tests, causing "missing testhost" and "shared
framework" errors. Restructured instructions to make baseline build
impossible to miss.
**Key changes:**
- Moved baseline build to **first section** after title with ⚠️
MANDATORY heading
- Added explicit cause-effect: skipping causes testhost/shared framework
errors
- Replaced verbose bullet lists with **quick-scan tables** for component
ID and build commands
- Added gate condition: "Only proceed after baseline build succeeds"
- Reduced document from ~325 to ~185 lines (~43% reduction)
- Removed table of contents and verbose iterative strategy section
(standard behavior, not actionable)
- Consolidated troubleshooting and references into compact table format
**Restored guidance per feedback:**
- WASM/WASI library detection logic (condensed)
- "Checkout main branch" instruction before baseline build
- Instruction to switch back to working branch after baseline build
- Success criteria (exit code 0, zero test failures)
- Library test project structure guidance with discovery command
- "Target does not exist" troubleshooting entry
- Log collection guidance for failure reporting
**Added new components per feedback:**
- Added entries for `src/tools`, `src/native/managed`, `src/tasks`,
`src/tests` to component identification table
- Added baseline build commands for Tools, Build Tasks, and Runtime
Tests
- Added workflow sections for Tools, Build Tasks, and Runtime Tests with
build/test commands
# Customer Impact
N/A - Internal tooling instructions only.
# Regression
No.
# Testing
Documentation-only change. Verified no trailing whitespace per markdown
guidelines.
# Risk
Low. No code changes. Core guidance retained; only organization and
emphasis changed.
# Package authoring no longer needed in .NET 9
IMPORTANT: Starting with .NET 9, you no longer need to edit a NuGet
package's csproj to enable building and bump the version.
Keep in mind that we still need package authoring in .NET 8 and older
versions.
<!-- START COPILOT CODING AGENT SUFFIX -->
<!-- START COPILOT ORIGINAL PROMPT -->
<details>
<summary>Original prompt</summary>
> Our instructions aren't working as well as we'd like. In particular,
the coding agent isn't doing the baseline setup steps before it tries
building/running tests. Please make whatever changes are needed to make
these instructions more effectove. That could include anything from
minor tweaks to an overhaul. Please retain the core instructions and
guidance; focus on organization, brevity, relevance to copilot, etc
</details>
<!-- START COPILOT CODING AGENT TIPS -->
---
💬 We'd love your input! Share your thoughts on Copilot coding agent in
our [2 minute survey](https://gh.io/copilot-coding-agent-survey).
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>
-[8.2. Windows Command Equivalents](#82-windows-command-equivalents)
51
-
-[8.3. References](#83-references)
36
+
## ⚠️ MANDATORY: Run Baseline Build First
52
37
53
-
## 1. Prerequisites
38
+
**You MUST complete these steps BEFORE making any code changes.** Skipping this causes "missing testhost" and "shared framework" errors that waste time.
54
39
55
-
These steps need to be done **before** applying any code changes.
40
+
### Step 1: Identify Your Component
56
41
57
-
### 1.1. Determine Affected Components
42
+
Based on file paths you will modify:
58
43
59
-
Identify which components will be impacted by the changes. If in doubt, analyze the paths of the files to be updated:
44
+
| Files Changed | Component |
45
+
|---------------|-----------|
46
+
|`src/coreclr/`| CoreCLR |
47
+
|`src/mono/`| Mono |
48
+
|`src/libraries/` (no Browser/WASM or WASI targets) | Libraries |
49
+
|`src/libraries/` with Browser/WASM or WASI targets in the affected `.csproj`| WASM/WASI Libraries |
50
+
|`src/native/corehost/`, `src/installer/`| Host |
51
+
|`src/tools`| Tools |
52
+
|`src/native/managed`| Tools |
53
+
|`src/tasks`| Build Tasks |
54
+
|`src/tests`| Runtime Tests |
55
+
| None of the above | Docs/infra only — skip build steps |
60
56
61
-
-**CoreCLR (CLR):** Changes in `src/coreclr/` or `src/tests/`
62
-
-**Mono Runtime:** Changes in `src/mono/`
63
-
-**Libraries:** Changes in `src/libraries/`
64
-
-**WASM/WASI Libraries:** Changes in `src/libraries/`*and* the affected library targets WASM or WASI *and* the changes are included for the target (see below for details).
65
-
-**Host:** Changes in `src/native/corehost/`, `src/installer/managed/`, or `src/installer/tests/`
66
-
- If none above apply, it is most possibly an infra-only or a docs-only change. Skip build and test steps.
57
+
**WASM/WASI Library Detection:** A change under `src/libraries/` is WASM/WASI-relevant if the library's `.csproj` has explicit Browser/WASM or WASI targets (`TargetFrameworks`, `TARGET_BROWSER`, `TARGET_WASI` constants, or `Condition` attributes referencing `browser`/`wasi`), **and** the changed file is not excluded from those targets via `Condition` on `<ItemGroup>` or `<Compile>`.
67
58
68
-
**WASM/WASI Library Change Detection**
59
+
### Step 2: Run the Baseline Build (from repo root)
69
60
70
-
A change is considered WASM/WASI-relevant if:
61
+
**First, checkout the `main` branch** to establish a known-good baseline, then run the appropriate build command:
71
62
72
-
- The relevant `.csproj` contains explicit Browser/WASM or WASI targets (look for `<TargetFrameworks>`, `$(TargetPlatformIdentifier)`, or `Condition` attributes referencing `browser` or `wasi`, as well as `TARGET_BROWSER` or `TARGET_WASI` constants), **and**
73
-
- The changed file is not excluded from the build for that platform in any way with a `Condition` attribute on `<ItemGroup>` or `<Compile>`.
Before applying any changes, ensure you have a full successful build of the needed runtime+libraries as a baseline.
80
-
81
-
1. Checkout `main` branch
74
+
For System.Private.CoreLib changes, use `-rc checked` instead of `-rc release` for asserts.
82
75
83
-
2. From the repository root, run the build depending on the affected component. If multiple components are affected, subsequently run and verify the builds for all of them.
If changes are being made in the System.Private.CoreLib library, you can follow the Libraries steps, but you may want to use "-rc checked" instead of "-rc release"; that will result in asserts being included in the build rather than excluded.
76
+
⏱️ **This build can take up to 40 minutes.** Do not cancel unless no output for 5+ minutes.
90
77
91
-
3. Verify the build completed without error.
92
-
-_If the baseline build failed, report the failure and don't proceed with the changes._
- Verify SDK Version: `dotnet --version` should match `sdk.version` in `global.json`.
80
+
```bash
81
+
export PATH="$(pwd)/.dotnet:$PATH"
82
+
dotnet --version # Should match sdk.version in global.json
83
+
```
97
84
98
-
5. Switch back to the working branch.
85
+
**Only proceed with changes after the baseline build succeeds.** If it fails, report the failure and stop. After the baseline build, switch back to your working branch before making changes.
99
86
100
87
---
101
88
102
-
## 2. Iterative Build and Test Strategy
103
-
104
-
1. Apply the intended changes
105
-
106
-
2.**Attempt Build.** If the build fails, attempt to fix and retry the step (up to 5 attempts).
107
-
108
-
3.**Attempt Test.**
109
-
- If a test _build_ fails, attempt to fix and retry the step (up to 5 attempts).
110
-
- If a test _run_ fails,
111
-
- Determine if the problem is in the test or in the source
112
-
- If the problem is in the test, attempt to fix and retry the step (up to 5 attempts).
113
-
- If the problem is in the source, reconsider the full changeset, attempt to fix and repeat the workflow.
114
-
115
-
4.**Workflow Iteration:**
116
-
- Repeat build and test up to 5 cycles.
117
-
- If issues persist after 5 workflow cycles, report failure.
118
-
- If the same error persists after each fix attempt, do not repeat the same fix. Instead, escalate or report with full logs.
119
-
120
-
When retrying, attempt different fixes and adjust based on the build/test results.
121
-
122
-
### 2.1. Success Criteria
123
-
124
-
-**Build:**
125
-
- Completes without errors.
126
-
- Any non-zero exit code from build commands is considered a failure.
127
-
128
-
-**Tests:**
129
-
- All tests must pass (zero failures).
130
-
- Any non-zero exit code from test commands is considered a failure.
131
-
132
-
-**Workflow:**
133
-
- On success: Report completion
134
-
- Otherwise: Report error(s) with logs for diagnostics.
135
-
- Collect logs from `artifacts/log/` and the console output for both build and test steps.
136
-
- Attach relevant log files or error snippets when reporting failures.
89
+
## Component-Specific Workflows
137
90
138
-
---
91
+
After completing the baseline build above, use the appropriate workflow for your changes.
92
+
All commands must complete with exit code 0, and all tests must pass with zero failures.
Test projects are typically at: `tests/<LibraryName>.Tests.csproj` or `tests/<LibraryName>.Tests/<LibraryName>.Tests.csproj`, or under `tests/FunctionalTests/`, `tests/UnitTests/`, etc. Use `find tests -name '*.Tests.csproj'` to discover them.
149
106
150
-
- More info can be found in the dedicated workflow docs:
- Refer to the sections [5.1. How To: Identify Affected Libraries](#51-how-to-identify-affected-libraries) and [5.2. How To: Build and Test Specific Library](#52-how-to-build-and-test-specific-library) below.
When working on changes limited to a specific library, do not complete without at least running all tests for that library and confirming they pass. For example if you are working within "System.Text.RegularExpressions" then make sure after your last edits that all the test libraries under `src\libraries\System.Text.RegularExpressions\tests` pass. It is OK to filter to relevant specific tests during your work, but before returning, ensure that, at least, ALL tests for the library do pass.
- More info can be found in the dedicated workflow docs:
268
-
-[Building and running host tests](/docs/workflow/testing/host/testing.md)
269
-
270
-
---
271
-
272
-
## 8. Additional Notes
273
-
274
-
### 8.1. Troubleshooting
275
-
276
-
-**Shared Framework Missing**
277
-
278
-
- If the build fails with an error "The shared framework must be built before the local targeting pack can be consumed.", build both the runtime (clr or mono) and the libs.
279
-
E.g., from the repo root, run `./build.sh clr+libs -rc release` if working on Libraries on CoreCLR. To find the applicable command, refer to the section [1.2. Baseline Setup](#12-baseline-setup).
280
-
281
-
-**Testhost Is Missing**
282
-
283
-
- If a test run fails with errors indicating a missing testhost, such as:
284
-
- "Failed to launch testhost with error: System.IO.FileNotFoundException", or
285
-
- "artifacts/bin/testhost/... No such file or directory",
286
-
that means some of the prerequisites were not built.
287
-
288
-
- To resolve, build both the appropriate runtime (clr or mono) and the libs as a single command before running tests.
289
-
E.g., from the repo root, run `./build.sh clr+libs -rc release` before testing Libraries on CoreCLR. To find the applicable command, refer to the section [1.2. Baseline Setup](#12-baseline-setup).
290
-
291
-
-**Build Timeout**
292
-
293
-
- Do not fail or cancel initial `./build.sh` builds due to timeout unless at least 40 minutes have elapsed.
294
-
A full `clr+libs` build from scratch can take up to 32 minutes or more on some systems.
295
-
296
-
- Only wait for long-running `./build.sh` commands if they continue to produce output.
297
-
If there is no output for 5 minutes, assume the build is stuck and fail early.
298
-
299
-
-**Target Does Not Exist**
300
-
301
-
- Avoid specifying a target framework when building unless explicitly asked.
302
-
Build should identify and select the appropriate `$(NetCoreAppCurrent)` automatically.
303
-
304
-
---
305
-
306
-
### 8.2. Windows Command Equivalents
307
-
308
-
- Use `build.cmd` instead of `build.sh` on Windows.
309
-
- Set PATH: `set PATH=%CD%\.dotnet;%PATH%`
310
-
- All other commands are similar unless otherwise noted.
0 commit comments