Skip to content

Commit e400a2b

Browse files
gewarrengewarren
authored
Merge pull request #52770 from dotnet/main
Merge main into live
2 parents ae72e63 + 9e3c909 commit e400a2b

26 files changed

Lines changed: 753 additions & 279 deletions

File tree

‎.github/prompts/ErrorConsolidation.1.Setup.prompt.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
model: Claude Opus 4.6 (copilot)
3+
agent: agent
4+
description: Creates a new consolidated compiler error/warning article skeleton and TOC entry
5+
tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo']
6+
---
7+
8+
# Create a consolidated error article
9+
10+
You are creating a new consolidated compiler error/warning article. The user will provide:
11+
12+
- **Destination filename** — the name of the new `.md` file (e.g., `overloaded-operator-errors.md`)
13+
- **Theme description** — a short description of the theme (e.g., "overflow, underflow, and checked and unchecked operators")
14+
- **Seed error codes** (optional) — a list of new, undocumented error codes to include from the start
15+
16+
## Step 1: Ask for TOC placement
17+
18+
Ask the user: *Where in the TOC should this entry be placed? Provide the name or href of the existing entry it should appear after.*
19+
20+
Wait for the user's answer before proceeding.
21+
22+
## Step 2: Create the destination file
23+
24+
Create the file at `docs/csharp/language-reference/compiler-messages/{destination-filename}` with this structure:
25+
26+
```yaml
27+
---
28+
title: "Resolve errors and warnings related to {theme description}"
29+
description: "This article helps you diagnose and correct compiler errors and warnings related to {theme description}"
30+
f1_keywords:
31+
# populated from seed error codes, sorted numerically
32+
helpviewer_keywords:
33+
# populated from seed error codes, sorted numerically
34+
ms.date: {today's date in MM/DD/YYYY format}
35+
ai-usage: ai-assisted
36+
---
37+
```
38+
39+
Then add the body:
40+
41+
```markdown
42+
# Resolve errors and warnings for {short theme title}
43+
44+
This article covers the following compiler errors and warnings:
45+
46+
<!-- The text in this list generates issues for Acrolinx, because they don't use contractions.
47+
That's by design. The text closely matches the text of the compiler error / warning for SEO purposes.
48+
-->
49+
50+
```
51+
52+
## Step 3: Add the TOC entry
53+
54+
Add an entry in `docs/csharp/language-reference/toc.yml` at the location the user specified. The entry format is:
55+
56+
```yaml
57+
- name: {Short theme title}
58+
href: ./compiler-messages/{destination-filename}
59+
displayName: >
60+
{theme keywords},
61+
{CS codes sorted numerically, comma-separated}
62+
```
63+
64+
Look at neighboring entries in the TOC for style and indentation guidance.
65+
66+
## Step 4: Populate seed error codes (if provided)
67+
68+
If the user provided seed error codes, process them as a batch:
69+
70+
For each error code:
71+
72+
1. Extract the numeric portion (e.g., `CS0220` → `220`).
73+
2. Find the constant with that number in the Roslyn source file `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs`. The constant name maps to the symbolic name.
74+
3. Find the corresponding `<data>` element in `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx` whose `name` attribute matches the `ErrorCodes.cs` constant name exactly, including the `ERR_` or `WRN_` prefix.
75+
4. Read the verbatim error message from the `<value>` child element.
76+
77+
Then update the destination file:
78+
79+
- Add each code to `f1_keywords` and `helpviewer_keywords` in sorted numeric order.
80+
- Add an entry to the error list in the article body. Use this format:
81+
```
82+
- [**CS{NNNN}**](#anchor-tbd): *{verbatim error message}*
83+
```
84+
Use `#anchor-tbd` as the anchor — these will be updated in the Consolidate phase.
85+
**Handling format placeholders:** The Roslyn source message may contain interpolation markers like `'{0}'`, `'{1}'`, etc. Replace these with descriptive terms that keep the text as close to the verbatim message as possible for SEO, while still reading as a coherent sentence. Use generic terms like `'type'`, `'value'`, `'operator'`, `'member'`, or `'method'` based on the context of the error. For example, `Constant value '{0}' cannot be converted to a '{1}'` becomes `Constant value 'value' cannot be converted to a 'type'`. Look at the XML `<comment>` element following the `<value>` (if present) for hints about what each placeholder represents.
86+
- Add each code to the `displayName` in the TOC entry, in sorted numeric order.
87+
88+
For each seed code, also remove it from the `f1_keywords` front matter in `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`.
89+
90+
## Step 5: Present for review
91+
92+
**Stop and present the created skeleton to the user.** Show:
93+
94+
1. The full destination file content
95+
2. The new TOC entry
96+
3. A summary of any codes removed from the catch-all file
97+
98+
Wait for user approval before ending. Do not proceed to merging or searching — those are separate prompt files.

