Add documentation on installing and configuring analyzers

Closes #1095

doc/analyzers/editorconfigs/AppWithMainThread.editorconfig

@@ -0,0 +1,4 @@
+# This file applies to applications with a main thread, and libraries that may run in them.
+
+# This file is intentionally empty because the default severity levels for the threading analyzers
+# are optimized for these types of projects.

doc/analyzers/editorconfigs/AppWithoutMainThread.editorconfig

@@ -0,0 +1,8 @@
+# These settings are appropriate for most projects that *never* run inside a process with a main thread and `SynchronizationContext`.
+# Examples of such applications are ASP.NET Core and console applications.
+
+# VSTHRD012: Provide JoinableTaskFactory where allowed
+dotnet_diagnostic.VSTHRD012.severity = none
+
+# VSTHRD003: Avoid awaiting foreign Tasks
+dotnet_diagnostic.VSTHRD003.severity = none

doc/analyzers/editorconfigs/JTFFocusedLibrary.editorconfig

@@ -0,0 +1,4 @@
+# These settings are appropriate for libraries that always run within a process that follows the JoinableTaskFactory rules.
+
+# VSTHRD111: Use .ConfigureAwait(bool)
+dotnet_diagnostic.VSTHRD111.severity = silent

doc/analyzers/editorconfigs/README.md

@@ -0,0 +1,53 @@
+# About these .editorconfig files
+
+This folder contains sample .editorconfig files applicable to various project types.
+
+Choose the most applicable .editorconfig file based on your project type and its filename and the introductory comments that may be included as a header in each file.
+Append the contents of that file to your own `.editorconfig` file in your repo.
+
+## Use of `warning` severity levels
+
+When the analyzers use the `warning` severity level by default, or when the `.editorconfig` files in this folder set them, it is with the expectation that compilation warnings cause build breaks in PR/CI builds.
+Using `warning` allows for a faster inner dev-loop because certain threading violations are permissible while drafting code changes, but _should_ be fixed before code is merged into the main branch.
+
+You can configure your CI/PR build to fail on compilation warnings by setting the `MSBuildTreatWarningsAsErrors` environment or pipeline variable to `true`.
+
+If your repo does _not_ have builds configured to fail on compilation warnings, consider elevating all the warning severites to error severities to ensure these serious issues do not get ignored.
+
+## More about specific project types
+
+While several project types have specific .editorconfig files defined in this folder, some merit some additional explanation and guidance.
+
+### Broadly shared libraries (non-Visual Studio specific)
+
+[SharedLibrary.editorconfig](SharedLibrary.editorconfig)
+
+Libraries that may run in any process, whether they have a main thread or not, should code themselves defensively to avoid any dependency on the main thread so that applications that do not follow `JoinableTaskFactory` rules can avoid deadlocks even when synchronously blocking their main thread using `Task.Wait()` on code running inside your library.
+In particular, shared libraries of general interest should _always_ use `.ConfigureAwait(false)` when awaiting on tasks.
+
+[Learn more about authoring libraries following best threading practices](../library_with_jtf.md).
+
+### Libraries that run inside a JoinableTaskFactory-compliant application
+
+[JTFFocusedLibrary.editorconfig](JTFFocusedLibrary.editorconfig)
+
+These are libraries that always run within a process that follows the JoinableTaskFactory rules, such as the Visual Studio process.
+Because these processes _may_ block the main thread using `JoinableTaskFactor.Run` or similar APIs, the most efficient thing for a library to do is _not_ use `.ConfigureAwait(false)` everywhere so that its continuations may resume on the thread that is already blocking on its completion.
+
+### GUI applications and libraries specific to them
+
+[AppWithMainThread.editorconfig](AppWithMainThread.editorconfig)
+
+This essentially captures all projects that are designed specifically to run inside an application that uses a `SynchronizationContext` on its main thread to keep code on the main thread, such as WinForms, WPF, Maui and Avalonia.
+
+These projects are strongly encouraged to include the `Microsoft.VisualStudio.Threading` NuGet package as a dependency and the analyzer modifications below are consistent with that recommendation.
+
+### ASP.NET Core and console applications
+
+[AppWithoutMainThread.editorconfig](AppWithoutMainThread.editorconfig)
+
+### Test projects
+
+[Tests.editorconfig](Tests.editorconfig)
+
+Test projects have a high tendency to define async test methods that are only called by reflection, and the `Async` method name suffix is usually unwelcome there.

doc/analyzers/editorconfigs/SharedLibrary.editorconfig

@@ -0,0 +1,2 @@
+# VSTHRD111: Use .ConfigureAwait(bool)
+dotnet_diagnostic.VSTHRD111.severity = warning

doc/analyzers/editorconfigs/Tests.editorconfig

