Add breaking change documentation for GnuTarEntry and PaxTarEntry atime/ctime behavior

Co-authored-by: gewarren <[email protected]>

Author: Copilot

docs/core/compatibility/10.0.md

@@ -30,6 +30,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [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          |
+| [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          |
 | [System.Linq.AsyncEnumerable included in core libraries](core-libraries/10.0/asyncenumerable.md)                           | Source incompatible | Preview 1          |

docs/core/compatibility/core-libraries/10.0/tar-atime-ctime-default.md

@@ -0,0 +1,51 @@
+---
+title: "Breaking change: GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default"
+description: "Learn about the breaking change in .NET 10 where GnuTarEntry and PaxTarEntry no longer automatically set access time and change time fields."
+ms.date: 01/30/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/46465
+---
+# GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default
+
+Starting in .NET 10, <xref:System.Formats.Tar.GnuTarEntry> and <xref:System.Formats.Tar.PaxTarEntry> no longer automatically set access time (`atime`) and change time (`ctime`) fields when creating new entries. These fields are problematic in tar entries because not all tar readers support them.
+
+## Version introduced
+
+.NET 10 Preview 5
+
+## Previous behavior
+
+Previously, `GnuTarEntry` and `PaxTarEntry` always added `atime` and `ctime` values when creating new entries.
+
+## New behavior
+
+Starting in .NET 10, `GnuTarEntry` and `PaxTarEntry` only set `atime` and `ctime` if:
+
+- The entry was read from a tar archive that already contained these fields
+- The user explicitly sets them using the appropriate properties
+
+The behavior of <xref:System.Formats.Tar.TarEntry.ModificationTime?displayProperty=nameWithType> remains unchanged. It's initialized to <xref:System.DateTime.UtcNow?displayProperty=nameWithType> for tar entries created with a constructor, and uses the file modification time for entries created from files.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Better compatibility with other tar readers and improved round-tripping of tar files without modification. The `atime` and `ctime` fields create tar files that aren't readable by many tar clients.
+
+## Recommended action
+
+No action required for most users. If you require these fields to be set, you can do so directly:
+
+- For `GnuTarEntry`: Use <xref:System.Formats.Tar.GnuTarEntry.AccessTime?displayProperty=nameWithType> and <xref:System.Formats.Tar.GnuTarEntry.ChangeTime?displayProperty=nameWithType> properties
+- For `PaxTarEntry`: Use the constructor that accepts extended attributes: <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})?displayProperty=nameWithType>
+
+However, be aware that setting these fields creates a tar file that might not be readable by many tar clients.
+
+## Affected APIs
+
+- <xref:System.Formats.Tar.GnuTarEntry?displayProperty=fullName>
+- <xref:System.Formats.Tar.PaxTarEntry?displayProperty=fullName>
+- <xref:System.Formats.Tar.TarReader?displayProperty=fullName>
+- <xref:System.Formats.Tar.TarWriter?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -24,6 +24,8 @@ items:
                 href: core-libraries/10.0/generic-math.md
               - name: Default trace context propagator updated to W3C Standard
                 href: core-libraries/10.0/default-trace-context-propagator.md
+              - name: GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default
+                href: core-libraries/10.0/tar-atime-ctime-default.md
               - name: LDAP DirectoryControl parsing is now more stringent
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
               - name: MacCatalyst version normalization