dotnet / dotnet/sdk

[API Compat] Problematic developer experience of compatibility suppressions

Open
#45,928 3 comments 1 reaction 1 assignee Claimed by @ViktorHofer View on GitHub
Area-ApiCompat
Dominant language
C#
Stars
3.2k
Forks
1.3k
PR merge metrics
PR metrics pending

Description

### Is your feature request related to a problem? Please describe.
The [package validation](https://learn.microsoft.com/dotnet/fundamentals/apicompat/diagnostic-ids#how-to-suppress) of the .NET SDK allows me to selectively accept/ignore a breaking changes using ` CompatibilitySuppressions.xml` files.

Unfortunately, for a human being, this file is very hard to parse and almost impossible to write.
This has the following problems during daily development of libraries:

1. When faced with a PR that contains new entries in ` CompatibilitySuppressions.xml` it is very hard to understand what the breaking change actually is. The way we currently often examine these suppression in a code review is, we checkout the PR branch locally, temporarily remove the new suppression entries and then pack the projects in question, so we can see a human readable error message. so instead of the somewhat incomprehensible suppression
```xml

CP0008
T:Foo.Bar.MyClass
lib/net8.0/MyAssembly.dll
lib/net8.0/MyAssembly.dll
true

```
the reviewer now has the proper error message again:
`error CP0008: Type 'Foo.Bar.MyClass' does not implement interface 'Foo.Bar.IMyInterface' on lib/net8.0/MyAssembly.dll but it does on [Baseline] lib/net8.0/MyAssembly.dll`
2. There is no good way for the PR author to document in the source code, _why_ this particular breaking change is acceptable here.
Adding an XML comment into the suppression file would be overwritten when the suppression file is regenerated the next time a new breaking change is accepted.

```xml


CP0008
T:Foo.Bar.MyClass
lib/net8.0/MyAssembly.dll
lib/net8.0/MyAssembly.dll
true

```

### Describe the solution you'd like
1. Also include the actual error message right in the supression entry. This would solve problem 1. Something similar like the example below
```xml

CP0008
Type 'Foo.Bar.MyClass' does not implement interface 'Foo.Bar.IMyInterface' on lib/net8.0/MyAssembly.dll but it does on [Baseline] lib/net8.0/MyAssembly.dll
T:Foo.Bar.MyClass
lib/net8.0/MyAssembly.dll
lib/net8.0/MyAssembly.dll
true

```
2. When regenerating the ` CompatibilitySuppressions.xml` file, leave all existing modifications to that file unchanged as long as it does not change the sematics of the supressions. This could solve problem 1 and 2 because we can now add helpful comments to the suppressions, like this:
```xml



CP0008
T:Foo.Bar.MyClass
lib/net8.0/MyAssembly.dll
lib/net8.0/MyAssembly.dll
true

```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.