Skip to content

Commit 8563721

Browse files
CptWesleyLauraXiulan
CptWesley
and
LauraXiulan
authored
Add more rules for API compatibility validation (#83)
* Add more rules for API compatibility validation * Update rules/Proj0247.md Co-authored-by: Laura Kramer <[email protected]> * Update rules/Proj0248.md Co-authored-by: Laura Kramer <[email protected]> * Update rules/Proj0249.md Co-authored-by: Laura Kramer <[email protected]> * Update rules/Proj0250.md Co-authored-by: Laura Kramer <[email protected]> * Update rules/Proj0251.md Co-authored-by: Laura Kramer <[email protected]> * Update rules/Proj0252.md Co-authored-by: Laura Kramer <[email protected]> --------- Co-authored-by: Laura Kramer <[email protected]>
1 parent 6b8e2b9 commit 8563721

File tree

7 files changed

+325
-0
lines changed

7 files changed

+325
-0
lines changed

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,12 @@ reported a the [GibHub repository](https://github.com/dotnet-project-file-analyz
101101
* [**Proj0244** Generate documentation file](rules/Proj0244.md)
102102
* [**Proj0245** Don't mix Version and VersionPrefix/VersionSuffix](rules/Proj0245.md)
103103
* [**Proj0246** Define VersionPrefix if VersionSuffix is defined](rules/Proj0246.md)
104+
* [**Proj0247** Enable strict mode for package baseline validation](rules/Proj0247.md)
105+
* [**Proj0248** Enable strict mode for package runtime compatibility validation](rules/Proj0248.md)
106+
* [**Proj0249** Enable strict mode for package framework compatibility validation](rules/Proj0249.md)
107+
* [**Proj0250** Generate API compatibility suppression file](rules/Proj0250.md)
108+
* [**Proj0251** Enable API compatibility attribute checks](rules/Proj0251.md)
109+
* [**Proj0252** Enable API compatibility parameter name checks](rules/Proj0252.md)
104110
* [**Proj0600** Avoid generating packages on build if not packable](rules/Proj0600.md)
105111

106112
### Publishing

‎rules/Proj0247.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
parent: Packaging
3+
ancestor: Rules
4+
---
5+
6+
# Proj0247: Enable strict mode for package baseline validation
7+
When ensuring backwards compatibility of the API surface
8+
of your package, it is advised to do this in strict mode.
9+
This helps preventing any unintentional API changes.
10+
11+
More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/baseline-version-validator) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enablestrictmodeforbaselinevalidation).
12+
13+
## Non-compliant
14+
``` xml
15+
<Project Sdk="Microsoft.NET.Sdk">
16+
17+
<PropertyGroup>
18+
<TargetFramework>net8.0</TargetFramework>
19+
<EnablePackageValidation>true</EnablePackageValidation>
20+
<PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
21+
<EnableStrictModeForBaselineValidation>false</EnableStrictModeForBaselineValidation>
22+
</PropertyGroup>
23+
24+
</Project>
25+
```
26+
27+
Or:
28+
29+
``` xml
30+
<Project Sdk="Microsoft.NET.Sdk">
31+
32+
<PropertyGroup>
33+
<TargetFramework>net8.0</TargetFramework>
34+
<EnablePackageValidation>true</EnablePackageValidation>
35+
<PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
36+
</PropertyGroup>
37+
38+
</Project>
39+
```
40+
41+
## Compliant
42+
``` xml
43+
<Project Sdk="Microsoft.NET.Sdk">
44+
45+
<PropertyGroup>
46+
<TargetFramework>net8.0</TargetFramework>
47+
<EnablePackageValidation>true</EnablePackageValidation>
48+
<PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
49+
<EnableStrictModeForBaselineValidation>true</EnableStrictModeForBaselineValidation>
50+
</PropertyGroup>
51+
52+
</Project>
53+
```

‎rules/Proj0248.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
parent: Packaging
3+
ancestor: Rules
4+
---
5+
6+
# Proj0248: Enable strict mode for package runtime compatibility validation
7+
When building your package for multiple runtimes it
8+
is advised to enable the strict mode of the runtime
9+
compatibility validation.
10+
11+
Note that the default value is `true` and can therefore be omitted.
12+
13+
More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-validator) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enablestrictmodeforcompatibletfms).
14+
15+
## Non-compliant
16+
``` xml
17+
<Project Sdk="Microsoft.NET.Sdk">
18+
19+
<PropertyGroup>
20+
<TargetFramework>net8.0</TargetFramework>
21+
<EnablePackageValidation>true</EnablePackageValidation>
22+
<EnableStrictModeForCompatibleTfms>false</EnableStrictModeForCompatibleTfms>
23+
</PropertyGroup>
24+
25+
</Project>
26+
```
27+
28+
## Compliant
29+
``` xml
30+
<Project Sdk="Microsoft.NET.Sdk">
31+
32+
<PropertyGroup>
33+
<TargetFramework>net8.0</TargetFramework>
34+
<EnablePackageValidation>true</EnablePackageValidation>
35+
</PropertyGroup>
36+
37+
</Project>
38+
```
39+
40+
Or:
41+
42+
``` xml
43+
<Project Sdk="Microsoft.NET.Sdk">
44+
45+
<PropertyGroup>
46+
<TargetFramework>net8.0</TargetFramework>
47+
<EnablePackageValidation>true</EnablePackageValidation>
48+
<EnableStrictModeForCompatibleTfms>true</EnableStrictModeForCompatibleTfms>
49+
</PropertyGroup>
50+
51+
</Project>
52+
```

