From fee2f02312380590b5268018cee0069d58efd45a Mon Sep 17 00:00:00 2001
From: Jan Jones <janjones@microsoft.com>
Date: Wed, 17 Jul 2024 12:50:05 +0200
Subject: [PATCH 1/4] Improve Sdk.Compilers.Toolset package description

---
 .../Microsoft.Net.Sdk.Compilers.Toolset.csproj | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
index 29ced3c4e5db..716a6b484e37 100644
--- a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
+++ b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
@@ -2,7 +2,23 @@
 
   <PropertyGroup>
     <TargetFramework>$(SdkTargetFramework)</TargetFramework>
-    <Description>Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only.</Description>
+    <Description><![CDATA[
+      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only.
+
+      This package is automatically downloaded when your MSBuild version does not match your SDK version.
+      Then your project uses the compiler version matching your SDK version instead of the one bundled with MSBuild.
+
+      If you want to disable this behavior, set property `BuildWithNetFrameworkHostedCompiler` to `false`
+      in your `.csproj` or `Directory.Build.props` file, for example:
+
+      ```csproj
+      <Project>
+        <PropertyGroup>
+          <BuildWithNetFrameworkHostedCompiler>false</BuildWithNetFrameworkHostedCompiler>
+        </ProperyGroup>
+      </Project>
+      ```
+    ]]></Description>
     <IsPackable>true</IsPackable>
     <IsShippingPackage>true</IsShippingPackage>
     <IncludeBuildOutput>false</IncludeBuildOutput>

From fd380629bcb9dc905e0d707eb86a7b933d751832 Mon Sep 17 00:00:00 2001
From: Jan Jones <jan.jones.cz@gmail.com>
Date: Wed, 17 Jul 2024 16:00:20 +0200
Subject: [PATCH 2/4] Extend the description

Co-authored-by: Rainer Sigwald <raines@microsoft.com>
---
 .../Microsoft.Net.Sdk.Compilers.Toolset.csproj                  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
index 716a6b484e37..17611e618fa4 100644
--- a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
+++ b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
@@ -3,7 +3,7 @@
   <PropertyGroup>
     <TargetFramework>$(SdkTargetFramework)</TargetFramework>
     <Description><![CDATA[
-      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only.
+      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only: do not reference this package directly.
 
       This package is automatically downloaded when your MSBuild version does not match your SDK version.
       Then your project uses the compiler version matching your SDK version instead of the one bundled with MSBuild.

From 3862b9d44747be2d52a3e07dc147d7104056f085 Mon Sep 17 00:00:00 2001
From: Jan Jones <jan.jones.cz@gmail.com>
Date: Thu, 18 Jul 2024 10:24:49 +0200
Subject: [PATCH 3/4] Extend the description

Co-authored-by: Jared Parsons <jared@paranoidcoding.org>
---
 .../Microsoft.Net.Sdk.Compilers.Toolset.csproj                  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
index 17611e618fa4..850d42c5b69e 100644
--- a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
+++ b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
@@ -3,7 +3,7 @@
   <PropertyGroup>
     <TargetFramework>$(SdkTargetFramework)</TargetFramework>
     <Description><![CDATA[
-      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only: do not reference this package directly.
+      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only: do not reference this package directly as it is explicitly not supported in that fashion.
 
       This package is automatically downloaded when your MSBuild version does not match your SDK version.
       Then your project uses the compiler version matching your SDK version instead of the one bundled with MSBuild.

From dc50af32e152e3018acf100eca36ea7e70110766 Mon Sep 17 00:00:00 2001
From: Jan Jones <janjones@microsoft.com>
Date: Fri, 19 Jul 2024 11:16:37 +0200
Subject: [PATCH 4/4] Improve the text

---
 ...Microsoft.Net.Sdk.Compilers.Toolset.csproj | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
index 850d42c5b69e..6f2ed7fc7279 100644
--- a/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
+++ b/src/Microsoft.Net.Sdk.Compilers.Toolset/Microsoft.Net.Sdk.Compilers.Toolset.csproj
@@ -3,21 +3,23 @@
   <PropertyGroup>
     <TargetFramework>$(SdkTargetFramework)</TargetFramework>
     <Description><![CDATA[
-      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only: do not reference this package directly as it is explicitly not supported in that fashion.
+      Transport package for Microsoft.Net.Compilers.Toolset.Framework assemblies. For internal use only:
+      do not reference this package directly as it is explicitly not supported in that fashion.
 
       This package is automatically downloaded when your MSBuild version does not match your SDK version.
-      Then your project uses the compiler version matching your SDK version instead of the one bundled with MSBuild.
+      Then the package is used to build your project with the compiler version matching your SDK version
+      instead of the one bundled with MSBuild.
 
-      If you want to disable this behavior, set property `BuildWithNetFrameworkHostedCompiler` to `false`
-      in your `.csproj` or `Directory.Build.props` file, for example:
+      If you want to download this package using the dotnet CLI, you can use the following command:
 
-      ```csproj
-      <Project>
-        <PropertyGroup>
-          <BuildWithNetFrameworkHostedCompiler>false</BuildWithNetFrameworkHostedCompiler>
-        </ProperyGroup>
-      </Project>
       ```
+      dotnet restore /p:BuildWithNetFrameworkHostedCompiler=true
+      ```
+
+      If you want to disable automatic download and use of this package, set property `BuildWithNetFrameworkHostedCompiler` to `false`
+      (for example, in your `.csproj` or `Directory.Build.props` file).
+      However, be aware that you will be building with mismatched compiler and SDK versions.
+      That is explicitly not supported and can lead to errors (especially with analyzers and source generators).
     ]]></Description>
     <IsPackable>true</IsPackable>
     <IsShippingPackage>true</IsShippingPackage>