Suppress warnings about breaking changes to Newtonsoft.Json dependency in SignalR (#9405)

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 is not suppressable. This error only appears in servicing builds, which should not change references between assemblies or packages.

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>
+```

eng/targets/ResolveReferences.targets

@@ -148,6 +148,8 @@
 
       <!-- Identify if any references were present in the last release of this package, but have been removed. -->
       <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,
@@ -201,8 +203,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"

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>

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>

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>

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>

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. -->