dotnet / dotnet/docs

CompatibilitySuppressions.xml file format is not fully documented

Open
#36,988 0 comments 3 reactions 0 assignees View on GitHub
:watch: Not Triaged dotnet-fundamentals/svc
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
19h 10m
Merged PRs (30d)
268

Description

The article describes the basic structure of the _CompatibilitySuppressions.xml_ file but leaves out a lot of interesting details.
Since there is no tooling or IDE integration for this, it must be read and understood manually to assess the breaking changes made in a PR or in an upcoming release.

For example:
- The rules itself are not documented (similar to https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules). It is not even clear what rules exist.
- Depending on the rule, ``, ``, `` may contain different types of content or the element can be omitted altogether (e.g. [PKV0001](https://github.com/dotnet/aspnetcore/blob/17993688eff8a3fc91a91985713ecd3c482a6ce7/src/Framework/App.Runtime/src/CompatibilitySuppressions.xml#L4) vs. [CP1002](https://github.com/dotnet/aspnetcore/blob/17993688eff8a3fc91a91985713ecd3c482a6ce7/src/Caching/SqlServer/src/CompatibilitySuppressions.xml#L4) vs. [CP0002](https://github.com/dotnet/ClangSharp/blob/32bbe8a857ce8e723557ba50dc78b4126bf9717b/sources/ClangSharp/CompatibilitySuppressions.xml#L5)). How must valid content look like?

> Just a side note: That file might not really be review-friendly for humans because it is a bit hard to parse and the file format is not fully documented.

_Originally posted by @bitbonk in https://github.com/dotnet/docs/pull/36954#discussion_r1313887454_

---
#### Document Details

⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*

* ID: 1076d3b1-dc45-1cc3-5961-8e369a9db793
* Version Independent ID: aec40896-e18d-a61d-2dbb-467556b24678
* Content: [.NET Package Validation - .NET](https://learn.microsoft.com/en-us/dotnet/fundamentals/package-validation/overview)
* Content Source: [docs/fundamentals/package-validation/overview.md](https://github.com/dotnet/docs/blob/main/docs/fundamentals/package-validation/overview.md)
* Product: **dotnet-fundamentals**
* GitHub Login: @dotnet-bot
* Microsoft Alias: **dotnetcontent**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.