@@ -0,0 +1,4 @@
+# These settings are appropriate for test projects.
+
+# VSTHRD200: Use `Async` naming convention
+dotnet_diagnostic.VSTHRD200.severity = none

doc/analyzers/index.md

@@ -2,6 +2,7 @@
 
 The following are the diagnostic analyzers installed with the [Microsoft.VisualStudio.Threading.Analyzers][1]
 NuGet package.
+Learn more about [how to install and configure these analyzers](installation.md).
 
 ID | Title | Severity | Supports | Default diagnostic severity
 ---- | --- | --- | --- | --- |

doc/analyzers/installation.md

@@ -0,0 +1,68 @@
+# Installing the threading analyzers
+
+The threading analyzers built from this repo and consumable via [the Microsoft.VisualStudio.Threading.Analyzers nuget package][NuGet] are useful for virtually every app library and most libraries.
+In particular, projects do not need to be related to Visual Studio in order for these analyzers to apply and improve the quality of your code.
+
+This document outlines how to install the analyzers and offer guidance on how to optimally configure them.
+
+## How to install the threading analyzers
+
+If you are using the `Microsoft.VisualStudio.Threading` NuGet package, you should already have the analyzers installed because they are brought in as a dependency of this package.
+
+Some projects may not want a runtime dependency on `Microsoft.VisualStudio.Threading`, but the analyzers may still apply.
+Install the analyzers using any of the methods described on [the package landing page on nuget.org][NuGet].
+For example, you might add this tag to your project file:
+
+```xml
+<PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.5.22" PrivateAssets="all" />
+```
+
+Or even better, add this to some broad `Directory.Build.targets` file so it can apply to all of your projects.
+
+Remember to periodically update the version of the analyzer package you reference.
+You should generally use the latest version available, without regard to the version of the application or threading library in use, so you get the best diagnostics.
+
+## Configuring the analyzers
+
+There are [many rules](index.md) in the analyzer package.
+The default severity levels for the various rules are not appropriate for every type of project.
+To get the best default severity levels for your project type, please review [these editorconfig recommendations](editorconfigs/README.md) and apply them to your project.
+
+Some analyzers allow for [specialized configuration](configuration.md) that allows you to tailor them to your specific application or library to provide even more value to your team.
+
+## Dealing with suppressions
+
+In some projects we find that some of the threading analyzers have been disabled because they were producing warnings that the project owner did not want to fix at the time.
+We generally discourage disabling rules that apply to a project because of the deadlocks that may already exist or that can creep into a codebase over time.
+If installing analyzers produces blocking errors or warnings and you cannot fix them all at once, suppress the warnings and schedule time to go back to review them soon.
+The recommended way to suppress your "baseline" of warnings is with in-situ `#pragma` suppressions such as:
+
+```css
+#pragma warning disable VSTHRD010 // Suppress warning in baseline when installing analyzers -- should review soon
+bad.Code();
+#pragma warning restore VSTHRD010
+```
+
+Suppressing specific occurrences in this way can be done in bulk using an automated C# code fix within Visual Studio.
+Doing it for each individual occurrence is better than suppressing the entire rule ID because the analyzers will be allowed to flag newly introduced code while you have not yet reviewed your old code and re-enabled the rule.
+
+If you suspect your project may have suppressed an analyzer rule project-wide, please look in the following common places for broad suppressions and remove them so that your project gets the analyzers run on them:
+
+1. MSBuild project file `<NoWarn>` properties that contain `VSTHRD*` warning IDs.
+1. MSBuild project files with `<PackageReference>` to the analyzer package but set `ExcludeAssets="analyzers"`, `ExcludeAssets="all"` or `IncludeAssets="none"` to explicitly turn them off.
+1. .ruleset files that decrease severity or turn off `VSTHRD*` rule IDs.
+1. .editorconfig files that decrease severity or turn off `VSTHRD*` rule IDs.
+
+## Visual Studio specific analyzers
+
+When a project targets Visual Studio specifically, it should also reference the [Microsoft.VisualStudio.Sdk.Analyzers][SdkAnalyzers] NuGet package.
+This package delivers additional analyzers and configures _these_ threading analyzers to be more aware of VS-specific APIs so that better diagnostics can be produced.
+
+```xml
+<PackageReference Include="Microsoft.VisualStudio.Sdk.Analyzers" Version="16.10.10" PrivateAssets="all" />
+```
+
+Note that although the SDK analyzers automatically brings in the threading analyzers due to a package dependency, you should reference the threading analyzers directly as well to bring in the latest version, since the SDK analyzers ships infrequently and thus brings in older versions of the threading analyzers by default.
+
+[NuGet]: https://www.nuget.org/packages/microsoft.visualstudio.threading.analyzers
+[SdkAnalyzers]: https://www.nuget.org/packages/microsoft.visualstudio.sdk.analyzers