From fb6f5fd1199abbcd77124a9938d19526924f9c5c Mon Sep 17 00:00:00 2001
From: Louis Seubert <louis.seubert.ls@gmail.com>
Date: Tue, 20 Oct 2026 21:16:12 +0200
Subject: [PATCH] fix(sdk): pack PACKAGE.md instead of README.md as package
 readme

---
 src/sdk/README.md             |  4 ++--
 src/sdk/common/Common.targets | 25 +++++++++++++------------
 2 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/src/sdk/README.md b/src/sdk/README.md
index 674c5a7..9c93b47 100644
--- a/src/sdk/README.md
+++ b/src/sdk/README.md
@@ -18,6 +18,6 @@ Set these properties in your project file or a directory-level props file. Unles
 | `PublishRepositoryUrl` | `true` | Publishes the repository URL in packages. |
 | `IncludeSymbols` | `true` | Packs a symbol package. |
 | `SymbolPackageFormat` | `snupkg` | Format of the symbol package. |
-| `PackageReadmeFile` | `README.md` when found | Packs a README file from the project directory as the package readme. |
-| `SearchReadmeFileAbove` | `false` | When `true`, searches parent directories for a README to pack. |
+| `PackageReadmeFile` | `PACKAGE.md` when found | Packs a `PACKAGE.md` file from the project directory as the package readme. Not packed: `README.md` is for repository visitors. |
+| `SearchReadmeFileAbove` | `false` | When `true`, searches parent directories for a `PACKAGE.md` to pack. |
 | `PackageLicenseFile` | Detected license file | Packs and declares a `LICENSE.txt`, `LICENSE.md` or `LICENSE` file found in the project directory or a parent directory. Skipped when the project sets `PackageLicenseExpression` or `PackageLicenseFile`. |
diff --git a/src/sdk/common/Common.targets b/src/sdk/common/Common.targets
index ed4ab3b..c94cbec 100644
--- a/src/sdk/common/Common.targets
+++ b/src/sdk/common/Common.targets
@@ -38,17 +38,18 @@
 
 	<!-- NuGet Package -->
 	<PropertyGroup>
-		<!-- Detect a README file in the project directory to pack as the package readme.
-		     Set 'SearchReadmeFileAbove' to 'true' to also search the parent directories. -->
-		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/README.md')">$(MSBuildProjectDirectory)/README.md</_PackageReadmeFilePath>
-		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/readme.md')">$(MSBuildProjectDirectory)/readme.md</_PackageReadmeFilePath>
-		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/Readme.md')">$(MSBuildProjectDirectory)/Readme.md</_PackageReadmeFilePath>
-		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/ReadMe.md')">$(MSBuildProjectDirectory)/ReadMe.md</_PackageReadmeFilePath>
+		<!-- Detect a package readme file in the project directory to pack as the package readme.
+		     Set 'SearchReadmeFileAbove' to 'true' to also search the parent directories.
+		     This is the package readme for consumers; a README.md in the repository is not packed. -->
+		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/PACKAGE.md')">$(MSBuildProjectDirectory)/PACKAGE.md</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/package.md')">$(MSBuildProjectDirectory)/package.md</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/Package.md')">$(MSBuildProjectDirectory)/Package.md</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(_PackageReadmeFilePath)' == '' AND Exists('$(MSBuildProjectDirectory)/PackAge.md')">$(MSBuildProjectDirectory)/PackAge.md</_PackageReadmeFilePath>
 
-		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('README.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('README.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
-		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('readme.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('readme.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
-		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('Readme.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('Readme.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
-		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('ReadMe.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('ReadMe.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('PACKAGE.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('PACKAGE.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('package.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('package.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('Package.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('Package.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
+		<_PackageReadmeFilePath Condition="'$(SearchReadmeFileAbove)' == 'true' AND '$(_PackageReadmeFilePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('PackAge.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('PackAge.md', '$(MSBuildProjectDirectory)'))</_PackageReadmeFilePath>
 
 		<_PackageThirdPartyNoticesPath Condition="'$(_PackageThirdPartyNoticesPath)' == '' AND Exists('$(MSBuildProjectDirectory)/THIRD-PARTY-NOTICES.TXT')">$(MSBuildProjectDirectory)/THIRD-PARTY-NOTICES.TXT</_PackageThirdPartyNoticesPath>
 		<_PackageThirdPartyNoticesPath Condition="'$(_PackageThirdPartyNoticesPath)' == '' AND Exists('$(MSBuildProjectDirectory)/THIRD-PARTY-NOTICES.txt')">$(MSBuildProjectDirectory)/THIRD-PARTY-NOTICES.txt</_PackageThirdPartyNoticesPath>
@@ -60,13 +61,13 @@
 		<_LicensePath Condition="'$(_LicensePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('LICENSE.md', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('LICENSE.md', '$(MSBuildProjectDirectory)'))</_LicensePath>
 		<_LicensePath Condition="'$(_LicensePath)' == '' AND Exists($([MSBuild]::GetPathOfFileAbove('LICENSE', '$(MSBuildProjectDirectory)')))">$([MSBuild]::GetPathOfFileAbove('LICENSE', '$(MSBuildProjectDirectory)'))</_LicensePath>
 
-		<PackageReadmeFile Condition="'$(PackageReadmeFile)' == '' AND '$(_PackageReadmeFilePath)' != ''">README.md</PackageReadmeFile>
+		<PackageReadmeFile Condition="'$(PackageReadmeFile)' == '' AND '$(_PackageReadmeFilePath)' != ''">PACKAGE.md</PackageReadmeFile>
 		<!-- Declare the detected license file in the nuspec, unless the project already declares a license expression or file -->
 		<PackageLicenseFile Condition="'$(PackageLicenseFile)' == '' AND '$(PackageLicenseExpression)' == '' AND '$(_LicensePath)' != ''">$([System.IO.Path]::GetFileName($(_LicensePath)))</PackageLicenseFile>
 	</PropertyGroup>
 
 	<ItemGroup>
-		<None Include="$(_PackageReadmeFilePath)" Pack="true" PackagePath="README.md" Condition="'$(_PackageReadmeFilePath)' != ''" />
+		<None Include="$(_PackageReadmeFilePath)" Pack="true" PackagePath="PACKAGE.md" Condition="'$(_PackageReadmeFilePath)' != ''" />
 		<None Include="$(_PackageThirdPartyNoticesPath)" Pack="true" PackagePath="" Condition="'$(_PackageThirdPartyNoticesPath)' != ''" />
 		<None Include="$(_LicensePath)" Pack="true" PackagePath="" Visible="false" Condition="'$(_LicensePath)' != ''" />
 	</ItemGroup>