From 2f701c0ca331dc833316fe1e59e62b1348e667d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9rald=20Barr=C3=A9?=
 <meziantou@users.noreply.github.com>
Date: Tue, 4 Jun 2024 14:17:44 -0400
Subject: [PATCH] Improve adoption documentation (#24)

---
 README.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 231518f..93fa69c 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,50 @@ dotnet format <path_to_your_solution_or_project> --severity warn --verbosity dia
 
 You can also modify the command to specify the IDs of the analysis rules you wish to automatically correct (if a fix is available). In this way, you avoid manual work, and breaking the correction into several pull requests will increase developers' confidence in the process of adopting new standards.
 
-All rules included in this package **can be disabled or modified** in an `.editorconfig` file that you can add to your project. You can also **disable a rule for a specific line or block of code** using `#pragma` directives or `[SuppressMessage]` attributes. Learn more about [configuring code analysis rules](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings). Remember to always justify why a rule is disabled or modified.
+All rules included in this package **can be disabled or modified** in an `.editorconfig` file that you can add to your project. You can also **disable a rule for a specific line or block of code** using `#pragma` directives or `[SuppressMessage]` attributes. Learn more about [configuring code analysis rules](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings). Remember to always justify why a rule is disabled or modified. Here're some examples:
+
+- Disable specific diagnostics in the code
+
+    ````c#
+    #pragma warning disable CA2200 // Rethrow to preserve stack details
+    throw e;
+    #pragma warning restore CA2200
+    ````
+
+- Disable specific diagnostics for a method
+
+    ````c#
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Usage", "CA2200:Rethrow to preserve stack details", Justification = "Not production code.")]
+    void Sample()
+    {
+    }
+    ````
+
+- Disable a rule using an .editorconfig
+
+    ````editorconfig
+    # Disable CA2200 globally
+    [*.cs]
+    dotnet_diagnostic.CA2200.severity = none
+
+    # Disable CA2200 for specific files
+    [tests/**/*.cs]
+    dotnet_diagnostic.CA2200.severity = none
+    ````
+
+> [!WARNING]
+> Remember that this should be a temporary solution to help adopting the package
+
+Finally, the warnings breaks the CI because they are treated as errors when building the `Release` configuration. You can disable this behavior by setting the following MSBuild property in the `.csproj` file or in the `Directory.Build.props` file
+
+    ````xml
+    <Project>
+        <PropertyGroup>
+            <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
+            <MSBuildTreatWarningsAsErrors>false</MSBuildTreatWarningsAsErrors>
+        </PropertyGroup>
+    </Project>
+    ````
 
 ## References