CONTRIBUTING.md

Contributing to Wolfgang.Etl.Abstractions

Thank you for your interest in contributing to Wolfgang.Etl.Abstractions! We welcome contributions to help improve this project.

How Can You Contribute?

You can contribute in several ways:

• Reporting bugs
• Suggesting enhancements
• Submitting pull requests for new features or bug fixes
• 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.

---

Getting Started

1. Fork the repository and clone it locally.

2. Create a new branch for your feature or bug fix:

   git checkout -b your-feature-name

3. Make your changes and commit them with clear messages:

   git commit -m "Describe your changes"

4. Push your branch to your fork:

   git push origin your-feature-name

5. Open a pull request describing your changes.

6. PR Checks:
   Once you create a pull request (PR), several Continuous Integration (CI) steps will run automatically. These may include:

   • Building the project
   • Running automated tests
   • Checking code style and linting
   • Running static analysis with multiple static analyzers (see list below)

   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 7 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. Roslynator.Analyzers

   • 500+ refactoring and code quality rules
   • Advanced C# pattern detection

3. AsyncFixer

   • Detects async/await anti-patterns
   • Ensures proper ConfigureAwait() usage
   • Prevents fire-and-forget async calls

4. Microsoft.VisualStudio.Threading.Analyzers

   • Thread safety enforcement
   • Async method naming conventions
   • Deadlock prevention

5. Microsoft.CodeAnalysis.BannedApiAnalyzers

   • Blocks usage of APIs listed in BannedSymbols.txt
   • Enforces async-first patterns (see below)

6. Meziantou.Analyzer

   • Comprehensive code quality checks
   • Performance optimizations
   • Best practice enforcement

7. 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

// Banned - blocks threads
task.Wait();
task.Result;
Task.WaitAll(tasks);

// Required - truly async
await task;
await Task.WhenAll(tasks);

❌ Synchronous I/O

// 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

// Banned
Thread.Sleep(1000);
Console.ReadLine();

// Required
await Task.Delay(1000);
// Avoid blocking console reads in async code

❌ Obsolete/Insecure APIs

// 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

# 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

# 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:

# Format all code
dotnet format

# Check formatting without changes (CI mode)
dotnet format --verify-no-changes

# PowerShell formatting script
pwsh ./scripts/format.ps1

See 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.

---

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 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 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 for our community guidelines.

---

Thank you for contributing! 🎉