Contributing to RoslynRules

Thank you for your interest in contributing! This project welcomes bug reports, feature requests, documentation improvements, and code contributions.

Quick Start

Fork the repository on GitHub
Clone your fork locally
Build the solution: dotnet build
Run tests: dotnet test
Create a branch: git checkout -b feature/my-change
Commit with a descriptive message (see format below)
Push and open a Pull Request

Development Setup

Requirements

.NET 8.0 SDK or later
Visual Studio 2022, VS Code, or JetBrains Rider
PowerShell 7+ (for scripts in /scripts)

Build

dotnet build --configuration Release

Test

# All tests
dotnet test

# With diagnostics
dotnet test --logger "console;verbosity=detailed"

# Specific project
dotnet test RoslynRules.Tests

Benchmarks

dotnet run --project RoslynRules.Benchmarks --configuration Release

Project Structure

Directory	Contents
`RoslynRules/`	Core library
`RoslynRules.Json/`	JSON serialization
`RoslynRules.Tests/`	Unit and integration tests
`RoslynRules.Benchmarks/`	BenchmarkDotNet suite
`RoslynRules.Demo/`	Demo application
`RoslynRules.Demo.Tests/`	Demo integration tests
`docs/`	GitHub Pages documentation
`scripts/`	Local automation scripts (gitignored)

Commit Message Format

Use Conventional Commits:

<type>(<scope>): <short description>

[optional body]

[optional footer: Fixes #123]

Types: feat, fix, docs, test, perf, refactor, chore

Examples:

feat(compiler): add async delegate compilation
fix(execution): handle null parameters in RuleContext
docs(api): document RuleMetrics properties
test(aot): add trim compatibility tests

Code Style

Follow existing formatting (4-space indentation)
Add XML documentation for all public APIs
Keep methods focused and under 50 lines where possible
Use sealed for classes not designed for inheritance
Run dotnet format before committing

Testing Guidelines

Unit Tests

Name format: MethodName_Scenario_ExpectedResult
Use xUnit facts and theories
Assert with FluentAssertions where available

Integration Tests

Test real compilation and execution
Use TestCompiler.Instance to share ExpressionCompiler across tests
Clean up with compiler.Unload() where appropriate

AOT Tests

Mark AOT-requiring tests with [RequiresUnreferencedCode]
Place in RoslynRules.Tests/AotCompatibility/

Documentation

When adding or changing features:

Update XML docs in source code
Add/update markdown docs in docs/
Include Jekyll frontmatter for page navigation
Cross-link related pages
Update CHANGELOG.md

Pull Request Process

Ensure all tests pass locally
Update docs for any API changes
Add CHANGELOG entry
Keep PRs focused — one concern per PR
Respond to review feedback promptly

Reporting Issues

When reporting bugs, include:

.NET version (dotnet --version)
RoslynRules version
Minimal reproduction code
Expected vs actual behavior
Full exception stack trace (if applicable)

License

By contributing, you agree that your contributions will be licensed under the MIT License.