Merge pull request #1129 from BillWagner/semester-review

Bring dotnet contributor up to date

Author: mikekinsman

.openpublishing.redirection.json

@@ -142,13 +142,11 @@
         },
         {
             "source_path": "Contribute/content/additional-resources.md",
-            "redirect_url": "/contribute/content/index",
-            "redirect_document_id": true
+            "redirect_url": "/contribute/content/index"
         },
         {
-            "source_path": "Contribute/dotnet/net-core-5-naming.md",
-            "redirect_url": "/contribute/content/dotnet/net-core-5-naming",
-            "redirect_document_id": true
+            "source_path": "Contribute/content/dotnet/net-core-5-naming.md",
+            "redirect_url": "/contribute/content/dotnet/dotnet-contribute"
         },
         {
             "source_path": "Contribute/get-started-setup-github.md",

Contribute/content/TOC.yml

@@ -103,8 +103,6 @@
             href: dotnet/dotnet-pr-review.md
           - name: Code analysis docs
             href: dotnet/dotnet-contribute-code-analysis.md
-          - name: .NET naming in docs
-            href: dotnet/net-core-5-naming.md
       - name: Patterns and Practices (AAC, WAF, CAF)
         href: architecture-center/aac-contribute.md
       - name: PowerShell-Docs

Contribute/content/dotnet/api-documentation.md

@@ -1,6 +1,6 @@
 ---
 title: How to write /// docs for .NET API ref
-ms.date: 06/29/2023
+ms.date: 06/17/2025
 author: gewarren
 ms.author: gewarren
 ms.service: learn
@@ -9,7 +9,7 @@ description: Learn how to write good descriptions in source code for generating
 ---
 # How to write good /// docs for .NET API reference
 
-The ultimate goal for .NET API docs is to have the /// XML comments in the .NET source code be the "source of truth". For MSBuild, ASP.NET Core, and EF Core, this goal has been met. However, currently the [dotnet-api-docs repo](https://github.com/dotnet/dotnet-api-docs) remains the source of truth for core .NET API reference. [This dotnet/runtime issue](https://github.com/dotnet/runtime/issues/44969) tracks the effort to backport .NET docs and make the [dotnet/runtime](https://github.com/dotnet/runtime) repo the source of truth.
+The ultimate goal for .NET API docs is to have the `///` XML comments in the .NET source code be the "source of truth". For MSBuild, ASP.NET Core, and EF Core, this goal has been met. However, currently the [dotnet-api-docs repo](https://github.com/dotnet/dotnet-api-docs) remains the source of truth for some namespaces in the .NET API reference. [This dotnet/runtime issue](https://github.com/dotnet/runtime/issues/44969) tracks the effort to backport .NET docs and make the [dotnet/runtime](https://github.com/dotnet/runtime) repo the source of truth. The presence or absence of the "edit" button on a page often indicates that the `dotnet-api-docs` repository is the source of truth. If it's missing, the source of truth is likely the `///` comments in the source repo.
 
 This article provides tips about writing good doc comments *within the source code itself*.
 

Contribute/content/dotnet/dotnet-contribute-code-analysis.md

@@ -6,7 +6,7 @@ ms.author: mavasani
 ms.topic: contributor-guide
 ms.service: learn
 ms.custom: external-contributor-guide
-ms.date: 10/09/2020
+ms.date: 06/17/2025
 ---
 # Contribute docs for .NET code analysis rules to the .NET docs repository
 

Contribute/content/dotnet/dotnet-contribute.md

@@ -4,7 +4,7 @@ description: This article describes the process for contributing to the articles
 ms.topic: contributor-guide
 ms.service: learn
 ms.custom: external-contributor-guide
-ms.date: 04/08/2021
+ms.date: 06/17/2025
 ---
 # Contribute to the .NET documentation repositories
 
@@ -15,10 +15,12 @@ This document covers the process for contributing to the articles and code sampl
 The .NET documentation site is built from multiple repositories. These are just some of them:
 
 - [.NET conceptual articles and code snippets](https://github.com/dotnet/docs)
+- [ASP.NET Core conceptual documentation](https://github.com/dotnet/AspNetCore.Docs)
+- [.NET Aspire conceptual documentation](https://github.com/dotnet/docs-aspire)
+- [.NET Desktop conceptual documentation](https://github.com/dotnet/docs-desktop)
+- [.NET MAUI conceptual documentation](https://github.com/dotnet/docs-maui)
 - [Code samples and snippets](https://github.com/dotnet/samples)
 - [.NET API reference](https://github.com/dotnet/dotnet-api-docs)
-- [.NET Compiler Platform SDK reference](https://github.com/dotnet/roslyn-api-docs)
-- [ML.NET API reference](https://github.com/dotnet/ml-api-docs)
 
 ## Guidelines for contributions
 

Contribute/content/dotnet/dotnet-pr-review.md

@@ -4,7 +4,7 @@ description: The .NET docs do not have the PR merger webhooks enabled. This arti
 ms.topic: contributor-guide
 ms.service: learn
 ms.custom: external-contributor-guide
-ms.date: 06/24/2020
+ms.date: 06/17/2025
 ---
 # Pull request review process for the .NET docs repositories
 
@@ -31,20 +31,20 @@ Reviews follow one of the three paths based on the PR:
 - **Major contributions** - Major contributions are significant edits to an existing article, new articles, or edits to a number of articles.
 - **Work in progress** - Authors can can create a PR that is marked as not ready for review yet by opening a *draft* pull request.
 
-The processing used by the Contributor License Agreement (CLA) bot is a good guideline for the distinction between "small" and "large" contributions. PRs that do not require the CLA to be signed are likely "small." PRs that do require the CLA are likely "large."
+The processing used by the Contributor License Agreement (CLA) bot is a good guideline for the distinction between "small" and "large" contributions. PRs that do not require the CLA to be signed are likely "small." PRs that do require the CLA are likely "large." The CLA needs to be signed once by each contributor, so this is an imperfect guide.
 
 ### Small PRs
 
 The changes in small PRs are reviewed for accuracy and checked using the build on the review site. Because they are small, these PRs do not trigger a review of the entire article.
 
-Reviewers may notice other small changes that would improve an article. If those changes are also small, suggest them as review comments. If the suggested changes would trigger a larger review, open an issue and address those later.
+Reviewers might notice other small changes that would improve an article. If those changes are also small, reviewers might suggest them as review comments. If the suggested changes would trigger a larger review, reviewers will ask to open an issue and address those later.
 
 ### Larger changes
 
 Larger PRs undergo a more thorough review. The following are all checked:
 
-- Sample code must be included in the PR, in source and as a downloadable zip file.
-- Sample code compiles and runs correctly.
+- Sample code must be included in the PR in source.
+- Sample code compiles and runs correctly using a supported .NET version.
 - The article clearly describes the goals for the reader, and those goals are met.
 - The article meets [style and grammar guidelines](dotnet-style-guide.md) and follows our [voice and tone principles](dotnet-voice-tone.md).
 - All links should resolve correctly.
@@ -59,7 +59,7 @@ You may want feedback earlier in the process. Open a draft PR and add a comment
 
 ## Explain suggestions
 
-GitHub lets you enter comments in triple-back-tick blocks of type `suggestion` that are displayed as a diff and can be merged by clicking a button. On short lines, GitHub does a good job of highlighting the changes. On longer lines, such as a long paragraph in one line of text, GitHub doesn't highlight the changes. When entering a suggestion for a long line, notice whether your changes are clearly highlighted. If the changes aren't highlighted, include comments outside the suggestion block explaining what you changed. Without an explanation it's often time-consuming for subsequent reviewers or the PR author to figure out what the changes are.
+GitHub lets you enter comments in triple-back-tick blocks of type `suggestion` that are displayed as a diff and can be merged by clicking a button. When entering a suggestion, include comments outside the suggestion block explaining what you changed. Without an explanation it's often time-consuming for subsequent reviewers or the PR author to figure out what the changes are.
 
 ## Respond to reviews
 

Contribute/content/dotnet/dotnet-style-guide.md

@@ -4,7 +4,7 @@ description: This article contains a handy template you can use to create new ar
 ms.topic: contributor-guide
 ms.service: learn
 ms.custom: external-contributor-guide
-ms.date: 11/07/2018
+ms.date: 06/17/2025
 ---
 # Metadata and Markdown template for .NET docs
 
@@ -48,12 +48,12 @@ Markdown uses special characters such as \*, \`, and \# for formatting. If you w
 
 File names use the following rules:
 
-* Contain only lowercase letters, numbers, and hyphens.
-* No spaces or punctuation characters. Use the hyphens to separate words and numbers in the file name.
-* Use action verbs that are specific, such as develop, buy, build, troubleshoot. No -ing words.
-* No small words - don't include a, and, the, in, or, etc.
-* Must be in Markdown and use the .md file extension.
-* Keep file names reasonably short. They are part of the URL for your articles.
+- Contain only lowercase letters, numbers, and hyphens.
+- No spaces or punctuation characters. Use the hyphens to separate words and numbers in the file name.
+- Use action verbs that are specific, such as develop, buy, build, troubleshoot. No -ing words.
+- No small words - don't include a, and, the, in, or, etc.
+- Must be in Markdown and use the .md file extension.
+- Keep file names reasonably short. They are part of the URL for your articles.
 
 ## Headings
 
@@ -113,8 +113,6 @@ Examples:
 - System.Exception.\#ctor becomes `System.Exception.%23ctor`
 - System.Lazy\`1.\#ctor(System.Threading.LazyThreadSafetyMode) becomes  `System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29`
 
-You can find the UIDs of types, a member overload list, or a particular overloaded member from `https://xref.learn.microsoft.com/autocomplete`. The query string `?text=*\<type-member-name>*` identifies the type or member whose UIDs you'd like to see. For example, `https://xref.learn.microsoft.com/autocomplete?text=string.format` retrieves the [String.Format](/dotnet/api/system.string.format) overloads. The tool searches for the provided `text` query parameter in any part of the UID. For example, you can search for member name (ToString), partial member name (ToStri), type and member name (Double.ToString), etc.
-
 If you add a \* (or `%2A`) after the UID, the link then represents the overload page and not a specific API. For example, you can use that when you want to link to the [List\<T>.BinarySearch Method](/dotnet/api/system.collections.generic.list-1.binarysearch) page in a generic way instead of a specific overload such as [List\<T>.BinarySearch(T, IComparer\<T>)](/dotnet/api/system.collections.generic.list-1.binarysearch#System_Collections_Generic_List_1_BinarySearch__0_). You can also use \* to link to a member page when the member is not overloaded; this saves you from having to include the parameter list in the UID.
 
 To link to a specific method overload, you must include the fully qualified type name of each of the method's parameters. For example, \<xref:System.DateTime.ToString> links to the parameterless [DateTime.ToString](/dotnet/api/system.datetime.tostring#System_DateTime_ToString) method, while \<xref:System.DateTime.ToString(System.String,System.IFormatProvider)> links to the  [DateTime.ToString(String,IFormatProvider)](/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_System_IFormatProvider_) method.
@@ -167,21 +165,23 @@ A custom style is available for lists. You can render lists with green check mar
 
 ```markdown
 > [!div class="checklist"]
-> * How to create a .NET Core app
-> * How to add a reference to the Microsoft.XmlSerializer.Generator package
-> * How to edit your MyApp.csproj to add dependencies
-> * How to add a class and an XmlSerializer
-> * How to build and run the application
+>
+> - How to create a .NET Core app
+> - How to add a reference to the Microsoft.XmlSerializer.Generator package
+> - How to edit your MyApp.csproj to add dependencies
+> - How to add a class and an XmlSerializer
+> - How to build and run the application
 ```
 
 This renders as:
 
 > [!div class="checklist"]
-> * How to create a .NET Core app
-> * How to add a reference to the Microsoft.XmlSerializer.Generator package
-> * How to edit your MyApp.csproj to add dependencies
-> * How to add a class and an XmlSerializer
-> * How to build and run the application
+>
+> - How to create a .NET Core app
+> - How to add a reference to the Microsoft.XmlSerializer.Generator package
+> - How to edit your MyApp.csproj to add dependencies
+> - How to add a class and an XmlSerializer
+> - How to build and run the application
 
 You can see an example of checked lists in action in the [.NET Core docs](/dotnet/core/additional-tools/xml-serializer-generator).
 

Contribute/content/dotnet/dotnet-voice-tone.md

@@ -4,7 +4,7 @@ description: Learn our voice and tone guidelines through examples of our styles
 ms.topic: contributor-guide
 ms.service: learn
 ms.custom: external-contributor-guide
-ms.date: 11/07/2018
+ms.date: 06/17/2025
 ---
 # Voice and tone guidelines