From 8965e21e688307b3991b3fe850988ec95289895e Mon Sep 17 00:00:00 2001
From: Nate McMaster <natemcmaster@users.noreply.github.com>
Date: Mon, 15 Apr 2019 18:00:59 -0700
Subject: [PATCH 1/3] Suppress warnings about breaking changes to
 Newtonsoft.Json dependency in SignalR

---
 docs/BuildErrors.md                             | 17 +++++++++++++++++
 docs/ReferenceResolution.md                     | 14 ++++++++++++++
 eng/targets/ResolveReferences.targets           | 11 ++++++++---
 ...rosoft.AspNetCore.SignalR.Client.Core.csproj |  5 +++++
 ...ft.AspNetCore.Http.Connections.Common.csproj |  5 +++++
 ...oft.AspNetCore.SignalR.Protocols.Json.csproj |  5 +++++
 .../Microsoft.AspNetCore.SignalR.Common.csproj  |  5 +++++
 version.props                                   |  1 +
 8 files changed, 60 insertions(+), 3 deletions(-)
 create mode 100644 docs/BuildErrors.md

diff --git a/docs/BuildErrors.md b/docs/BuildErrors.md
new file mode 100644
index 000000000000..1faebb5f8dda
--- /dev/null
+++ b/docs/BuildErrors.md
@@ -0,0 +1,17 @@
+Build Errors
+------------
+
+This document is for common build errors and how to resolve them.
+
+### Warning BUILD001
+
+> warning BUILD001: Package references changed since the last release...
+
+This warning indicates a breaking change might have been made to a package or assembly due to the removal of a reference which was used
+in a previous release of this assembly. See <./ReferenceResolution.md> for how to suppress.
+
+### Error BUILD002
+
+> error BUILD002: Package references changed since the last release...
+
+Similar to BUILD001, but this error not suppressable. This error only appears in servicing builds which should not change references between assemblies or packages.
diff --git a/docs/ReferenceResolution.md b/docs/ReferenceResolution.md
index 4acb23b2b83a..7d1e20c0cc25 100644
--- a/docs/ReferenceResolution.md
+++ b/docs/ReferenceResolution.md
@@ -25,6 +25,7 @@ The requirements that led to this system are:
 * Name the .csproj file to match the assembly name.
 * Run `build.cmd /t:GenerateProjectList` when adding new projects
 * Use [eng/tools/BaseLineGenerator/](/eng/tools/BaselineGenerator/README.md) if you need to update baselines.
+* If you need to make a breaking change to dependencies, you may need to add `<SuppressBaselineReference>`.
 
 ## Important files
 
@@ -67,3 +68,16 @@ Steps for adding a new package dependency to an existing project. Let's say I'm
 
        If you don't know the commit hash of the source code used to produce "0.0.1-beta-1", you can use `000000` as a placeholder for `Sha`
        as its value is unimportant and will be updated the next time the bot runs.
+
+## Example: make a breaking change to references
+
+If Microsoft.AspNetCore.Banana in 2.1 had a reference to `Microsoft.AspNetCore.Orange`, but in 3.0 this reference is changing to `Microsoft.AspNetCore.BetterThanOrange`, you would need to make these changes to the .csproj file
+
+```diff
+<!-- in Microsoft.AspNetCore.Banana.csproj -->
+  <ItemGroup>
+-    <Reference Include="Microsoft.AspNetCore.Orange" /> <!-- the old dependency -->
++    <Reference Include="Microsoft.AspNetCore.BetterThanOrange" /> <!-- the new dependency -->
++    <SuppressBaselineReference Include="Microsoft.AspNetCore.Orange" /> <!-- suppress as a known breaking change -->
+  </ItemGroup>
+```
diff --git a/eng/targets/ResolveReferences.targets b/eng/targets/ResolveReferences.targets
index 3eeface237fa..a606b9646659 100644
--- a/eng/targets/ResolveReferences.targets
+++ b/eng/targets/ResolveReferences.targets
@@ -147,7 +147,7 @@
       </Reference>
 
       <!-- Identify if any references were present in the last release of this package, but have been removed. -->
-      <UnusedBaselinePackageReference Include="@(BaselinePackageReference)" Exclude="@(Reference);@(_ProjectReferenceByAssemblyName);@(PackageReference)" />
+      <UnusedBaselinePackageReference Include="@(BaselinePackageReference)" Exclude="@(SuppressBaselineReference);@(Reference);@(_ProjectReferenceByAssemblyName);@(PackageReference)" />
 
       <!--
         MSBuild does not provide a way to join on matching identities in a Condition,
