Merge main into live

.github/copilot-instructions.md

@@ -0,0 +1,41 @@
+When writing documentation, follow the following guidelines:
+
+Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
+
+Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+
+Headings should be in sentence case, not title case. Don't use gerunds in titles.
+
+Use the active voice whenever possible, and second person to address the reader directly.
+
+Use a conversational tone with contractions.
+
+Be concise.
+
+Break up long sentences.
+
+Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value."
+
+Do not use "we" or "our" to refer to the authors of the documentation.
+
+Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method."
+
+Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception."
+
+Use the Oxford comma in lists of three or more items.
+
+Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists.
+
+Use **bold** when referring to UI elements. Use `code style` for file names and folders, custom types, and other text that should never be localized.
+
+Put raw URLs within angle brackets.
+
+Include links to related topics and resources where appropriate. Use relative links if the target file lives in this repo. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link.
+
+When mentioning APIs, use cross-references to the API documentation. These links are formatted as <xref:api-doc-ID>. You can find the API doc ID in the XML files in the https://github.com/dotnet/dotnet-api-docs repository. For types, the doc ID is the value of the `Value` attribute of the `<TypeSignature>` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `<MemberSignature>` element where the `Language` attribute value is `DocId`. Omit the first two characters of the DocId. For example, the xref link for System.String is <xref:System.String>.
+
+If you're assigned a GitHub issue that's labeled "breaking-change", include the prompt directions in the .github/prompts/breaking-change.md file in this repo.
+
+If you include a code snippet that's more than 6 lines long, put it in a separate .cs file in a folder named "snippets" in the same folder as the document. Within the "snippets" folder, add a new directory with the name of the document. For example, if the document is named "my-doc.md", create a folder named "snippets/my-doc" folder. Also add a simple .csproj file to the same directory that targets the latest version of .NET. It can be a library or executable project.
+
+If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name.

.github/prompts/breaking-change.md

@@ -0,0 +1,61 @@
+When you're assigned an issue that's labeled "breaking-change", or when you're given a link to an issue that's labeled "breaking-change" and asked to create a new breaking change document, follow the following guidelines:
+
+The document should be in Markdown format.
+
+Ignore all breaking change documentation under https://github.com/dotnet/docs/tree/main/docs/framework/migration-guide - that is for legacy .NET Framework breaking changes. Modern .NET breaking changes live in the https://github.com/dotnet/docs/tree/main/docs/core/compatibility folder and its subfolders.
+
+Rephrase all content to be clear and concise, if necessary.
+
+Describe previous behavior in past tense and new behavior in present tense.
+
+The document should start with the following header, including --- characters. Placeholder text is shown in angle brackets.
+
+   ---
+   title: "Breaking change - <A concise descriptive title of the breaking change>"
+   description: "Learn about the breaking change in <product/version without the preview number> where <very brief description>."
+   ms.date: <Today's date>
+   ai-usage: ai-assisted
+   ms.custom: <URL of the issue>
+   ---
+
+After the header, include the following sections in this order. Use the description in parentheses as a guide for the content of each section.
+
+h1: "(The same title used in the document header, sans 'Breaking Change - ')"
+
+   (An introductory paragraph summarizing the breaking change. Include the major version but not the preview number.)
+
+h2: Version introduced
+
+   (The version in which the breaking change was introduced. Include the preview number here, if given.)
+
+h2: Previous behavior
+
+   (A brief description of the behavior before the change, including an example code snippet if applicable.)
+
+h2: New behavior
+
+   (A brief description of the behavior after the change, including an example code snippet if applicable.)
+
+h2: Type of breaking change
+
+   If the type of breaking change is "behavioral change", add the following sentence (without the backticks): `This is a [behavioral change](../../categories.md#behavioral-change).`
+
+   If the type of breaking change is "source incompatible" or "binary incompatible", add the following sentence (without the backticks): `This change can affect [source compatibility](../../categories.md#source-compatibility).` or `This change can affect [binary compatibility](../../categories.md#binary-compatibility).`
+
+   If the issue lists multiple types of breaking changes, create a single sentence that links to each applicable type, such as "This is both a []() and []() change.". If there is no type of breaking change selected in the issue, write "TODO: Add type of breaking change."
+
+h2: Reason for change
+
+   (The complete reasoning behind the change, including any relevant links.)
+
+h2: Recommended action
+
+   (A brief description of the action or actions that users should take, including example code snippets if applicable.)
+
+h2: Affected APIs
+
+   (A bullet list of APIs that are affected by the change. If there are no affected APIs (or "No response") write "None.". Use xref-style links as described in the copilot-instructions.md file. At the end of each doc ID, add "?displayProperty=fullName", for example "<xref:System.String?displayProperty=fullName>".)
+
+Then, add the new document to both the "By area" and "By version" sections of the TOC file located at https://github.com/dotnet/docs/blob/main/docs/core/compatibility/toc.yml. Also add an entry to the index file under the appropriate area H2 heading in the https://github.com/dotnet/docs/blob/main/docs/core/compatibility/10.0.md file by adding a row to the table (create a new heading/table if it doesn't exist yet).
+
+Next, create a pull request. In the description, include the text "Fixes #\<issue-number>", where "issue-number" is the GitHub issue number.