From bb56ccb420ff4a1a45721dde0a6c426518c44364 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tau=20G=C3=A4rtli?= <git@tau.garden>
Date: Sun, 2 Feb 2025 19:09:33 +0100
Subject: [PATCH] Add documentation

---
 Funcky.Analyzers/readme.md | 44 ++++++++++++++++++++++++++++++++++++++
 Funcky.sln                 |  3 +++
 2 files changed, 47 insertions(+)
 create mode 100644 Funcky.Analyzers/readme.md

diff --git a/Funcky.Analyzers/readme.md b/Funcky.Analyzers/readme.md
new file mode 100644
index 00000000..19ff8ad1
--- /dev/null
+++ b/Funcky.Analyzers/readme.md
@@ -0,0 +1,44 @@
+# Analyzers
+## Analyzers and Code Fixes In Separate Projects
+Analyzers and code fixes are split in two projects.
+
+This is to prevent us from accidentally referencing `Microsoft.CodeAnalysis.*.Workspaces`
+which is only available in the IDE, but not during `dotnet build`.
+
+## BuiltinAnalyzers
+These are analyzers that in our eyes are *mandatory* (disallow `TryGetValue`),
+so we package them directly in the Funcky package to ensure that every user is using them.
+
+## Roslyn Multi-Targeting
+In order to support newer C# features (which in turn requires an upgrade of the `Microsoft.CodeAnalysis.*` packages)
+we would break compatibility with older .NET SDK / Visual Studio Versions.
+
+To work around this, Roslyn supports shipping different analyzer assemblies
+in the NuGet package based on the Roslyn version i.e. ["multi-targeting" but for Roslyn][multi-targeting].
+
+The .NET SDK supports "multi-targeting" analyzers on the Roslyn version.
+This means that we ship multiple copies of the analyzer assembly in the following structure:
+
+```
+╰─ analyzers
+   ╰─ dotnet
+      ├─ cs
+      │  ├─ Funcky.Analyzers.dll
+      │  ╰─ ...
+      ╰─ roslyn4.12
+         ╰─ cs
+            ├─ Funcky.Analyzers.dll
+            ╰─ ...
+```
+
+## Roslyn Version Compatibility
+There are three documents that help figure out what version of Roslyn to target:
+* [.NET compiler platform package version reference](https://learn.microsoft.com/en-us/visualstudio/extensibility/roslyn-version-support): \
+  Maps Roslyn version to Visual Studio version
+* [.NET SDK, MSBuild, and Visual Studio versioning](https://learn.microsoft.com/en-gb/dotnet/core/porting/versioning-sdk-msbuild-vs): \
+  Maps .NET SDK version to Visual Studio version
+* [The history of C#](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-version-history): \
+  Lists C# versions and their release date which helps find the minimum Visual Studio version for a given C# version.
+
+
+[multi-targeting]: https://github.com/dotnet/sdk/issues/20355
diff --git a/Funcky.sln b/Funcky.sln
index 37fb4ae8..d21c379f 100644
--- a/Funcky.sln
+++ b/Funcky.sln
@@ -35,6 +35,9 @@ EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Funcky.Xunit.Test", "Funcky.Xunit.Test\Funcky.Xunit.Test.csproj", "{C2400B4E-63DD-475E-BF7B-5D5079601F51}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Analyzers", "Analyzers", "{BBE35279-7416-4B9D-B89D-B6D1FF369681}"
+	ProjectSection(SolutionItems) = preProject
+		Funcky.Analyzers\readme.md = Funcky.Analyzers\readme.md
+	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Funcky.Analyzers", "Funcky.Analyzers\Funcky.Analyzers\Funcky.Analyzers.csproj", "{38795B14-3E1A-4491-AEA0-173A73CE9E3A}"
 EndProject