Update README

Author: neoscie

CHANGELOG.md

@@ -7,6 +7,11 @@ and adheres to a project-specific [Versioning](/README.md).
 
 ## [Unreleased]
 
+### Fixed
+
+- Improved README by describing the purpose, usage, and versioning of the package.
+- Adds repository and icon information to the test ruleset NuGet package.
+
 ### Changed
 
 - Updated SonarAnalyzer.CSharp to version 9.32.0.97167

Neolution.CodeAnalysis.TestsRuleset.nuspec

@@ -7,6 +7,9 @@
     <authors>Neolution AG</authors>
     <description>Configures Code Analysis for Neolution Test Projects.</description>
     <projectUrl>https://github.com/neolution-ch/Neolution.CodeAnalysis</projectUrl>
+    <repository type="git" url="https://github.com/neolution-ch/Neolution.CodeAnalysis" />
+    <icon>icon.png</icon>
+    <tags>code analysis;roslyn;stylecop;sonar;ruleset</tags>
     <readme>docs\README.md</readme>
     <license type="expression">MIT</license>
     <requireLicenseAcceptance>false</requireLicenseAcceptance>

README.md

@@ -1,26 +1,74 @@
-# Neolution Code Analysis rulesets
-We maintain two (opinionated) rulesets for all our projects and distribute them, including 3rd-party Roslyn Analyzers (StyleCop and SonarSource) in two respective NuGet packages.
+# Neolution Code Analysis Rulesets
 
-- For Libraries, Tools, Web, UI and other projects
-  - [Neolution.CodeAnalysis](https://www.nuget.org/packages/Neolution.CodeAnalysis/)
-- For projects containing automated tests (less strict rules)
-  - [Neolution.CodeAnalysis.TestsRuleset](https://www.nuget.org/packages/Neolution.CodeAnalysis.TestsRuleset/)
+[![NuGet](https://img.shields.io/nuget/v/Neolution.CodeAnalysis.svg)](https://www.nuget.org/packages/Neolution.CodeAnalysis/)
+[![NuGet](https://img.shields.io/nuget/v/Neolution.CodeAnalysis.TestsRuleset.svg)](https://www.nuget.org/packages/Neolution.CodeAnalysis.TestsRuleset/)
 
-## Decisions and opinions
-The base ruleset consists of the default ruleset of the Roslyn Analyzers we include in the NuGet package and those used in our build tools.
+**Neolution.CodeAnalysis** provides a plug-and-play code analysis standard for .NET projects. By adding this package, you instantly enforce consistent, high-quality code with minimal setup—no need to maintain your own ruleset or configuration. The package includes:
 
-- We include our own opinionated ruleset with adjusted Analyzer severities as a [Global AnalyzerConfig](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files#global-analyzerconfig)
-- In all build configurations other that `Debug`, warnings will be converted to errors.
-- We include our own [stylecop.json](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/Configuration.md) configuration file.
+- Pre-configured Roslyn analyzers (StyleCop, SonarSource)
+- Strict and up-to-date rules for code quality and security
+- Automatic conversion of warnings to errors (except in Debug)
+- A single source of truth for code style and best practices
+- Easy updates: just bump the package version to get the latest rules
+
+**Why use this package?**
+
+- Save time on code reviews by catching issues early
+- Ensure all projects follow the same standards
+- Reduce technical debt and improve maintainability
+- Onboard new developers faster with clear, enforced guidelines
+- **Flexible:** You can override any rules or severities in your own `.editorconfig` files at the project or solution level to fit your team's needs.
+
+## Packages
+
+- **[Neolution.CodeAnalysis](https://www.nuget.org/packages/Neolution.CodeAnalysis/):** For libraries, tools, web, UI, and other projects.
+- **[Neolution.CodeAnalysis.TestsRuleset](https://www.nuget.org/packages/Neolution.CodeAnalysis.TestsRuleset/):** For test projects (less strict rules).
+
+## Installation
+
+Install via NuGet Package Manager:
+
+```shell
+Install-Package Neolution.CodeAnalysis
+```
+
+or for test projects:
+
+```shell
+Install-Package Neolution.CodeAnalysis.TestsRuleset
+```
+
+Or add the following to your `.csproj`:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Neolution.CodeAnalysis" Version="*">
+    <PrivateAssets>all</PrivateAssets>
+    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+  </PackageReference>
+</ItemGroup>
+```
 
 ## Versioning
-Given a version number `MAJOR.MINOR.PATCH`, an incremented number for:
 
-- `MAJOR` version means there are incompatible changes with the previous version,
-- `MINOR` version means functionality and rules were added, and
-- `PATCH` version means that the changes are all completely backwards compatible. Usually when rules were lowered in severity or disabled/removed.
+- **MAJOR**: Incompatible changes, may require significant refactoring
+- **MINOR**: New rules or rule changes, may break the build
+- **PATCH**: Safe to update, only disables or lowers severity of rules
+
+See [CHANGELOG.md](./CHANGELOG.md) for details.
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome! Please open an issue or pull request on [GitHub](https://github.com/neolution-ch/Neolution.CodeAnalysis).
+
+> **Note:** The ruleset is intentionally opinionated and curated by Neolution to reflect our collective experience and values. While we welcome feedback and suggestions, changes to the rules themselves are carefully considered to maintain consistency across projects. If your requirements differ significantly, you are welcome to fork the package and adapt it to your needs.
+
+## Links
 
-### What it means in practice:
-- You can (and should) always update the package to the latest `PATCH` version whenever you have the chance to do it, it should never break the build. 
-- Updating to the latest `MINOR` version can break the build and may require minor refactorings. But you can expect to have Roslyn code fixes and/or documentation available for the changes that are needed to fix the build.
--  `MAJOR` updates will break your build and may require major refactorings.
+- [Source on GitHub](https://github.com/neolution-ch/Neolution.CodeAnalysis)
+- [NuGet: Neolution.CodeAnalysis](https://www.nuget.org/packages/Neolution.CodeAnalysis/)
+- [NuGet: Neolution.CodeAnalysis.TestsRuleset](https://www.nuget.org/packages/Neolution.CodeAnalysis.TestsRuleset/)

build/Neolution.CodeAnalysis.globalconfig

@@ -276,7 +276,7 @@ dotnet_diagnostic.S6931.severity = none
 
 # S6678: Use PascalCase for named placeholders
 ; Team decided that enforcing this rule is not worth the effort
-dotnet_diagnostic.S6678.severity = none
+dotnet_diagnostic.S6678.severity = suggestion
 
 # S6964: Value type property used as input in a controller action should be nullable, required or annotated with the JsonRequiredAttribute to avoid under-posting
 ; This is handled by a custom model binder in our project templates that produces a bad request response in case of under-posting