GetFolderPath breaking change

docs/core/compatibility/8.0.md

@@ -14,6 +14,12 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 >
 > This article is a work in progress. It's not a complete list of breaking changes in .NET 8. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet/docs%20or%20repo:aspnet/Announcements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%208%22%20or%20label:8.0.0)%20sort:created-desc).
 
+## Core .NET libraries
+
+| Title                                                                      | Type of change    | Introduced |
+| -------------------------------------------------------------------------- | ----------------- | ---------- |
+| [GetFolderPath behavior on Unix](core-libraries/8.0/getfolderpath-unix.md) | Behavioral change | Preview 1  |
+
 ## Cryptography
 
 | Title                                                                                                    | Type of change    | Introduced |

docs/core/compatibility/core-libraries/8.0/getfolderpath-unix.md

@@ -0,0 +1,62 @@
+---
+title: ".NET 8 breaking change: GetFolderPath behavior on Unix"
+description: Learn about the .NET 8 breaking change in core .NET libraries where the behavior of Environment.GetFolderPath has changed on Unix.
+ms.date: 11/18/2022
+---
+# GetFolderPath behavior on Unix
+
+Starting in .NET 8, the behavior of <xref:System.Environment.GetFolderPath%2A?displayProperty=nameWithType> on Unix operating systems has changed.
+
+## Change description
+
+The following tables show how the returned path value changes for each Unix operating system for various special folders.
+
+### Linux
+
+| SpecialFolder value | Path (.NET 7 and earlier) | Path (.NET 8 and later)                                            |
+|---------------------|---------------------------|--------------------------------------------------------------------|
+| `MyDocuments`       | `$HOME`                   | Uses `XDG_DOCUMENTS_DIR` if available; otherwise `$HOME/Documents` |
+| `Personal`          | `$HOME`                   | Uses `XDG_DOCUMENTS_DIR` if available; otherwise `$HOME/Documents` |
+
+### macOS
+
+| SpecialFolder value | Path (.NET 7 and earlier) | Path (.NET 8 and later) |
+|-|-|-|
+| `MyDocuments` | `$HOME` | [NSDocumentDirectory](https://developer.apple.com/documentation/foundation/nssearchpathdirectory/nsdocumentdirectory) (`$HOME/Documents`) |
+| `Personal` | `$HOME` | [NSDocumentDirectory](https://developer.apple.com/documentation/foundation/nssearchpathdirectory/nsdocumentdirectory) (`$HOME/Documents`) |
+| `ApplicationData` | `$HOME/.config` | [NSApplicationSupportDirectory](https://developer.apple.com/documentation/foundation/nssearchpathdirectory/nsapplicationsupportdirectory) (Library/Application Support) |
+| `LocalApplicationData` | `$HOME/.local/share` | [NSApplicationSupportDirectory](https://developer.apple.com/documentation/foundation/nssearchpathdirectory/nsapplicationsupportdirectory) (Library/Application Support) |
+| `MyVideos` | `$HOME/Videos` | [NSMoviesDirectory](https://developer.apple.com/documentation/foundation/nssearchpathdirectory/nsmoviesdirectory) (`$HOME/Movies`) |
+
+### Android
+
+| SpecialFolder value | Path (.NET 7 and earlier) | Path (.NET 8 and later) |
+|---------------------|---------------------------|-------------------------|
+| `MyDocuments`       | `$HOME`                   | `$HOME/Documents`       |
+| `Personal`          | `$HOME`                   | `$HOME/Documents`       |
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The previous behavior was incorrect and didn't meet user expectations for Linux, macOS, and Android.
+
+## Recommended action
+
+The most common break is if you're passing <xref:System.Environment.SpecialFolder.Personal?displayProperty=fullName> to <xref:System.Environment.GetFolderPath(System.Environment.SpecialFolder)?displayProperty=nameWithType> on Unix to get the `$HOME` directory (`Environment.GetFolderPath(Environment.SpecialFolder.Personal)`). <xref:System.Environment.SpecialFolder.Personal?displayProperty=nameWithType> and <xref:System.Environment.SpecialFolder.MyDocuments?displayProperty=nameWithType> are aliases for the same underlying enumeration value. If you're using <xref:System.Environment.SpecialFolder.Personal?displayProperty=nameWithType> in this way, change your code to pass <xref:System.Environment.SpecialFolder.UserProfile?displayProperty=nameWithType> instead (`Environment.GetFolderPath(Environment.SpecialFolder.UserProfile)`).
+
+For other breaks, the recommended action is to do one of the following:
+
+- Migrate your application's files to the appropriate directory.
+- Add a fallback check for the previous location to your code.
+
+## Affected APIs
+
+- <xref:System.Environment.GetFolderPath(System.Environment.SpecialFolder)?displayProperty=fullName>
+- <xref:System.Environment.GetFolderPath(System.Environment.SpecialFolder,System.Environment.SpecialFolderOption)?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -8,6 +8,10 @@ items:
     items:
     - name: Overview
       href: 8.0.md
+    - name: Core .NET libraries
+      items:
+      - name: GetFolderPath behavior on Unix
+        href: core-libraries/8.0/getfolderpath-unix.md
     - name: Cryptography
       items:
       - name: AesGcm authentication tag size on macOS
@@ -874,6 +878,10 @@ items:
         href: https://github.com/dotnet/dotnet-docker/discussions/3699
   - name: Core .NET libraries
     items:
+    - name: .NET 8
+      items:
+      - name: GetFolderPath behavior on Unix
+        href: core-libraries/8.0/getfolderpath-unix.md
     - name: .NET 7
       items:
       - name: API obsoletions with default diagnostic ID