Improve README.md and add it to the NuGet package too.

CodeStyle/CodeStyle.csproj

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project Sdk="Microsoft.Build.NoTargets">
     <PropertyGroup>
-        <Version>1.2.1</Version>
+        <Version>1.2.2</Version>
         <PackageId>Polyadic.CodeStyle</PackageId>
         <PackageTags>analyzers</PackageTags>
         <Description>Various analyzers bundled with opinionated configuration</Description>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+        <RepositoryUrl>https://github.com/polyadic/code-style</RepositoryUrl>
+        <RepositoryType>git</RepositoryType>
         <NoWarn>$(NoWarn);NU5104;NU5128</NoWarn>
         <!-- NU5104: A stable release of a package should not have a prerelease dependency.
                      See https://docs.microsoft.com/en-us/nuget/reference/errors-and-warnings/nu5104 -->
@@ -21,5 +24,6 @@
     <ItemGroup>
         <None Include="build\**\*" Pack="true" PackagePath="%(Identity)" />
         <None Include="buildMultiTargeting\**\*" Pack="true" PackagePath="%(Identity)" />
+        <None Include="..\README.md" Pack="true" PackagePath="\" />
     </ItemGroup>
 </Project>

README.md

@@ -1,42 +1,115 @@
 # Polyadic Code Style
 
 [![NuGet Version](https://img.shields.io/nuget/v/Polyadic.CodeStyle)](https://www.nuget.org/packages/Polyadic.CodeStyle)
-[![Licence: MIT](https://img.shields.io/badge/licence-MIT-green)](https://raw.githubusercontent.com/polyadic/funcky/main/LICENSE-MIT)
-[![Licence: Apache](https://img.shields.io/badge/licence-Apache-green)](https://raw.githubusercontent.com/polyadic/funcky/main/LICENSE-Apache)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-green)](https://github.com/polyadic/code-style/blob/main/LICENSE-MIT)
+[![Licence: Apache](https://img.shields.io/badge/licence-Apache-green)](https://github.com/polyadic/code-style/blob/main/LICENSE-Apache)
 
+Shared, opinionated code style for all [Polyadic](https://github.com/polyadic) projects, including
+[Funcky](https://github.com/polyadic/funcky). Add one package reference and your project gets the same
+analyzers and the same rule configuration as every other Polyadic project.
 
-Shared Code Style for all Polyadic/Funcky projects.
+## What's included
+
+The package pulls in these analyzers as transitive dependencies and configures them:
+
+| Analyzer | Purpose |
+|---|---|
+| [StyleCop.Analyzers](https://github.com/DotNetAnalyzers/StyleCopAnalyzers) | Formatting, naming, ordering, documentation and readability rules |
+| [IDisposableAnalyzers](https://github.com/DotNetAnalyzers/IDisposableAnalyzers) | Detects leaked, double-disposed or un-owned `IDisposable` instances |
+
+On top of that, the package applies the following settings to every project that references it:
+
+* A **rule set** (`Default.ruleset`) that turns most StyleCop and all IDisposable rules into **errors**
+  and disables the ones Polyadic deliberately does not follow.
+* A **`stylecop.json`** that places `using` directives outside the namespace.
+* A **global `.editorconfig`** that enforces file-scoped namespaces and flags unnecessary `using` directives.
+* `EnforceCodeStyleInBuild=true`, so `IDE*` rules are checked during the build and not only in the IDE.
+* `GenerateDocumentationFile=true`, so analyzers can inspect XML documentation comments (required by `SA0001`).
+  Missing documentation itself (`CS1591`) is not reported.
+* `nullable` warnings are promoted to errors in C# projects.
+* A guard that fails `dotnet pack` for locally built packages so that only CI-built packages reach nuget.org
+  (see [Packing](#packing)).
 
 ## Usage
 
+Add the package to every project that should follow the code style:
+
 ```xml
-<PackageReference Include="Polyadic.CodeStyle" Version="..." />
+<PackageReference Include="Polyadic.CodeStyle" Version="..." PrivateAssets="all" />
+```
+
+To apply it to a whole repository at once, put the reference into a `Directory.Build.props`
+(or `Directory.Packages.props` when using central package management) at the repository root instead:
+
+```xml
+<Project>
+  <ItemGroup>
+    <PackageReference Include="Polyadic.CodeStyle" Version="..." PrivateAssets="all" />
+  </ItemGroup>
+</Project>
+```
+
+`PrivateAssets="all"` keeps the analyzers out of the dependency list of your own package.
+
+The rules are configured with the expectation that CI builds with warnings treated as errors:
+
+```sh
+dotnet build /p:TreatWarningsAsErrors=true
 ```
 
-The rules are configured with the expectation that you build with
-`/p:TreatWarningsAsErrors=true` on CI.
+### Overriding rules
+
+Every rule can be adjusted per repository or per project with an `.editorconfig` entry, which takes
+precedence over the packaged rule set:
+
+```ini
+[*.cs]
+dotnet_diagnostic.SA1600.severity = none   # Elements should be documented
+```
+
+For one-off cases, prefer a `#pragma warning disable` or a `[SuppressMessage]` with a justification.
+
+### Packing
+
+`dotnet pack` fails on developer machines with the message
+*"Do not publish locally built packages to NuGet.org"*. This is intentional: release packages should be
+built by CI, where `ContinuousIntegrationBuild` is set. To pack locally anyway, for example to test a
+package, run:
+
+```sh
+dotnet pack /p:ContinuousIntegrationBuild=true
+```
+
+The guard is skipped for non-packable projects and while generating an API compatibility suppression file
+(`ApiCompatGenerateSuppressionFile=true`).
 
 ## Releasing
-1. Bump `<Version>` in `CodeStyle/CodeStyle.csproj` and add a changelog entry.
+
+1. Bump `<Version>` in `CodeStyle/CodeStyle.csproj` and add an entry to
+   [`changelog.md`](https://github.com/polyadic/code-style/blob/main/changelog.md).
 2. Merge to `main`, then create and push a tag matching the version (e.g. `1.2.0`).
-3. The [Publish Release Packages](.github/workflows/publish-release.yml) workflow packs
-   and pushes the package to nuget.org via trusted publishing.
+3. The [Publish Release Packages](https://github.com/polyadic/code-style/blob/main/.github/workflows/publish-release.yml)
+   workflow verifies that the tag matches the version, packs the package and pushes it to nuget.org via
+   trusted publishing. No API key is stored in the repository.
 
 ## Credits
+
 The `Polyadic.CodeStyle` package started as a direct copy of
 [`Messerli.CodeStyle`](https://github.com/messerli-informatik-ag/code-style), licensed under either Apache 2.0 or MIT.
 
 ## License
+
 Licensed under either of
 
 * Apache License, Version 2.0
-  ([LICENSE-Apache](LICENSE-Apache) or <http://www.apache.org/licenses/LICENSE-2.0>)
+  ([LICENSE-Apache](https://github.com/polyadic/code-style/blob/main/LICENSE-Apache) or <http://www.apache.org/licenses/LICENSE-2.0>)
 * MIT license
-  ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+  ([LICENSE-MIT](https://github.com/polyadic/code-style/blob/main/LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
 
 at your option.
 
 ## Contribution
+
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.