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
@@ -11,128 +11,128 @@ This document contains general and repository-specific instructions for GitHub C
11
11
12
12
## General Guidelines
13
13
14
-
### Issue Handling
14
+
### 1. Issue Handling
15
15
When creating a PR for an issue:
16
-
1. Read the full issue and all linked references
17
-
2. Study code samples from linked PRs that demonstrate features in the latest .NET pre-release version (e.g., .NET 10 Preview) to ensure that guidance and documentation reflect the latest upcoming changes and best practices.
18
-
3. For labeled issues that have the following labels, follow these guidelines:
19
-
-**new-feature:** State which version introduced the feature
20
-
-**bug:** Focus on correcting technical inaccuracies
21
-
4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, ensure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced.
22
-
5. Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information.
23
-
6. Include the folder structure of the repository, including any important directories or files that are relevant to the project.
24
-
25
-
### Markdown File Naming and Organization
26
-
- 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.
27
-
28
-
### API References and Verification
29
-
- Use `<xref:api-doc-ID>` for API cross-references.
30
-
- The API documentation ID must be verified and sourced from the official XML documentation in dotnet-api-docs, never just infer API documentation IDs by looking for similar patterns.
31
-
- If you cannot verify, state that explicitly in your output.
32
-
33
-
### Links and References
34
-
- For cross-references to other articles within the AspNetCore.Docs repository:
35
-
- Use the xref syntax: `<xref:target-uid>`
36
-
- The "target-uid" of the xref syntax is obtained from the `uid` property value in the YAML front matter of the article's markdown file
37
-
- Examples
38
-
- For a target article `uid` value of `aspnetcore/mvc/overview`, the xref cross-link is `<xref:aspnetcore/mvc/overview>`
39
-
- For a target article `uid` value of `blazor/index`, the xref cross-link is `<xref:blazor/index>`
40
-
41
-
- For non-markdown files (files that don't have the `.md` file extension) within this repository, such as PowerShell scripts and code files:
42
-
- Use relative links with the appropriate file extension
43
-
- Example: `../build-tools/build.ps1` or `./sample.json`
44
-
45
-
- For external links to non-Microsoft sites (MDN, W3C, etc.):
46
-
- Use absolute URLs
47
-
- Remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.)
- For links to Microsoft Learn content in other repositories:
60
-
- Use the relative URL starting with a forward slash
61
-
- Don't include the scheme and the host (example: `https://learn.microsoft.com`) and don't include the locale (example: `en-us`)
62
-
- Example: For the target Learn website URL `https://learn.microsoft.com/en-us/dotnet/core/introduction`, use the relative URL `/dotnet/core/introduction` for the link destination
63
-
64
-
- Never use physical .md file paths in published content
65
-
- Wrong: `../blazor/index.md` or `/aspnet/core/blazor/index.md`
66
-
- Correct: `<xref:blazor/index>`
67
-
- Exception: GitHub-only content (such as README files, contributing guidelines, and other repository documentation that isn't published to learn.microsoft.com) should use an absolute URL to the markdown file (`.md` file extension)
16
+
-[ ] Read the full issue and all linked references
17
+
-[ ] Study code samples from linked PRs that demonstrate features in the latest .NET pre-release version (e.g., .NET 10 Preview) to ensure that guidance and documentation reflect the latest upcoming changes and best practices.
18
+
-[ ] For labeled issues that have the following labels, follow these guidelines:
19
+
-[ ]**new-feature:** State which version introduced the feature
20
+
-[ ]**bug:** Focus on correcting technical inaccuracies
21
+
-[ ] When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, ensure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced.
22
+
-[ ] Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information.
23
+
-[ ] Include the folder structure of the repository, including any important directories or files that are relevant to the project.
24
+
25
+
### 2. Markdown File Naming and Organization
26
+
-[ ]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.
27
+
28
+
### 3. API References and Verification
29
+
-[ ]Use `<xref:api-doc-ID>` for API cross-references.
30
+
-[ ]The API documentation ID must be verified and sourced from the official XML documentation in dotnet-api-docs, never just infer API documentation IDs by looking for similar patterns.
31
+
-[ ]If you cannot verify, state that explicitly in your output.
32
+
33
+
### 4. Links and References
34
+
-[ ]For cross-references to other articles within the AspNetCore.Docs repository:
35
+
-[ ]Use the xref syntax: `<xref:target-uid>`
36
+
-[ ]The "target-uid" of the xref syntax is obtained from the `uid` property value in the YAML front matter of the article's markdown file
37
+
-[ ]Examples
38
+
-[ ]For a target article `uid` value of `aspnetcore/mvc/overview`, the xref cross-link is `<xref:aspnetcore/mvc/overview>`
39
+
-[ ]For a target article `uid` value of `blazor/index`, the xref cross-link is `<xref:blazor/index>`
40
+
41
+
-[ ]For non-markdown files (files that don't have the `.md` file extension) within this repository, such as PowerShell scripts and code files:
42
+
-[ ]Use relative links with the appropriate file extension
43
+
-[ ]Example: `../build-tools/build.ps1` or `./sample.json`
44
+
45
+
-[ ]For external links to non-Microsoft sites (MDN, W3C, etc.):
46
+
-[ ]Use absolute URLs
47
+
-[ ]Remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.)
-[ ]For links to Microsoft Learn content in other repositories:
60
+
-[ ]Use the relative URL starting with a forward slash
61
+
-[ ]Don't include the scheme and the host (example: `https://learn.microsoft.com`) and don't include the locale (example: `en-us`)
62
+
-[ ]Example: For the target Learn website URL `https://learn.microsoft.com/en-us/dotnet/core/introduction`, use the relative URL `/dotnet/core/introduction` for the link destination
63
+
64
+
-[ ]Never use physical .md file paths in published content
65
+
-[ ]Wrong: `../blazor/index.md` or `/aspnet/core/blazor/index.md`
66
+
-[ ]Correct: `<xref:blazor/index>`
67
+
-[ ]Exception: GitHub-only content (such as README files, contributing guidelines, and other repository documentation that isn't published to learn.microsoft.com) should use an absolute URL to the markdown file (`.md` file extension)
68
68
69
69
## Repository-Specific Guidelines
70
-
- Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
71
-
-**Repository Exceptions**:
72
-
- Number ordered lists as "1." for every item (don't use sequential numbers)
73
-
- Use backticks around content specifically for file names (`file.txt`), folders (`folder`), file paths (`folder/file.txt`), custom types (`myVariable`, `MyClass`), raw URLs in the text (`https://www.contoso.com`), URL segments (`/product/id/199`), file extensions (`.razor`), NuGet packages (`Microsoft.AspNetCore.SignalR.Client`), and code that should never be localized
74
-
- For Blazor's Razor components mentioned in article text, use backticks around the name of the component (example: `Counter` component)
75
-
- For any new or updated .md file, ensure the standard frontmatter (metadata) is included as specified in [Metadata for Microsoft Learn documentation.](https://learn.microsoft.com/en-us/contribute/content/metadata)
76
-
- For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included:
77
-
- Metadata `ai-usage: ai-assisted` if any AI assistance was used
78
-
- Place the title metadata first, followed by the remaining metadata lines in alphabetical order. Example: `title`, `author`, `description`, `monikerRange`, `ms.author`, `ms.custom`, `ms.date`, `uid`, `zone_pivot_groups`
79
-
- Metadata `ms.date: <today's date>` with a format of MM/DD/YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters are changed in the file.
70
+
-[ ]Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
71
+
-[ ]**Repository Exceptions**:
72
+
-[ ]Number ordered lists as "1." for every item (don't use sequential numbers)
73
+
-[ ]Use backticks around content specifically for file names (`file.txt`), folders (`folder`), file paths (`folder/file.txt`), custom types (`myVariable`, `MyClass`), raw URLs in the text (`https://www.contoso.com`), URL segments (`/product/id/199`), file extensions (`.razor`), NuGet packages (`Microsoft.AspNetCore.SignalR.Client`), and code that should never be localized
74
+
-[ ]For Blazor's Razor components mentioned in article text, use backticks around the name of the component (example: `Counter` component)
75
+
-[ ]For any new or updated .md file, ensure the standard frontmatter (metadata) is included as specified in [Metadata for Microsoft Learn documentation.](https://learn.microsoft.com/en-us/contribute/content/metadata)
76
+
-[ ]For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included:
77
+
-[ ]Metadata `ai-usage: ai-assisted` if any AI assistance was used
78
+
-[ ]Place the title metadata first, followed by the remaining metadata lines in alphabetical order. Example: `title`, `author`, `description`, `monikerRange`, `ms.author`, `ms.custom`, `ms.date`, `uid`, `zone_pivot_groups`
79
+
-[ ]Metadata `ms.date: <today's date>` with a format of MM/DD/YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters are changed in the file.
- [ ] Set `redirect_document_id` to `false` unless specifically instructed otherwise
105
+
- [ ] Maintain alphabetical order of the `source_path` entries for better organization
106
+
- [ ] Ensure proper JSON formatting with correct commas between entries
107
+
- [ ] When selecting a redirect target, choose the most relevant existing content that would serve the user's original intent
108
+
- [ ] If no direct replacement exists, redirect to a parent category page or related topic
109
109
110
-
### Code Snippets
111
-
- For code snippets longer than 6 lines:
112
-
1. Create a subfolder named after the document the snippet supports.
113
-
1. Create a `snippets` folder inside that subfolder.
114
-
1. For the code file:
115
-
- If the snippet is not version-specific, place the code in a file with the appropriate extension (for example, `.cs` for C#) in the `snippets` folder.
116
-
- If the snippet is version-specific:
117
-
1. Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9).
118
-
1. Place the code in a file with the correct extension inside the version subfolder.
119
-
1. Add a project file (`.csproj`) to the version subfolder targeting the matching .NET version, if necessary to run or build the snippet.
120
-
- Reference snippets using triple-colon syntax:
121
-
- **Use file-relative paths** for snippets located in the same file as the articles that refer to it.
110
+
### 3. Code Snippets
111
+
- [ ] For code snippets longer than 6 lines:
112
+
- [ ] Create a subfolder named after the document the snippet supports.
113
+
- [ ] Create a `snippets` folder inside that subfolder.
114
+
- [ ] For the code file:
115
+
- [ ] If the snippet is not version-specific, place the code in a file with the appropriate extension (for example, `.cs` for C#) in the `snippets` folder.
116
+
- [ ] If the snippet is version-specific:
117
+
- [ ] Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9).
118
+
- [ ] Place the code in a file with the correct extension inside the version subfolder.
119
+
- [ ] Add a project file (`.csproj`) to the version subfolder targeting the matching .NET version, if necessary to run or build the snippet.
120
+
- [ ] Reference snippets using triple-colon syntax:
121
+
- [ ] **Use file-relative paths** for snippets located in the same file as the articles that refer to it.
@@ -145,13 +145,13 @@ When creating a PR for an issue:
145
145
Console | console | 2
146
146
Text | - | 2
147
147
148
-
### ASP.NET Core Specific Guidelines
149
-
- Use the latest supported version for examples unless otherwise specified
150
-
- Title and section header casing is sentence case (capitalize the first word and any proper nouns)
151
-
- For parts of a title or section header that normally use code style in article text (backticks around the content), also use code style in the title or section header (example H1 header: "# Modify the `Program.cs` file")
152
-
- Use code style for any words that shouldn't be localized
153
-
- For bullet lists, use an asterisk as the bullet marker
154
-
- Bullet lists should have two or more entries at the same level in the list. If there is only one item under a bullet, remove its bullet marker and roll that item into its parent bullet.
155
-
- Lead with Microsoft-recommended approaches
156
-
- Include differences between Minimal API and controller-based approaches when relevant
157
-
- For middleware content and examples, use the middleware class approach
148
+
### 4. ASP.NET Core Specific Guidelines
149
+
- [ ] Use the latest supported version for examples unless otherwise specified
150
+
- [ ] Title and section header casing is sentence case (capitalize the first word and any proper nouns)
151
+
- [ ] For parts of a title or section header that normally use code style in article text (backticks around the content), also use code style in the title or section header (example H1 header: "# Modify the `Program.cs` file")
152
+
- [ ] Use code style for any words that shouldn't be localized
153
+
- [ ] For bullet lists, use an asterisk as the bullet marker
154
+
- [ ] Bullet lists should have two or more entries at the same level in the list. If there is only one item under a bullet, remove its bullet marker and roll that item into its parent bullet.
155
+
- [ ] Lead with Microsoft-recommended approaches
156
+
- [ ] Include differences between Minimal API and controller-based approaches when relevant
157
+
- [ ] For middleware content and examples, use the middleware class approach
0 commit comments