@@ -201,8 +201,13 @@
       <_ExplicitPackageReference Remove="@(_ExplicitPackageReference)" />
     </ItemGroup>
 
-    <Warning Condition="@(UnusedBaselinePackageReference->Count()) != 0"
-             Text="Package references changed since the last release. This could be a breaking change. References removed:%0A - @(UnusedBaselinePackageReference, '%0A -')" />
+    <Warning Condition="'$(IsReferenceAssemblyProject)' != 'true' AND '$(IsServicingBuild)' != 'true' AND '%(UnusedBaselinePackageReference.Identity)' != ''"
+             Code="BUILD001"
+             Text="Reference to '%(UnusedBaselinePackageReference.Identity)' was removed since the last stable release of this package. This could be a breaking change. See docs/ReferenceResolution.md for instructions on how to update changes to references or suppress this warning if the error was intentional." />
+
+    <Error Condition="'$(IsReferenceAssemblyProject)' != 'true' AND '$(IsServicingBuild)' == 'true' AND @(UnusedBaselinePackageReference->Count()) != 0"
+           Code="BUILD002"
+           Text="Package references changed since the last release. This could be a breaking change and is not allowed in a servicing update. References removed:%0A - @(UnusedBaselinePackageReference, '%0A -')" />
 
     <Error Condition="'$(TargetFrameworkIdentifier)' != '.NETFramework' AND '%(Reference.Identity)' != '' AND ! Exists('%(Reference.Identity)') AND '$(DisablePackageReferenceRestrictions)' != 'true'"
            Code="MSB3245"
diff --git a/src/SignalR/clients/csharp/Client.Core/src/Microsoft.AspNetCore.SignalR.Client.Core.csproj b/src/SignalR/clients/csharp/Client.Core/src/Microsoft.AspNetCore.SignalR.Client.Core.csproj
index 7c97496450e8..ac01f69d59c8 100644
--- a/src/SignalR/clients/csharp/Client.Core/src/Microsoft.AspNetCore.SignalR.Client.Core.csproj
+++ b/src/SignalR/clients/csharp/Client.Core/src/Microsoft.AspNetCore.SignalR.Client.Core.csproj
@@ -28,4 +28,9 @@
     <Reference Include="System.Threading.Channels" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(AspNetCoreMajorMinorVersion)' == '3.0'">
+    <!-- This dependency was replaced by Protocols.NewtonsoftJson between 3.0 and 2.2. This suppression can be removed after 3.0 is complete. -->
+    <SuppressBaselineReference Include="Microsoft.AspNetCore.SignalR.Protocols.Json" />
+  </ItemGroup>
+
 </Project>
diff --git a/src/SignalR/common/Http.Connections.Common/src/Microsoft.AspNetCore.Http.Connections.Common.csproj b/src/SignalR/common/Http.Connections.Common/src/Microsoft.AspNetCore.Http.Connections.Common.csproj
index 6b877415aa61..334dbdd502c4 100644
--- a/src/SignalR/common/Http.Connections.Common/src/Microsoft.AspNetCore.Http.Connections.Common.csproj
+++ b/src/SignalR/common/Http.Connections.Common/src/Microsoft.AspNetCore.Http.Connections.Common.csproj
@@ -24,4 +24,9 @@
     <Reference Include="System.Runtime.CompilerServices.Unsafe" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(AspNetCoreMajorMinorVersion)' == '3.0'">
+    <!-- This dependency was replaced by System.Text.Json between 3.0 and 2.2. This suppression can be removed after 3.0 is complete. -->
+    <SuppressBaselineReference Include="Newtonsoft.Json" />
+  </ItemGroup>
+
 </Project>
diff --git a/src/SignalR/common/Protocols.Json/src/Microsoft.AspNetCore.SignalR.Protocols.Json.csproj b/src/SignalR/common/Protocols.Json/src/Microsoft.AspNetCore.SignalR.Protocols.Json.csproj
index a115330e1ba1..c1f31c3e5437 100644
--- a/src/SignalR/common/Protocols.Json/src/Microsoft.AspNetCore.SignalR.Protocols.Json.csproj
+++ b/src/SignalR/common/Protocols.Json/src/Microsoft.AspNetCore.SignalR.Protocols.Json.csproj
@@ -27,4 +27,9 @@
     <Reference Include="System.Runtime.CompilerServices.Unsafe" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(AspNetCoreMajorMinorVersion)' == '3.0'">
+    <!-- This dependency was replaced by System.Text.Json between 3.0 and 2.2. This suppression can be removed after 3.0 is complete. -->
+    <SuppressBaselineReference Include="Newtonsoft.Json" />
+  </ItemGroup>
+
 </Project>
