diff --git a/docs/fundamentals/package-validation/baseline-version-validator.md b/docs/fundamentals/package-validation/baseline-version-validator.md index 16e67460f1a5d..eb9b0875039a2 100644 --- a/docs/fundamentals/package-validation/baseline-version-validator.md +++ b/docs/fundamentals/package-validation/baseline-version-validator.md @@ -17,7 +17,7 @@ For example, consider the following scenario. You're working on the AdventureWor net6.0 - 2.0.0 + 1.1.0 true 1.0.0 @@ -45,17 +45,13 @@ public static HttpClient Connect(string url, TimeSpan timeout = default) However, when you try to pack, it throws an error. -```cmd +```dotnetcli D:\demo>dotnet pack -Microsoft (R) Build Engine version 17.0.0-preview-21460-01+8f208e609 for .NET -Copyright (C) Microsoft Corporation. All rights reserved. - +MSBuild version 17.3.2+561848881 for .NET Determining projects to restore... All projects are up-to-date for restore. - You are using a preview version of .NET. See: https://aka.ms/dotnet-core-preview - PackageValidationThrough -> D:\demo\bin\Debug\net6.0\PackageValidationThrough.dll - Successfully created package 'D:\demo\bin\Debug\PackageValidationThrough.2.0.0.nupkg'. -C:\Program Files\dotnet\sdk\6.0.100-rc.1.21463.6\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Compatibility.Common.targets(32,5): error CP0002: Member 'A.B.Connect(string)' exists on [Baseline] lib/net6.0/PackageValidationThrough.dll but not on lib/net6.0/PackageValidationThrough.dll [D:\demo\PackageValidationThrough.csproj] + AdventureWorks.Client -> D:\demo\bin\Debug\net6.0\AdventureWorks.Client.dll +C:\Program Files\dotnet\sdk\6.0.413\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Compatibility.Common.targets(33,5): error CP0002: Member 'A.B.Connect(string)' exists on [Baseline] lib/net6.0/AdventureWorks.Client.dll but not on lib/net6.0/AdventureWorks.Client.dll [D:\demo\AdventureWorks.Client.csproj] ``` ![BaselineVersion](media/baseline-version.png) @@ -77,3 +73,64 @@ public static HttpClient Connect(string url, TimeSpan timeout) Now when you pack the project, it succeeds. ![BaselineVersionSuccessful](media/baseline-version-successful.png) + +For version 2.0.0 you later decide you want to remove obsolete `Connect` method with the single `string` parameter and upon careful consideration deliberately decide to accept this breaking change. + +```xml + + + + net6.0 + 2.0.0 + true + 1.1.0 + + + +``` + +```diff +- public static HttpClient Connect(string url) +- { +- return Connect(url, Timeout.InfiniteTimeSpan); +- } + +public static HttpClient Connect(string url, TimeSpan timeout) +{ + // ... +} +``` + +To suppress the `CP0002` error for this intentional breaking change, you can add a *CompatibilitySuppressions.xml* file to your project. By calling `dotnet pack /p:GenerateCompatibilitySuppressionFile=true` once, this file can be generated automatically. It contains a suppression for each validation error that occurred during pack. For more information, see [Suppress compatibility errors](overview.md#suppress-compatibility-errors). + +In this example, the *CompatibilitySuppressions.xml* contains the suppression for the `CP0002` error: + +```xml + + + + CP0002 + M:A.B.Connect(System.String) + lib/net6.0/AdventureWorks.Client.dll + lib/net6.0/AdventureWorks.Client.dll + true + + +``` + +This file should be checked into source control to document and review the breaking changes made in a PR and the upcoming release. + +After you have released version 2.0.0 of the package, you would delete the *CompatibilitySuppressions.xml* file and update the `PackageValidationBaselineVersion` property to validate future changes against the new release. + +```xml + + + + net6.0 + 2.1.0 + true + 2.0.0 + + + +``` diff --git a/docs/fundamentals/package-validation/media/baseline-version-successful.png b/docs/fundamentals/package-validation/media/baseline-version-successful.png index 290cbeb984db4..f52faa25ee7ae 100644 Binary files a/docs/fundamentals/package-validation/media/baseline-version-successful.png and b/docs/fundamentals/package-validation/media/baseline-version-successful.png differ diff --git a/docs/fundamentals/package-validation/media/baseline-version.png b/docs/fundamentals/package-validation/media/baseline-version.png index 2508574b3fb84..dd919a5031cec 100644 Binary files a/docs/fundamentals/package-validation/media/baseline-version.png and b/docs/fundamentals/package-validation/media/baseline-version.png differ