From e7ed445efa09408486289d0653b3d113526f5409 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 15 Aug 2025 10:11:37 -0400 Subject: [PATCH 1/6] Add guidance for choosing ToList() vs ToArray() in async LINQ scenarios (#47729) * Initial plan * Add explanation and example for ToList() vs ToArray() in async scenarios Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update docs/csharp/asynchronous-programming/async-scenarios.md * Add complete snippet markers to Program.cs and update markdown reference Co-authored-by: adegeo <67293991+adegeo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: adegeo <67293991+adegeo@users.noreply.github.com> --- .../async-scenarios.md | 23 +++++++------------ .../snippets/async-scenarios/Program.cs | 21 +++++++++++++++++ 2 files changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/csharp/asynchronous-programming/async-scenarios.md b/docs/csharp/asynchronous-programming/async-scenarios.md index e63c3c0efecb3..4192f71fde8f1 100644 --- a/docs/csharp/asynchronous-programming/async-scenarios.md +++ b/docs/csharp/asynchronous-programming/async-scenarios.md @@ -132,25 +132,18 @@ You can write this code more succinctly by using LINQ: Although you write less code by using LINQ, exercise caution when mixing LINQ with asynchronous code. LINQ uses deferred (or lazy) execution, which means that without immediate evaluation, async calls don't happen until the sequence is enumerated. -The previous example is correct and safe, because it uses the method to immediately evaluate the LINQ query and store the tasks in an array. This approach ensures the `id => GetUserAsync(id)` calls execute immediately and all tasks start concurrently, just like the `foreach` loop approach. +The previous example is correct and safe, because it uses the method to immediately evaluate the LINQ query and store the tasks in an array. This approach ensures the `id => GetUserAsync(id)` calls execute immediately and all tasks start concurrently, just like the `foreach` loop approach. Always use or when creating tasks with LINQ to ensure immediate execution and concurrent task execution. Here's an example that demonstrates using `ToList()` with `Task.WhenAny` to process tasks as they complete: -**Problematic approach** (without immediate evaluation): +:::code language="csharp" source="snippets/async-scenarios/Program.cs" ID="ProcessTasksAsTheyComplete"::: -```csharp -// DON'T do this - tasks won't start until enumerated. -var getUserTasks = userIds.Select(id => GetUserAsync(id)); // No .ToArray()! -return await Task.WhenAll(getUserTasks); // Tasks start here. -``` +In this example, `ToList()` creates a list that supports the `Remove()` operation, allowing you to dynamically remove completed tasks. This pattern is particularly useful when you want to handle results as soon as they're available, rather than waiting for all tasks to complete. -**Recommended approach**: +Although you write less code by using LINQ, exercise caution when mixing LINQ with asynchronous code. LINQ uses deferred (or lazy) execution. Asynchronous calls don't happen immediately as they do in a `foreach` loop, unless you force the generated sequence to iterate with a call to the `.ToList()` or `.ToArray()` method. -```csharp -// DO this - tasks start immediately. -var getUserTasks = userIds.Select(id => GetUserAsync(id)).ToArray(); -return await Task.WhenAll(getUserTasks); -``` +You can choose between and based on your scenario: -Always use or when creating tasks with LINQ to ensure immediate execution and concurrent task execution. +- Use `ToArray()` when you plan to process all tasks together, such as with `Task.WhenAll`. Arrays are efficient for scenarios where the collection size is fixed. +- Use `ToList()` when you need to dynamically manage tasks, such as with `Task.WhenAny` where you might remove completed tasks from the collection as they finish. ## Review considerations for asynchronous programming @@ -280,7 +273,7 @@ For more detailed guidance on the challenges and considerations of synchronous w The following code represents the complete example, which is available in the *Program.cs* example file. -:::code language="csharp" source="snippets/async-scenarios/Program.cs"::: +:::code language="csharp" source="snippets/async-scenarios/Program.cs" ID="complete"::: ## Related links diff --git a/docs/csharp/asynchronous-programming/snippets/async-scenarios/Program.cs b/docs/csharp/asynchronous-programming/snippets/async-scenarios/Program.cs index fc847ba26edbc..1d273161dd477 100644 --- a/docs/csharp/asynchronous-programming/snippets/async-scenarios/Program.cs +++ b/docs/csharp/asynchronous-programming/snippets/async-scenarios/Program.cs @@ -1,3 +1,4 @@ +// using System.Text.RegularExpressions; using System.Windows; using Microsoft.AspNetCore.Mvc; @@ -145,6 +146,22 @@ private static async Task GetUsersAsyncByLINQ(IEnumerable userIds) } // + // + private static async Task ProcessTasksAsTheyCompleteAsync(IEnumerable userIds) + { + var getUserTasks = userIds.Select(id => GetUserAsync(id)).ToList(); + + while (getUserTasks.Count > 0) + { + Task completedTask = await Task.WhenAny(getUserTasks); + getUserTasks.Remove(completedTask); + + User user = await completedTask; + Console.WriteLine($"Processed user {user.id}"); + } + } + // + // [HttpGet, Route("DotNetCount")] static public async Task GetDotNetCountAsync(string URL) @@ -178,6 +195,9 @@ static async Task Main() Console.WriteLine($"{user.id}: isEnabled={user.isEnabled}"); } + Console.WriteLine("Processing tasks as they complete..."); + await ProcessTasksAsTheyCompleteAsync(ids); + Console.WriteLine("Application ending."); } } @@ -219,4 +239,5 @@ static async Task Main() // 9: isEnabled= False // 0: isEnabled= False // Application ending. +// From ba47c6c944908549ad06a37a9f99099cbf7643a2 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 15 Aug 2025 07:19:52 -0700 Subject: [PATCH 2/6] use xrefs etc (#47970) --- docs/core/whats-new/dotnet-10/libraries.md | 18 +++++++++--------- docs/core/whats-new/dotnet-10/overview.md | 2 -- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/core/whats-new/dotnet-10/libraries.md b/docs/core/whats-new/dotnet-10/libraries.md index 0c9ac5d159867..0dd05b1111fc1 100644 --- a/docs/core/whats-new/dotnet-10/libraries.md +++ b/docs/core/whats-new/dotnet-10/libraries.md @@ -61,9 +61,9 @@ If you want even more control, you can use [the overload](xref:System.Security.C .NET 10 includes support for three new asymmetric algorithms: ML-KEM (FIPS 203), ML-DSA (FIPS 204), and SLH-DSA (FIPS 205). The new types are: -- `System.Security.Cryptography.MLKem` -- `System.Security.Cryptography.MLDsa` -- `System.Security.Cryptography.SlhDsa` +- +- +- Because it adds little benefit, these new types don't derive from . Rather than the `AsymmetricAlgorithm` approach of creating an object and then importing a key into it, or generating a fresh key, the new types all use static methods to generate or import a key: @@ -95,7 +95,7 @@ using (MLKem key = MLKem.GenerateKey(MLKemAlgorithm.MLKem768)) These algorithms all continue with the pattern of having a static `IsSupported` property to indicate if the algorithm is supported on the current system. -.NET 10 includes Windows Cryptography API: Next Generation (CNG) support for Post-Quantum Cryptography (PQC), making these algorithms available on Windows systems with PQC support. For example: +.NET 10 includes Windows Cryptography API: Next Generation (CNG) support for Post-Quantum Cryptography (PQC), which makes these algorithms available on Windows systems with PQC support. For example: ```csharp using System; @@ -130,7 +130,7 @@ private static byte[] SignData(string privateKeyPath, ReadOnlySpan data) } ``` -Additionally, this release added support for HashML-DSA, which is called "PreHash" to help distinguish it from "pure" ML-DSA. As the underlying specification interacts with the Object Identifier (OID) value, the SignPreHash and VerifyPreHash methods on this `[Experimental]` type take the dotted-decimal OID as a string. This might evolve as more scenarios using HashML-DSA become well-defined. +Additionally, .NET 10 adds support for HashML-DSA, which is called "PreHash" to help distinguish it from "pure" ML-DSA. As the underlying specification interacts with the Object Identifier (OID) value, the SignPreHash and VerifyPreHash methods on this `[Experimental]` type take the dotted-decimal OID as a string. This might evolve as more scenarios using HashML-DSA become well-defined. ```csharp private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan data) @@ -142,7 +142,7 @@ private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan d #### Composite ML-DSA -.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (currently at draft 7), including `CompositeMLDsa` and `CompositeMLDsaAlgorithm` types with implementation of the primitive methods for RSA variants. +.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (currently at draft 7), including the and types, with implementation of the primitive methods for RSA variants. ```csharp var algorithm = CompositeMLDsaAlgorithm.MLDsa65WithRSA4096Pss; @@ -160,7 +160,7 @@ Console.WriteLine(publicKey.VerifyData(data, signature)); // False ### AES KeyWrap with Padding (IETF RFC 5649) -AES-KWP is an algorithm that is occasionally used in constructions like Cryptographic Message Syntax (CMS) EnvelopedData, where content is encrypted once, but the decryption key needs to be distributed to multiple parties, each one in a distinct secret form. +AES-KWP is an algorithm that's occasionally used in constructions like Cryptographic Message Syntax (CMS) EnvelopedData, where content is encrypted once, but the decryption key needs to be distributed to multiple parties, each one in a distinct secret form. .NET now supports the AES-KWP algorithm via instance methods on the class: @@ -440,7 +440,7 @@ For Windows, you can now use -->, a new API designed to simplify some of the most common—and previously cumbersome— scenarios in .NET. +.NET 10 introduces , a new API designed to simplify some of the most common—and previously cumbersome— scenarios in .NET. Traditional `WebSocket` APIs are low-level and require significant boilerplate: handling buffering and framing, reconstructing messages, managing encoding/decoding, and writing custom wrappers to integrate with streams, channels, or other transport abstractions. These complexities make it difficult to use WebSockets as a transport, especially for apps with streaming or text-based protocols, or event-driven handlers. @@ -485,7 +485,7 @@ Here are a few examples of how `WebSocketStream` simplifies typical `WebSocket` Use an AppContext switch in code: ```csharp -// Opt in to Network.framework-backed TLS on Apple platforms +// Opt in to Network.framework-backed TLS on Apple platforms. AppContext.SetSwitch("System.Net.Security.UseNetworkFramework", true); using var client = new HttpClient(); diff --git a/docs/core/whats-new/dotnet-10/overview.md b/docs/core/whats-new/dotnet-10/overview.md index 02d2f1a8b4592..53f0ad2991675 100644 --- a/docs/core/whats-new/dotnet-10/overview.md +++ b/docs/core/whats-new/dotnet-10/overview.md @@ -26,14 +26,12 @@ For more information, see [What's new in the .NET 10 runtime](runtime.md). The .NET 10 libraries introduce new APIs in cryptography, globalization, numerics, serialization, collections, and diagnostics, and when working with ZIP files. New JSON serialization options include disallowing duplicate properties, strict serialization settings, and `PipeReader` support for improved efficiency. Post-quantum cryptography support has been expanded with Windows Cryptography API: Next Generation (CNG) support, enhanced ML-DSA with simplified APIs and HashML-DSA support, plus Composite ML-DSA. Additional cryptography enhancements include AES KeyWrap with Padding support. New networking capabilities include `WebSocketStream` for simplified `WebSocket` usage and TLS 1.3 support for macOS clients. Process management gains Windows process group support for better signal isolation. For more information, see [What's new in the .NET 10 libraries](libraries.md). -For details on JSON serialization, see [System.Text.Json overview](/dotnet/standard/serialization/system-text-json/overview). ## .NET SDK The .NET 10 SDK includes support for [Microsoft.Testing.Platform](../../testing/microsoft-testing-platform-intro.md) in `dotnet test`, standardizes CLI command order, and updates the CLI to generate native tab-completion scripts for popular shells. For containers, console apps can natively create container images, and a new property lets you explicitly set the format of container images. The SDK also supports platform-specific .NET tools with enhanced compatibility via the `any` RuntimeIdentifier, one-shot tool execution with `dotnet tool exec`, the new `dnx` tool execution script, CLI introspection with `--cli-schema`, and enhanced file-based apps with publish support and native AOT. For more information, see [What's new in the SDK for .NET 10](sdk.md). -For details on .NET tools, see [Manage .NET tools](/dotnet/core/tools/global-tools). ## .NET Aspire From d6b51cf5e2aa8ab83f4bb117aeff86c05a34e83d Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 15 Aug 2025 09:10:39 -0700 Subject: [PATCH 3/6] Document breaking change: Arm64 SVE NonFaulting loads require mask parameter (#47907) --- docs/core/compatibility/10.0.md | 1 + .../sve-nonfaulting-loads-mask-parameter.md | 79 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 82 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index fb0e411ae0e0f..1eb3ffccd047e 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -39,6 +39,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| | [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 | +| [Arm64 SVE nonfaulting loads require mask](core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md) | Binary/source incompatible | Preview 1 | | [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 | | [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 | | [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 | diff --git a/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md b/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md new file mode 100644 index 0000000000000..b67428c0e94e9 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md @@ -0,0 +1,79 @@ +--- +title: "Breaking change: Arm64 SVE nonfaulting loads require mask parameter" +description: "Learn about the breaking change in .NET 10 where Arm64 SVE nonfaulting load APIs now require a mask parameter as the first argument." +ms.date: 08/11/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/47439 +--- + +# Arm64 SVE nonfaulting loads require mask parameter + +All Arm64 SVE nonfaulting load APIs have been updated to include a `mask` parameter in the first position. This change affects all methods with `LoadVector*NonFaulting` in their name in the class. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +Previously, nonfaulting load APIs took only an address parameter and loaded a full vector: + +```csharp +Vector result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address); +``` + +To do nonfaulting load with masked-out elements, you had to use : + +```csharp +Vector maskedResult = Sve.ConditionalSelect( + mask, + Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address), + zero); +``` + +## New behavior + +Starting in .NET 10, nonfaulting load APIs require a mask parameter as the first argument. + +To do a nonfaulting load for all elements, create and pass a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);` + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility) and [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +This change was necessary because a nonfaulting load updates the first fault register (FFR) depending on which vector lanes are loaded. The standard conversion of `ConditionalSelect(mask, LoadVectorNonFaulting(addr), zero)` to a masked load can't be used because it doesn't properly handle the FFR register state. Therefore, the only valid way to implement a masked nonfaulting load is by exposing it as a dedicated API. + +## Recommended action + +- For existing uses of `Sve.ConditionalSelect(mask, Sve.LoadVector*NonFaulting*(addr), zero)`, replace them with `Sve.LoadVector*NonFaulting*(mask, addr)`. +- Update other uses of nonfaulting loads to include a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr)`. + +## Affected APIs + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 264f6a530f18a..724e1f2485cca 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -36,6 +36,8 @@ items: href: core-libraries/10.0/obsolete-apis.md - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change href: core-libraries/10.0/activity-sampling.md + - name: Arm64 SVE nonfaulting loads require mask + href: core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md - name: C# 14 overload resolution with span parameters href: core-libraries/10.0/csharp-overload-resolution.md - name: Consistent shift behavior in generic math From 22f92a1929d88ded1bed70c277af6dd72aaeccc9 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 15 Aug 2025 12:35:17 -0400 Subject: [PATCH 4/6] Add note on which codes are build only (#47969) Fixes #47470 --- ...n-t-have-specifics-on-this-csharp-error.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md b/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md index a3b198f22fe75..ceefdca01b4b5 100644 --- a/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md +++ b/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md @@ -118,7 +118,7 @@ f1_keywords: - "CS7019" - "CS7020" - "CS7021" - - "CS7022" + - "CS7022" # build only diagnostic - "CS7024" - "CS7025" - "CS7026" @@ -130,7 +130,7 @@ f1_keywords: - "CS7033" - "CS7034" - "CS7035" - - "CS7038" + - "CS7038" # build only diagnostic - "CS7041" - "CS7042" - "CS7043" @@ -173,23 +173,23 @@ f1_keywords: - "CS7098" - "CS7099" - "CS7100" - - "CS7101" + - "CS7101" # build only diagnostic - "CS7102" - "CS7103" - "CS8001" - "CS8002" - "CS8003" - - "CS8004" - - "CS8005" - - "CS8006" - - "CS8007" - - "CS8008" + - "CS8004" # build only diagnostic + - "CS8005" # build only diagnostic + - "CS8006" # build only diagnostic + - "CS8007" # build only diagnostic + - "CS8008" # build only diagnostic - "CS8009" - - "CS8010" - - "CS8011" + - "CS8010" # build only diagnostic + - "CS8011" # build only diagnostic - "CS8012" - - "CS8013" - - "CS8014" + - "CS8013" # build only diagnostic + - "CS8014" # build only diagnostic - "CS8015" - "CS8016" - "CS8017" @@ -204,7 +204,7 @@ f1_keywords: - "CS8032" - "CS8033" - "CS8034" - - "CS8035" + - "CS8035" # build only diagnostic - "CS8036" - "CS8040" - "CS8050" @@ -216,7 +216,7 @@ f1_keywords: - "CS8070" - "CS8076" - "CS8077" - - "CS8078" + - "CS8078" # build only diagnostic - "CS8079" - "CS8080" - "CS8081" From 6c4a21c30d1dd92ac56b70fb6a51beeebceb2e75 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 15 Aug 2025 17:59:35 +0000 Subject: [PATCH 5/6] Add Unicode escape sequence scenario to CS1012 error documentation (#47962) * Initial plan * Add Unicode escape sequence scenario to CS1012 error documentation Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> * Update docs/csharp/misc/cs1012.md * Update docs/csharp/misc/cs1012.md * Update docs/csharp/misc/cs1012.md * Update docs/csharp/misc/cs1012.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/csharp/misc/cs1012.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/csharp/misc/cs1012.md b/docs/csharp/misc/cs1012.md index 68326585d9ec8..088fcb1847e0e 100644 --- a/docs/csharp/misc/cs1012.md +++ b/docs/csharp/misc/cs1012.md @@ -12,9 +12,7 @@ ms.assetid: 4acc5fe0-da47-4882-b7d8-557767d7cf03 Too many characters in character literal - An attempt was made to initialize a [char](../language-reference/builtin-types/char.md) constant with more than one character. - - CS1012 can also occur when doing data binding. For example the following line will give an error: + An attempt was made to initialize a [char](../language-reference/builtin-types/char.md) constant with more than one character. CS1012 can occur when doing data binding. CS1012 can also occur when using Unicode escape sequences that exceed the UTF-16 range. A character literal represents a single character as a UTF-16 code unit, so Unicode values greater than 0xFFFF (65535) aren't valid in character literals. For example, the following code gives an error: `<%# DataBinder.Eval(Container.DataItem, 'doctitle') %>` @@ -30,9 +28,12 @@ class Sample { static void Main() { - char a = 'xx'; // CS1012 - char a2 = 'x'; // OK - System.Console.WriteLine(a2); + char a = 'xx'; // CS1012 - too many characters + char b = '\U00010000'; // CS1012 - exceeds UTF-16 range (> 0xFFFF) + + char c = 'x'; // OK + char d = '\u0061'; // OK - represents 'a' within UTF-16 range + System.Console.WriteLine($"{c}, {d}"); } } ``` From 1b66d537567e682f03e178ce36eaa978dc13b24c Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 15 Aug 2025 14:01:54 -0400 Subject: [PATCH 6/6] Another iteration on What's new prompt (#47976) * Another iteration on What's new prompt Go through the comments on the What's new in .NET 10 Preview 7 PR, and update the prompt for What's new issues so that Copilot improves. There are four main themes: - Don't separate features by preview build. - Use includable snippets for samples more than 6 lines. - Translate any marketing speak (first person announcements and such) to technical information in 2nd person. - Follow the general guidelines for all edits pertaining to style and form. * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --------- Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .github/prompts/whats-new-net.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/prompts/whats-new-net.md b/.github/prompts/whats-new-net.md index 5180e98d7f1bd..3b6105c685d87 100644 --- a/.github/prompts/whats-new-net.md +++ b/.github/prompts/whats-new-net.md @@ -27,8 +27,23 @@ For preview releases, the path is `/preview/preview` where: The primary release notes are in the `README.MD` file in that folder. That file contains links to other release notes for components of .NET: libraries, runtime, SDK, languages, and so on. Use all that information for source. +The source files you use are release notes from the product team. These take the form of announcements, so you should edit any incorporated content per the following guidelines: + +- Remove any 1st person references (we, us, our), and rewrite that information in the 2nd person: Tell the reader what the reader can do, using "you" to refer to the reader. +- Remove any marketing and promotional language. These articles provide technical information, not marketing copy. + ## Updates for each file +Each file should be organized to provide a cohesive story about "What's new" in the release. When you edit: + +- The introductory paragraph states when the last update was made (Preview N, general release, any service release). That is the only mention of the latest minor, patch, or preview version. +- If one of the areas (SDK, libraries, or runtime) doesn't have any updates for the current release (preview, RC, or GA), update the introductory paragraph and ms.date value, without making any other changes. +- Each file should organize updates by feature area, not by when an update was made. In other words, starting with the 2nd preview, incorporate updates to the existing text to provide a single view of all updates made in the major release. For example, the "RC1" updates should add in updates in RC1 where it fits in the document, not make a new "RC1" section. +- If a preview introduces a new feature that's unrelated to existing new features, add a new H2 for that feature area. + +In addition, follow these recommendations: + +- Follow the Microsoft Writing Style Guide, as noted in the `.github/copilot-instructions.md` file in this repository. - Each file should have its `ms.date` metadata field updated to match the date you're assigned the issue. - Ensure each file has the `ai-usage: ai-assisted` metadata field added. - Update phrasing on the latest update to reference the current release (preview, GA, or service release). Individual features shouldn't reference a given preview release, but the article should make it clear which was the last preview. @@ -36,9 +51,11 @@ The primary release notes are in the `README.MD` file in that folder. That file - For the runtime and libraries articles, include extensive examples as well as links to recently updated articles related to the new feature. The examples should be at least as thorough as the examples from the source release notes. - Where applicable, the SDK article should include the samples. - The overview article generally doesn't include examples. Its purpose is to direct readers to more detailed information in other articles. -- All APIs should be referenced using an `xref` style link, at least on first mention. +- All APIs should be referenced using an `xref` style link, at least on first mention. Later mentions should be code-fenced in single back-ticks. - All links to article in the `dotnet/docs` repository should be file relative. - Spell out acronyms on first use in each file. +- Avoid gerund form in headings. - In general, don't mention specific contributors or pull requests to the product repos. +- Code snippets longer than 6 lines should be moved to a code file and included using the `:::` extension. All code files should be included in a buildable project to ensure the snippets build correctly. Next, create a pull request. In the description, include the text "Fixes #\", where "issue-number" is the GitHub issue number.