Add breaking change documentation for FilePatternMatch.Stem nullability change

docs/core/compatibility/10.0.md

@@ -45,11 +45,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 |
 | [DriveInfo.DriveFormat returns Linux filesystem types](core-libraries/10.0/driveinfo-driveformat-linux.md) | Behavioral change | Preview 6 |
 | [DynamicallyAccessedMembers annotation removed from DefaultValueAttribute ctor](core-libraries/10.0/defaultvalueattribute-dynamically-accessed-members.md) | Binary/source incompatible | Preview 7 |
+| [Explicit struct Size disallowed with InlineArray](core-libraries/10.0/inlinearray-explicit-size-disallowed.md) | Binary incompatible | Preview 7 |
+| [FilePatternMatch.Stem changed to non-nullable](core-libraries/10.0/filepatternmatch-stem-nonnullable.md) | Source incompatible/behavioral change | RC 1 |
 | [GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default](core-libraries/10.0/tar-atime-ctime-default.md) | Behavioral change   | Preview 5          |
 | [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md) | Behavioral change | Preview 1 |
 | [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md) | Behavioral change | Preview 1 |
 | [.NET runtime no longer provides default termination signal handlers](core-libraries/10.0/sigterm-signal-handler.md) | Behavioral change | Preview 5 |
-| [Explicit struct Size disallowed with InlineArray](core-libraries/10.0/inlinearray-explicit-size-disallowed.md) | Binary incompatible | Preview 7 |
 | [System.Linq.AsyncEnumerable included in core libraries](core-libraries/10.0/asyncenumerable.md) | Source incompatible | Preview 1 |
 | [YMM embedded rounding removed from AVX10.2](core-libraries/10.0/ymm-embedded-rounding.md) | Behavioral change | Preview 5 |
 

docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md

@@ -0,0 +1,58 @@
+---
+title: "Breaking change - FilePatternMatch.Stem changed to non-nullable"
+description: "Learn about the breaking change in .NET 10 where FilePatternMatch.Stem property was changed from nullable to non-nullable."
+ms.date: 09/08/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/47914
+---
+
+# FilePatternMatch.Stem changed to non-nullable
+
+The <xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch.Stem?displayProperty=nameWithType> property was previously annotated as nullable because the `PatternTestResult.Stem` property it gets its value from is nullable. While the <xref:Microsoft.Extensions.FileSystemGlobbing.Internal.PatternTestResult> can indeed be null if the result isn't successful, the `FilePatternMatch` never is because it's only constructed when `PatternTestResult` is successful.
+
+To accurately reflect nullability, the `[MemberNotNullWhen()]` attribute is applied to the `PatternTestResult.Stem` property to tell the compiler it won't be null if it's successful. Additionally, the `stem` argument passed into the `FilePatternMatch` constructor is no longer nullable, and an `ArgumentNullException` will be thrown if a null `stem` is passed in.
+
+## Version introduced
+
+.NET 10 RC 1
+
+## Previous behavior
+
+Previously, the <xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch> constructor accepted `null` for the `stem` parameter without any compile-time or run-time warnings or errors.
+
+```csharp
+// Allowed in previous versions.
+var match = new FilePatternMatch("path/to/file.txt", null);
+```
+
+The <xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch.Stem?displayProperty=nameWithType> property was also annotated as being nullable.
+
+## New behavior
+
+Starting in .NET 10, passing a `null` or possibly-null value to the `stem` argument in the <xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch> constructor yields a compile-time warning. And, if `null` is passed in, a run-time <xref:System.ArgumentNullException> is thrown.
+
+The <xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch.Stem?displayProperty=nameWithType> property is now annotated to indicate that the value won't be null if `IsSuccessful` is `true`.
+
+```csharp
+// Generates compile-time warning.
+var match = new FilePatternMatch("path/to/file.txt", null);
+```
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility) and is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The previous nullability annotations were inaccurate, and a `null` value for the `stem` argument was unexpected but not properly guarded against. This change reflects the expected behavior of the API and guards against unpredictable behavior while also producing design-time guidance around usage.
+
+## Recommended action
+
+If a possibly null value was passed in for the `stem` argument, review usage and update the call site to ensure `stem` can't be paTssed in as `null`.
+
+If you applied nullability warning suppressions when consuming the `FilePatternMatch.Stem` property, you can remove those suppressions.
+
+## Affected APIs
+
+- [FilePatternMatch(String,String) constructor](xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch.%23ctor(System.String,System.String))
+- <xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch.Stem?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -48,6 +48,10 @@ items:
                 href: core-libraries/10.0/driveinfo-driveformat-linux.md
               - name: DynamicallyAccessedMembers annotation removed from DefaultValueAttribute ctor
                 href: core-libraries/10.0/defaultvalueattribute-dynamically-accessed-members.md
+              - name: Explicit struct Size disallowed with InlineArray
+                href: core-libraries/10.0/inlinearray-explicit-size-disallowed.md
+              - name: FilePatternMatch.Stem changed to non-nullable
+                href: core-libraries/10.0/filepatternmatch-stem-nonnullable.md
               - name: GnuTarEntry and PaxTarEntry exclude atime and ctime by default
                 href: core-libraries/10.0/tar-atime-ctime-default.md
               - name: LDAP DirectoryControl parsing is now more stringent
@@ -56,8 +60,6 @@ items:
                 href: core-libraries/10.0/maccatalyst-version-normalization.md
               - name: No default termination signal handlers
                 href: core-libraries/10.0/sigterm-signal-handler.md
-              - name: Explicit struct Size disallowed with InlineArray
-                href: core-libraries/10.0/inlinearray-explicit-size-disallowed.md
               - name: System.Linq.AsyncEnumerable included in core libraries
                 href: core-libraries/10.0/asyncenumerable.md
               - name: YMM embedded rounding removed from AVX10.2