issue 43303

Author: Cam Soper

docs/core/compatibility/10.0.md

@@ -22,6 +22,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md)                                    | Source incompatible | Preview 1          |
 | [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change   | 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          |
 | [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md)                | Behavioral change   | Preview 1          |
 
 ## Globalization

docs/core/compatibility/core-libraries/10.0/generic-math.md

@@ -0,0 +1,38 @@
+---
+title: "Breaking change: Consistent shift behavior in generic math"
+description: Learn about the .NET 10 breaking change in core .NET libraries where shift operations in generic math now have consistent behavior.
+ms.date: 01/30/2025
+---
+# Consistent shift behavior in generic math
+
+This document explains the breaking change in .NET 10 where shift operations in generic math now have consistent behavior across all built-in integer types.
+
+## Previous behavior
+
+The behavior when utilizing generic math to perform a shift on a `T` could differ based on the type. In some cases, it would appropriately mask the shift amount by `sizeof(T) - 1` and in other cases, it would do no masking. This meant that "overshifting" (such as shifting a `byte` by 8) could result in different answers than expected.
+
+## New behavior
+
+The implementations were updated to mask the shift amount, as appropriate, to ensure consistent behavior across all built-in integer types and with the behavior documented by the <xref:System.Numerics.IShiftOperators`3?displayProperty=nameWithType> interface.
+
+## Version introduced
+
+.NET 10 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The behavior differed from the designed behavior due to a difference in how masking works for small integer types in C#.
+
+## Recommended action
+
+Update any code that relies on the previous inconsistent behavior to ensure it works with the new consistent behavior.
+
+## Affected APIs
+
+- `operator <<`
+- `operator >>`
+- `operator >>>` for `byte`, `char`, `sbyte`, `short`, and `ushort` when used via `Generic Math`, which requires a `T` constrained to `where T : IShiftOperators<T, int, T>` or a similar interface.

docs/core/compatibility/toc.yml

@@ -16,6 +16,8 @@ items:
                 href: core-libraries/10.0/activity-sampling.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
+                href: core-libraries/10.0/generic-math.md
               - name: LDAP DirectoryControl parsing is now more stringent
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
           - name: Globalization
@@ -1330,6 +1332,8 @@ items:
                 href: core-libraries/10.0/activity-sampling.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
+                href: core-libraries/10.0/generic-math.md
               - name: LDAP DirectoryControl parsing is now more stringent
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
           - name: .NET 9