diff --git a/README.md b/README.md index 3a57ab1..7a96285 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,12 @@ reported a the [GibHub repository](https://github.com/dotnet-project-file-analyz * [**Proj0244** Generate documentation file](rules/Proj0244.md) * [**Proj0245** Don't mix Version and VersionPrefix/VersionSuffix](rules/Proj0245.md) * [**Proj0246** Define VersionPrefix if VersionSuffix is defined](rules/Proj0246.md) +* [**Proj0247** Enable strict mode for package baseline validation](rules/Proj0247.md) +* [**Proj0248** Enable strict mode for package runtime compatibility validation](rules/Proj0248.md) +* [**Proj0249** Enable strict mode for package framework compatibility validation](rules/Proj0249.md) +* [**Proj0250** Generate API compatibility suppression file](rules/Proj0250.md) +* [**Proj0251** Enable API compatibility attribute checks](rules/Proj0251.md) +* [**Proj0252** Enable API compatibility parameter name checks](rules/Proj0252.md) * [**Proj0600** Avoid generating packages on build if not packable](rules/Proj0600.md) ### Publishing diff --git a/rules/Proj0247.md b/rules/Proj0247.md new file mode 100644 index 0000000..40af589 --- /dev/null +++ b/rules/Proj0247.md @@ -0,0 +1,53 @@ +--- +parent: Packaging +ancestor: Rules +--- + +# Proj0247: Enable strict mode for package baseline validation +When ensuring backwards compatibility of the API surface +of your package, it is advised to do this in strict mode. +This helps preventing any unintentional API changes. + +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). + +## Non-compliant +``` xml + + + + net8.0 + true + 1.0.0 + false + + + +``` + +Or: + +``` xml + + + + net8.0 + true + 1.0.0 + + + +``` + +## Compliant +``` xml + + + + net8.0 + true + 1.0.0 + true + + + +``` diff --git a/rules/Proj0248.md b/rules/Proj0248.md new file mode 100644 index 0000000..899b691 --- /dev/null +++ b/rules/Proj0248.md @@ -0,0 +1,52 @@ +--- +parent: Packaging +ancestor: Rules +--- + +# Proj0248: Enable strict mode for package runtime compatibility validation +When building your package for multiple runtimes it +is advised to enable the strict mode of the runtime +compatibility validation. + +Note that the default value is `true` and can therefore be omitted. + +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). + +## Non-compliant +``` xml + + + + net8.0 + true + false + + + +``` + +## Compliant +``` xml + + + + net8.0 + true + + + +``` + +Or: + +``` xml + + + + net8.0 + true + true + + + +``` diff --git a/rules/Proj0249.md b/rules/Proj0249.md new file mode 100644 index 0000000..13f18ca --- /dev/null +++ b/rules/Proj0249.md @@ -0,0 +1,50 @@ +--- +parent: Packaging +ancestor: Rules +--- + +# Proj0249: Enable strict mode for package framework compatibility validation +When building your package for multiple target +frameworks it is advised to enable the strict +mode of the framework compatibility validation. + +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). + +## Non-compliant +``` xml + + + + net8.0 + true + false + + + +``` + +Or: + +``` xml + + + + net8.0 + true + + + +``` + +## Compliant +``` xml + + + + net8.0 + true + true + + + +``` diff --git a/rules/Proj0250.md b/rules/Proj0250.md new file mode 100644 index 0000000..1641264 --- /dev/null +++ b/rules/Proj0250.md @@ -0,0 +1,62 @@ +--- +parent: Packaging +ancestor: Rules +--- + +# Proj0250: Generate API compatibility suppression file +When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) is enabled, it is required to +provide a [suppression file](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids#how-to-suppress) for all differences that +occur in the API: +- [Changes between different package versions](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/baseline-version-validator) +- [Differences between different runtimes (e.g. windows vs unix)](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/compatible-framework-validator) +- [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) + +This suppression file can be created manually, or automatically generated +by enabling the `GenerateCompatibilitySuppressionFile` property. It is advised +to enable this property in the project file to ensure that the file is kept +up-to-date automatically. + +Additionally, it is advised to keep changes to the generated file tracked in +your version control system to ensure any API changes are explicitly included +in code reviews. + +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). + +## Non-compliant +``` xml + + + + net8.0 + true + false + + + +``` + +Or: + +``` xml + + + + net8.0 + true + + + +``` + +## Compliant +``` xml + + + + net8.0 + true + true + + + +``` diff --git a/rules/Proj0251.md b/rules/Proj0251.md new file mode 100644 index 0000000..394c8e9 --- /dev/null +++ b/rules/Proj0251.md @@ -0,0 +1,49 @@ +--- +parent: Packaging +ancestor: Rules +--- + +# Proj0251: Enable API compatibility attribute checks +When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) +is enabled, it is advised to opt-in to the strict attribute compatibility checks. + +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). + +## Non-compliant +``` xml + + + + net8.0 + true + false + + + +``` + +Or: + +``` xml + + + + net8.0 + true + + + +``` + +## Compliant +``` xml + + + + net8.0 + true + true + + + +``` diff --git a/rules/Proj0252.md b/rules/Proj0252.md new file mode 100644 index 0000000..6746cd6 --- /dev/null +++ b/rules/Proj0252.md @@ -0,0 +1,53 @@ +--- +parent: Packaging +ancestor: Rules +--- + +# Proj0252: Enable API compatibility parameter name checks +When [package validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/package-validation/overview) +is enabled, it is advised to opt-in to the strict parameter name compatibility checks. +While renaming parameters does not directly break runtime compatibility, it can break +source compatibility when a consuming application uses +[explicit parameter names](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments) +when calling one of your methods. + +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). + +## Non-compliant +``` xml + + + + net8.0 + true + false + + + +``` + +Or: + +``` xml + + + + net8.0 + true + + + +``` + +## Compliant +``` xml + + + + net8.0 + true + true + + + +```