Merge pull request #36 from Chris-Wolfgang/copilot/update-readme-and-contributing-docs

Update documentation and configure build settings for Wolfgang.Extensions.IAsyncEnumerable

Author: Chris-Wolfgang

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to <Application Name>
+# Contributing to Wolfgang.Extensions.IAsyncEnumerable
 
-Thank you for your interest in contributing to **<Application Name>**! We welcome contributions to help improve this project.
+Thank you for your interest in contributing to **Wolfgang.Extensions.IAsyncEnumerable**! We welcome contributions to help improve this project.
 
 ## How Can You Contribute?
 
@@ -11,8 +11,9 @@ You can contribute in several ways:
 - Improving documentation
 - Writing or improving tests
 
-Please note: Before coding anything please check with me first by entering an issue and getting approval for it. PRs are more likely to get merged if I have agreed to the changes.
+**Please note:** Before coding anything please check with me first by entering an issue and getting approval for it. PRs are more likely to get merged if I have agreed to the changes.
 
+---
 
 ## Getting Started
 
@@ -36,27 +37,206 @@ Please note: Before coding anything please check with me first by entering an is
    - Building the project
    - Running automated tests
    - Checking code style and linting
+   - Running static analysis with 8 different analyzers
 
    **It is important to make sure that all CI steps pass before your PR can be merged.**
    - If any CI step fails, please review the error messages and update your PR as needed.
    - Maintainers will review your PR once all checks have passed.
 
+---
+
+## Code Quality Standards
+
+This project maintains **extremely high code quality standards** through multiple layers of static analysis and automated enforcement.
+
+### The 8 Analyzers
+
+All code is analyzed by these tools during build:
+
+1. **Microsoft.CodeAnalysis.NetAnalyzers** (Built-in .NET SDK)
+   - Correctness, performance, and security rules
+   - Latest analysis level enabled
+
+2. **StyleCop.Analyzers**
+   - Enforces consistent code style and formatting
+   - Documentation comment requirements
+
+3. **Roslynator.Analyzers**
+   - 500+ refactoring and code quality rules
+   - Advanced C# pattern detection
+
+4. **AsyncFixer**
+   - Detects async/await anti-patterns
+   - Ensures proper `ConfigureAwait()` usage
+   - Prevents fire-and-forget async calls
+
+5. **Microsoft.VisualStudio.Threading.Analyzers**
+   - Thread safety enforcement
+   - Async method naming conventions
+   - Deadlock prevention
+
+6. **Microsoft.CodeAnalysis.BannedApiAnalyzers**
+   - Blocks usage of APIs listed in `BannedSymbols.txt`
+   - Enforces async-first patterns (see below)
+
+7. **Meziantou.Analyzer**
+   - Comprehensive code quality checks
+   - Performance optimizations
+   - Best practice enforcement
+
+8. **SonarAnalyzer.CSharp**
+   - Industry-standard code analysis
+   - Security vulnerability detection
+   - Code smell identification
+
+### Async-First Enforcement
+
+This library **prohibits synchronous blocking calls** via `BannedSymbols.txt`. The following APIs are **banned**:
+
+#### ❌ Blocking Async Operations
+```csharp
+// Banned - blocks threads
+task.Wait();
+task.Result;
+Task.WaitAll(tasks);
+
+// Required - truly async
+await task;
+await Task.WhenAll(tasks);
+```
+
+#### ❌ Synchronous I/O
+```csharp
+// Banned
+File.ReadAllText(path);
+stream.Read(buffer, 0, count);
+streamReader.ReadLine();
+
+// Required
+await File.ReadAllTextAsync(path);
+await stream.ReadAsync(buffer, 0, count);
+await streamReader.ReadLineAsync();
+```
+
+#### ❌ Thread Blocking
+```csharp
+// Banned
+Thread.Sleep(1000);
+Console.ReadLine();
+
+// Required
+await Task.Delay(1000);
+// Avoid blocking console reads in async code
+```
+
+#### ❌ Obsolete/Insecure APIs
+```csharp
+// Banned
+var client = new WebClient();
+var formatter = new BinaryFormatter();
+var now = DateTime.Now; // Use DateTimeOffset
+
+// Required
+var client = new HttpClient();
+// Use System.Text.Json.JsonSerializer
+var now = DateTimeOffset.UtcNow;
+```
+
+**Why?** This ensures all code is **truly asynchronous** and **non-blocking**, providing optimal performance in async contexts.
+
+---
+
+## Build and Test Instructions
+
+### Prerequisites
+- .NET 8.0 SDK or later
+- PowerShell Core (optional, for formatting scripts)
+
+### Build the Project
+
+```bash
+# Restore NuGet packages
+dotnet restore
+
+# Build in Release configuration (enforces all analyzers)
+dotnet build --configuration Release
+```
+
+**Note:** Release builds treat all analyzer warnings as errors (`<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`). Debug builds allow warnings to facilitate development.
+
+### Run Tests
+
+```bash
+# Run all unit tests
+dotnet test --configuration Release
+
+# Run with coverage (if configured)
+dotnet test --collect:"XPlat Code Coverage"
+```
+
+### Code Formatting
+
+This project uses `.editorconfig` for consistent code style:
+
+```bash
+# Format all code
+dotnet format
+
+# Check formatting without changes (CI mode)
+dotnet format --verify-no-changes
+
+# PowerShell formatting script
+pwsh ./format.ps1
+```
+
+See [README-FORMATTING.md](README-FORMATTING.md) for detailed formatting rules.
+
+---
+
+## .editorconfig Rules
+
+Key style rules enforced:
+
+- **Indentation:** 4 spaces (C#), 2 spaces (XML/JSON)
+- **Line endings:** LF (Unix-style)
+- **Charset:** UTF-8
+- **Trim trailing whitespace:** Yes
+- **Final newline:** Yes
+- **Braces:** New line style (Allman)
+- **Naming:** PascalCase for public members, camelCase for parameters/locals
+- **File-scoped namespaces:** Required in C# 10+
+- **`var` preferences:** Use for built-in types and when type is obvious
+- **Null checks:** Prefer pattern matching (`is null`, `is not null`)
+
+View the complete configuration in [.editorconfig](.editorconfig).
+
+---
+
 ## Guidelines
 
 - Follow the coding style used in the project.
 - Write clear, concise commit messages.
 - Add relevant tests for new features or bug fixes.
-- Document any public APIs or significant changes.
+- Document any public APIs with XML documentation comments.
+- Ensure all analyzer warnings are addressed (they're treated as errors in Release builds).
+- Use async/await patterns - no blocking calls allowed.
+- Include `CancellationToken` parameters in async methods where appropriate.
+
+---
 
 ## Pull Requests
 
-- Ensure your pull request passes all tests.
+- Ensure your pull request passes all tests and analyzer checks.
 - Respond to review feedback in a timely manner.
 - Reference related issues in your pull request description.
+- Keep changes focused and atomic - one feature/fix per PR.
+- Update documentation if you change public APIs.
+
+---
 
 ## Code of Conduct
 
-Please be respectful and considerate in all interactions. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) if available.
+Please be respectful and considerate in all interactions. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our community guidelines.
 
 ---