diff --git a/src/SignalR/common/SignalR.Common/src/Microsoft.AspNetCore.SignalR.Common.csproj b/src/SignalR/common/SignalR.Common/src/Microsoft.AspNetCore.SignalR.Common.csproj
index 66dae2f3c0cb..f5689810426b 100644
--- a/src/SignalR/common/SignalR.Common/src/Microsoft.AspNetCore.SignalR.Common.csproj
+++ b/src/SignalR/common/SignalR.Common/src/Microsoft.AspNetCore.SignalR.Common.csproj
@@ -29,4 +29,9 @@
     <Reference Include="System.Runtime.CompilerServices.Unsafe" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(AspNetCoreMajorMinorVersion)' == '3.0'">
+    <!-- This dependency was replaced by System.Text.Json between 3.0 and 2.2. This suppression can be removed after 3.0 is complete. -->
+    <SuppressBaselineReference Include="Newtonsoft.Json" />
+  </ItemGroup>
+
 </Project>
diff --git a/version.props b/version.props
index 5d7bcf2f9206..228a6c4b43fd 100644
--- a/version.props
+++ b/version.props
@@ -8,6 +8,7 @@
     <PreReleaseBrandingLabel>Preview $(PreReleasePreviewNumber)</PreReleaseBrandingLabel>
     <ExperimentalVersionPrefix>0.3.$(AspNetCorePatchVersion)</ExperimentalVersionPrefix>
     <BlazorComponentsVersionPrefix>0.9.$(AspNetCorePatchVersion)</BlazorComponentsVersionPrefix>
+    <AspNetCoreMajorMinorVersion>$(AspNetCoreMajorVersion).$(AspNetCoreMinorVersion)</AspNetCoreMajorMinorVersion>
     <VersionPrefix>$(AspNetCoreMajorVersion).$(AspNetCoreMinorVersion).$(AspNetCorePatchVersion)</VersionPrefix>
 
     <!-- ANCM versioning is intentionally 10 + AspNetCoreMajorVersion because earlier versions of ANCM shipped as 8.x. -->

From 220985eda91ba6a0aade2e9ab30474615cf01282 Mon Sep 17 00:00:00 2001
From: Nate McMaster <natemcmaster@users.noreply.github.com>
Date: Mon, 15 Apr 2019 18:06:51 -0700
Subject: [PATCH 2/3] fixup! Suppress warnings about breaking changes to
 Newtonsoft.Json dependency in SignalR

---
 eng/targets/ResolveReferences.targets | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/eng/targets/ResolveReferences.targets b/eng/targets/ResolveReferences.targets
index a606b9646659..204c281f88da 100644
--- a/eng/targets/ResolveReferences.targets
+++ b/eng/targets/ResolveReferences.targets
@@ -147,7 +147,9 @@
       </Reference>
 
       <!-- Identify if any references were present in the last release of this package, but have been removed. -->
-      <UnusedBaselinePackageReference Include="@(BaselinePackageReference)" Exclude="@(SuppressBaselineReference);@(Reference);@(_ProjectReferenceByAssemblyName);@(PackageReference)" />
+      <UnusedBaselinePackageReference Include="@(BaselinePackageReference)" Exclude="@(Reference);@(_ProjectReferenceByAssemblyName);@(PackageReference)" />
+      <!-- Only allow suppressing baseline changes in non-servicing builds. -->
+      <UnusedBaselinePackageReference Remove="@(SuppressBaselineReference)" Condition="'$(IsServicingBuild)' != 'true'"/>
 
       <!--
         MSBuild does not provide a way to join on matching identities in a Condition,

From 14b2fa0e1d4eba5c176f732457cf3d95253f0afa Mon Sep 17 00:00:00 2001
From: Nate McMaster <natemcmaster@users.noreply.github.com>
Date: Tue, 16 Apr 2019 09:10:35 -0700
Subject: [PATCH 3/3] Update BuildErrors.md

---
 docs/BuildErrors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/BuildErrors.md b/docs/BuildErrors.md
index 1faebb5f8dda..be5f94a56082 100644
--- a/docs/BuildErrors.md
+++ b/docs/BuildErrors.md
@@ -14,4 +14,4 @@ in a previous release of this assembly. See <./ReferenceResolution.md> for how t
 
 > error BUILD002: Package references changed since the last release...
 
-Similar to BUILD001, but this error not suppressable. This error only appears in servicing builds which should not change references between assemblies or packages.
+Similar to BUILD001, but this error is not suppressable. This error only appears in servicing builds, which should not change references between assemblies or packages.