‎rules/Proj0249.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
parent: Packaging
3+
ancestor: Rules
4+
---
5+
6+
# Proj0249: Enable strict mode for package framework compatibility validation
7+
When building your package for multiple target
8+
frameworks it is advised to enable the strict
9+
mode of the framework compatibility validation.
10+
11+
More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-in-package-validator) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enablestrictmodeforcompatibleframeworksinpackage).
12+
13+
## Non-compliant
14+
``` xml
15+
<Project Sdk="Microsoft.NET.Sdk">
16+
17+
<PropertyGroup>
18+
<TargetFramework>net8.0</TargetFramework>
19+
<EnablePackageValidation>true</EnablePackageValidation>
20+
<EnableStrictModeForCompatibleFrameworksInPackage>false</EnableStrictModeForCompatibleFrameworksInPackage>
21+
</PropertyGroup>
22+
23+
</Project>
24+
```
25+
26+
Or:
27+
28+
``` xml
29+
<Project Sdk="Microsoft.NET.Sdk">
30+
31+
<PropertyGroup>
32+
<TargetFramework>net8.0</TargetFramework>
33+
<EnablePackageValidation>true</EnablePackageValidation>
34+
</PropertyGroup>
35+
36+
</Project>
37+
```
38+
39+
## Compliant
40+
``` xml
41+
<Project Sdk="Microsoft.NET.Sdk">
42+
43+
<PropertyGroup>
44+
<TargetFramework>net8.0</TargetFramework>
45+
<EnablePackageValidation>true</EnablePackageValidation>
46+
<EnableStrictModeForCompatibleFrameworksInPackage>true</EnableStrictModeForCompatibleFrameworksInPackage>
47+
</PropertyGroup>
48+
49+
</Project>
50+
```

