diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..b927e7e422 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,41 @@ +When writing documentation or editing .md files, 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 . 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 `` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `` 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 . + +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. \ No newline at end of file diff --git a/.github/prompts/breaking-change.md b/.github/prompts/breaking-change.md new file mode 100644 index 0000000000..68863f018b --- /dev/null +++ b/.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. + +.NET Aspire breaking changes live in the https://github.com/dotnet/docs-aspire/tree/main/docs/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 frontmatter, including `---` characters. Placeholder text is shown in angle brackets. + + --- + title: "Breaking change - " + description: "Learn about the breaking change in where ." + ms.date: + ai-usage: ai-assisted + ms.custom: + --- + +After the frontmatter, 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 "".) + +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-aspire/tree/main/docs/compatibility/toc.yml. Also add an entry to the index file under the appropriate area H2 heading in the https://github.com/dotnet/docs-aspire/tree/main/docs/compatibility/9.3/index.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 #\", where "issue-number" is the GitHub issue number.