‎.github/prompts/ErrorConsolidation.2.MergeExisting.prompt.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
model: Claude Opus 4.6 (copilot)
3+
agent: agent
4+
description: Merges existing standalone error articles into a consolidated article
5+
tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo']
6+
---
7+
8+
# Merge existing error articles into a consolidated article
9+
10+
You are merging existing standalone compiler error/warning articles into a consolidated destination file. The user will provide:
11+
12+
- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/`
13+
- **Theme description** — the theme these errors relate to
14+
- **Source files** — a list of existing error article files to merge (already approved by the user)
15+
16+
## Key file locations
17+
18+
- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}`
19+
- **TOC file**: `docs/csharp/language-reference/toc.yml`
20+
- **Redirection file**: `.openpublishing.redirection.csharp.json`
21+
- **Redirect script**: `.github/skills/redirect-article/scripts/create-redirect-entry.ps1`
22+
23+
## Batch process: for each source file
24+
25+
Process the entire approved list. For each source file:
26+
27+
### 1. Read and extract
28+
29+
Read the source file and extract:
30+
- The error code (from the filename or front matter, e.g., `CS0220`)
31+
- The error message: extract the numeric portion of the error code, find the constant with that number in `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs`, then find the matching `<data>` element in `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx` and read the verbatim text from its `<value>` child element.
32+
- The article body content (everything after the front matter and H1)
33+
34+
### 2. Update the destination file
35+
36+
**Front matter:**
37+
- Add the error code to `f1_keywords` in sorted numeric order.
38+
- Add the error code to `helpviewer_keywords` in sorted numeric order.
39+
40+
**Error list:**
41+
- Add an entry to the error list at the top of the article, in sorted numeric order. Format:
42+
```
43+
- [**CS{NNNN}**](#anchor-tbd): *{verbatim compiler error message}*
44+
```
45+
Use `#anchor-tbd` as a placeholder anchor — these will be finalized in the Consolidate phase.
46+
**Handling format placeholders:** The Roslyn source message may contain interpolation markers like `'{0}'`, `'{1}'`, etc. Replace these with descriptive terms that keep the text as close to the verbatim message as possible for SEO, while still reading as a coherent sentence. Use generic terms like `'type'`, `'value'`, `'operator'`, `'member'`, or `'method'` based on the context of the error. For example, `Constant value '{0}' cannot be converted to a '{1}'` becomes `Constant value 'value' cannot be converted to a 'type'`. Look at the XML `<comment>` element following the `<value>` (if present) for hints about what each placeholder represents.
47+
48+
**Content:**
49+
- Add the source file's content as a new H2 section at the end of the destination file:
50+
```markdown
51+
## CS{NNNN}
52+
53+
{source article content, adapted to fit as a section rather than standalone article}
54+
```
55+
Remove any front matter, H1 heading, and `See also` sections from the pasted content. Adjust heading levels (H2 in the source becomes H3, etc.).
56+
57+
### 3. Create a redirect
58+
59+
Use the `create-redirect-entry.ps1` script to add a redirect from the source file to the destination:
60+
61+
```powershell
62+
./.github/skills/redirect-article/scripts/create-redirect-entry.ps1 `
63+
-RedirectionFile ".openpublishing.redirection.csharp.json" `
64+
-SourcePath "docs/csharp/language-reference/compiler-messages/{source-filename}" `
65+
-RedirectUrl "/dotnet/csharp/language-reference/compiler-messages/{destination-filename-without-extension}"
66+
```
67+
68+
If the source file is in `docs/csharp/misc/`, adjust the `SourcePath` accordingly.
69+
70+
### 4. Update the TOC
71+
72+
In `docs/csharp/language-reference/toc.yml`:
73+
- Add the error code to the `displayName` for the destination file entry, maintaining numeric sort order.
74+
- Find and remove the TOC entry for the source file (the `- name:` / `href:` block that references it).
75+
76+
### 5. Delete the source file
77+
78+
Delete the source markdown file from the repository.
79+
80+
## After processing all files
81+
82+
Present a summary:
83+
- List of all source files merged
84+
- Count of error codes added to the destination
85+
- List of redirects created
86+
- List of TOC entries removed
87+
88+
Do not proceed to searching or consolidation — those are separate prompt files.

‎.github/prompts/ErrorConsolidation.3.Search.prompt.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
model: Claude Opus 4.6 (copilot)
3+
agent: agent
4+
description: Searches existing docs and Roslyn source for additional related error codes
5+
tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo']
6+
---
7+
8+
# Search for additional related error codes
9+
10+
You are searching for error codes related to a theme that may have been missed during initial consolidation. The user will provide:
11+
12+
- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/`
13+
- **Theme description** — the theme to search for
14+
15+
## Key file locations
16+
17+
- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}`
18+
- **TOC file**: `docs/csharp/language-reference/toc.yml`
19+
- **Catch-all file**: `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`
20+
- **Roslyn ErrorCodes**: `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs`
21+
- **Roslyn Resources**: `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx`
22+
23+
## Phase A: Search existing documentation
24+
25+
1. Read the destination file to collect all error codes already included.
26+
2. Search all files whose names start with `cs` in these folders:
27+
- `docs/csharp/language-reference/compiler-messages/`
28+
- `docs/csharp/misc/`
29+
3. For each candidate file, read its content and determine whether the error it documents relates to the theme.
30+
4. Build a list of candidate files with their error codes and a brief reason why they match.
31+
32+
**Present the candidate list to the user and stop.** Format the list as:
33+
34+
```
35+
| File | Error Code | Reason |
36+
|------|-----------|--------|
37+
| cs0220.md | CS0220 | Describes compile-time overflow |
38+
```
39+
40+
Tell the user: *Review this list. Approve the files you want merged, then run `ErrorConsolidation.2.MergeExisting` with the approved list.*
41+
42+
**Wait for the user to respond before proceeding to Phase B.**
43+
44+
## Phase B: Search undocumented errors in the catch-all file
45+
46+
1. Read the `f1_keywords` front matter from `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`.
47+
2. For each error code listed:
48+
a. Extract the numeric portion (e.g., `CS0463` → `463`).
49+
b. Find the constant with that number in `ErrorCodes.cs`. The constant will look like `ERR_SomeName = NNNN` or `WRN_SomeName = NNNN`.
50+
c. Find the corresponding `<data>` element in `CSharpResources.resx` whose `name` attribute matches the constant name (e.g., `ERR_SomeName`).
51+
d. Read the verbatim error message from the `<value>` child element.
52+
3. Filter the results to only those whose error message relates to the theme.
53+
4. Exclude any codes already in the destination file.
54+
55+
**Present the filtered list to the user and stop.** Format as:
56+
57+
```
58+
| Error Code | Error Message |
59+
|-----------|--------------|
60+
| CS0463 | Evaluation of the decimal constant expression failed |
61+
| CS1021 | Integral constant is too large |
62+
```
63+
64+
Tell the user: *Review this list. Tell me which error codes to add.*
65+
66+
**Wait for the user to respond before proceeding to Phase C.**
67+
68+
## Phase C: Batch add approved error codes
69+
70+
For each approved error code:
71+
72+
1. **Update destination front matter:**
73+
- Add the code to `f1_keywords` in sorted numeric order.
74+
- Add the code to `helpviewer_keywords` in sorted numeric order.
75+
76+
2. **Update the error list** in the destination file body:
77+
- Add an entry in sorted numeric order:
78+
```
79+
- [**CS{NNNN}**](#anchor-tbd): *{verbatim error message from CSharpResources.resx}*
80+
**Handling format placeholders:** The Roslyn source message may contain interpolation markers like `'{0}'`, `'{1}'`, etc. Replace these with descriptive terms that keep the text as close to the verbatim message as possible for SEO, while still reading as a coherent sentence. Use generic terms like `'type'`, `'value'`, `'operator'`, `'member'`, or `'method'` based on the context of the error. For example, `Constant value '{0}' cannot be converted to a '{1}'` becomes `Constant value 'value' cannot be converted to a 'type'`. Look at the XML `<comment>` element following the `<value>` (if present) for hints about what each placeholder represents.
81+
```
82+
83+
3. **Update the TOC:**
84+
- Add the code to the `displayName` for the destination file entry in `docs/csharp/language-reference/toc.yml`, maintaining numeric sort order.
85+
86+
4. **Remove from catch-all file:**
87+
- Remove the code from `f1_keywords` in `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`.
88+
89+
No redirections are needed for these error codes — they had no standalone articles.
90+
91+
Present a summary of all changes made.

‎.github/prompts/ErrorConsolidation.4.Consolidate.prompt.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
model: Claude Opus 4.6 (copilot)
3+
agent: agent
4+
description: Reorganizes individual error H2s into thematic sections with resolution focus
5+
tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo']
6+
---
7+
8+
# Consolidate error sections and rewrite for resolution
9+
10+
You are reorganizing a consolidated error article so individual per-error H2s become thematic H2 sections focused on resolution. The user will provide:
11+
12+
- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/`
13+
14+
## Key file locations
15+
16+
- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}`
17+
- **Reference examples**: Other `*-errors.md` files in the same folder (study these for structural patterns)
18+
19+
## Phase A: Propose themes
20+
21+
1. Read the destination file and identify all error codes and their current H2 sections.
22+
2. Read 2-3 other consolidated error files in `docs/csharp/language-reference/compiler-messages/` to understand the expected structure and tone.
23+
3. Group the error codes into themes based on their error messages, underlying language rules, and resolution strategies. Each theme should represent a coherent set of related diagnostics.
24+
4. Propose the list of themes with:
25+
- A theme title (which becomes the H2 heading and anchor)
26+
- The included error codes
27+
- A one-sentence rationale for the grouping
28+
29+
**Present the theme list to the user and stop.** Format as:
30+
31+
```
32+
### Proposed themes
33+
34+
1. **Operator signature requirements** (`#operator-signature-requirements`)
35+
- CS0448, CS0559, CS0562, CS0563, CS0564, CS0567, CS0590
36+
- These errors all relate to invalid parameter or return types in operator declarations.
37+
38+
2. **Overflow and underflow errors** (`#overflow-and-underflow-errors`)
39+
- CS0031, CS0220, CS0221, CS0463, CS0543, CS0594, CS0652, CS1021, CS8778, CS8973
40+
- These errors all involve constant values or operations that exceed type boundaries.
41+
```
42+
43+
Tell the user: *Review and approve each theme. Let me know which to proceed with and any adjustments.*
44+
45+
**Wait for user approval before proceeding to Phase B.**
46+
47+
## Phase B: Build thematic sections
48+
49+
For each approved theme:
50+
51+
### 1. Update the master error list at the top of the file
52+
53+
Each error code in the master list should link to its theme's anchor. Keep the list in **numerical order** by error code. Format:
54+
55+
```markdown
56+
- [**CS{NNNN}**](#{theme-anchor}): *{verbatim compiler error message}*
57+
```
58+
59+
### 2. Create the thematic H2 section
60+
61+
Replace all the individual-error H2s that belong to this theme with a single thematic H2:
62+
63+
```markdown
64+
## {Theme title}
65+
66+
- **CS{NNNN}**: *{verbatim error message}*
67+
- **CS{NNNN}**: *{verbatim error message}*
68+
...
69+
70+
{Resolution-focused content}
71+
```
72+
73+
The error list within the section repeats the codes and messages but **without anchor links** (they're already in the section).
74+
75+
### 3. Write resolution-focused content
76+
77+
The content in each thematic section should focus on **how to correct each error**, not on explaining the language feature. Follow these rules:
78+
79+
- **Link to language reference:** Provide links to language reference articles and C# specification sections that explain the rules these diagnostics enforce. For example, link to `https://github.com/dotnet/docs/blob/main/docs/csharp/language-reference/operators/operator-overloading.md` or the relevant spec section.
80+
- **Write detailed corrections:** For each correction, use a full sentence explaining what to do and why. Put the affected error codes in parentheses, in **bold** style. Example:
81+
> Change the return type of `++` or `--` operators to the containing type or a type derived from it (**CS0448**). The language requires that increment and decrement operators return a value compatible with the containing type so the result can be assigned back to the same variable.
82+
- **No extensive examples:** Remove lengthy code examples. Brief inline code references are acceptable.
83+
- **No H3 headings:** Keep the section flat under the H2.
84+
- **Note obsolete errors:** If any error codes are no longer produced in the latest version of C#, explicitly note that.
85+
- **Incorporate source material:** Where applicable, reuse text or brief examples from the individual H2s you're replacing.
86+
87+
### 4. Remove the old individual H2s
88+
89+
After creating the thematic section, delete all individual-error H2s (`## CS{NNNN}`) that were absorbed into it.
90+
91+
## Final check
92+
93+
After all themes are built:
94+
95+
1. Verify the master error list at the top is still in numerical order.
96+
2. Verify every error code in the front matter has a corresponding entry in the master list.
97+
3. Verify every error code in the master list links to a valid anchor in the article.
98+
4. Verify there are no orphaned H2 sections (individual error H2s that weren't grouped into a theme).

0 commit comments

Comments
 (0)