‎rules/Proj0250.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
parent: Packaging
3+
ancestor: Rules
4+
---
5+
6+
# Proj0250: Generate API compatibility suppression file
7+
When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) is enabled, it is required to
8+
provide a [suppression file](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids#how-to-suppress) for all differences that
9+
occur in the API:
10+
- [Changes between different package versions](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/baseline-version-validator)
11+
- [Differences between different runtimes (e.g. windows vs unix)](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-validator)
12+
- [Differences between different target frameworks (e.g. netstandard2.0 vs net8.0)](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-in-package-validator)
13+
14+
This suppression file can be created manually, or automatically generated
15+
by enabling the `GenerateCompatibilitySuppressionFile` property. It is advised
16+
to enable this property in the project file to ensure that the file is kept
17+
up-to-date automatically.
18+
19+
Additionally, it is advised to keep changes to the generated file tracked in
20+
your version control system to ensure any API changes are explicitly included
21+
in code reviews.
22+
23+
More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids#how-to-suppress) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#apicompatgeneratesuppressionfile).
24+
25+
## Non-compliant
26+
``` xml
27+
<Project Sdk="Microsoft.NET.Sdk">
28+
29+
<PropertyGroup>
30+
<TargetFramework>net8.0</TargetFramework>
31+
<EnablePackageValidation>true</EnablePackageValidation>
32+
<ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
33+
</PropertyGroup>
34+
35+
</Project>
36+
```
37+
38+
Or:
39+
40+
``` xml
41+
<Project Sdk="Microsoft.NET.Sdk">
42+
43+
<PropertyGroup>
44+
<TargetFramework>net8.0</TargetFramework>
45+
<EnablePackageValidation>true</EnablePackageValidation>
46+
</PropertyGroup>
47+
48+
</Project>
49+
```
50+
51+
## Compliant
52+
``` xml
53+
<Project Sdk="Microsoft.NET.Sdk">
54+
55+
<PropertyGroup>
56+
<TargetFramework>net8.0</TargetFramework>
57+
<EnablePackageValidation>true</EnablePackageValidation>
58+
<ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
59+
</PropertyGroup>
60+
61+
</Project>
62+
```

‎rules/Proj0251.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
parent: Packaging
3+
ancestor: Rules
4+
---
5+
6+
# Proj0251: Enable API compatibility attribute checks
7+
When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview)
8+
is enabled, it is advised to opt-in to the strict attribute compatibility checks.
9+
10+
More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) and [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#apicompatenableruleattributesmustmatch).
11+
12+
## Non-compliant
13+
``` xml
14+
<Project Sdk="Microsoft.NET.Sdk">
15+
16+
<PropertyGroup>
17+
<TargetFramework>net8.0</TargetFramework>
18+
<EnablePackageValidation>true</EnablePackageValidation>
19+
<ApiCompatEnableRuleAttributesMustMatch>false</ApiCompatEnableRuleAttributesMustMatch>
20+
</PropertyGroup>
21+
22+
</Project>
23+
```
24+
25+
Or:
26+
27+
``` xml
28+
<Project Sdk="Microsoft.NET.Sdk">
29+
30+
<PropertyGroup>
31+
<TargetFramework>net8.0</TargetFramework>
32+
<EnablePackageValidation>true</EnablePackageValidation>
33+
</PropertyGroup>
34+
35+
</Project>
36+
```
37+
38+
## Compliant
39+
``` xml
40+
<Project Sdk="Microsoft.NET.Sdk">
41+
42+
<PropertyGroup>
43+
<TargetFramework>net8.0</TargetFramework>
44+
<EnablePackageValidation>true</EnablePackageValidation>
45+
<ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
46+
</PropertyGroup>
47+
48+
</Project>
49+
```

‎rules/Proj0252.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
parent: Packaging
3+
ancestor: Rules
4+
---
5+
6+
# Proj0252: Enable API compatibility parameter name checks
7+
When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview)
8+
is enabled, it is advised to opt-in to the strict parameter name compatibility checks.
9+
While renaming parameters does not directly break runtime compatibility, it can break
10+
source compatibility when a consuming application uses
11+
[explicit parameter names](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments)
12+
when calling one of your methods.
13+
14+
More information can be found [here](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview), [here](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#apicompatenablerulecannotchangeparametername) and [here](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments).
15+
16+
## Non-compliant
17+
``` xml
18+
<Project Sdk="Microsoft.NET.Sdk">
19+
20+
<PropertyGroup>
21+
<TargetFramework>net8.0</TargetFramework>
22+
<EnablePackageValidation>true</EnablePackageValidation>
23+
<ApiCompatEnableRuleCannotChangeParameterName>false</ApiCompatEnableRuleCannotChangeParameterName>
24+
</PropertyGroup>
25+
26+
</Project>
27+
```
28+
29+
Or:
30+
31+
``` xml
32+
<Project Sdk="Microsoft.NET.Sdk">
33+
34+
<PropertyGroup>
35+
<TargetFramework>net8.0</TargetFramework>
36+
<EnablePackageValidation>true</EnablePackageValidation>
37+
</PropertyGroup>
38+
39+
</Project>
40+
```
41+
42+
## Compliant
43+
``` xml
44+
<Project Sdk="Microsoft.NET.Sdk">
45+
46+
<PropertyGroup>
47+
<TargetFramework>net8.0</TargetFramework>
48+
<EnablePackageValidation>true</EnablePackageValidation>
49+
<ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
50+
</PropertyGroup>
51+
52+
</Project>
53+
```

0 commit comments

Comments
 (0)