Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (79 loc) · 2.97 KB

CONTRIBUTING.md

File metadata and controls

105 lines (79 loc) · 2.97 KB

Contributing to AnAspect.OneOf

Thank you for your interest in contributing! This is an experimental project exploring IL weaving for zero-cost abstractions in C#.

GitHub: https://github.com/Pouria7/AnAspect.OneOf

🧪 Experimental Status

This project is in early experimental stage. APIs and behavior may change significantly. We welcome:

  • Bug reports and issue discussions
  • Performance benchmarks and comparisons
  • Documentation improvements
  • Test case contributions

🚀 Getting Started

Prerequisites

  • .NET 8+ SDK
  • .NET 10+ SDK (for benchmarks)
  • Visual Studio 2022 or JetBrains Rider (optional, for IDE support)

Building

dotnet restore
dotnet build OneOf.sln -c Debug

Running Tests

dotnet test tests/OneOf.Tests/OneOf.Tests.csproj

Running Benchmarks

dotnet run --project tests/OneOf.Benchmarks/OneOf.Benchmarks.csproj -c Release -- --manual

📝 Pull Request Process

  1. Fork the repository
  2. Create a branch for your feature/fix
  3. Write tests for your changes
  4. Ensure all tests pass
  5. Update documentation if needed
  6. Submit a PR with a clear description

🎯 Areas for Contribution

High Priority

  • Support for OneOf<T1, T2, T3> and higher arities
  • TryGet method IL rewriting
  • Field/parameter/return type retargeting
  • More comprehensive test coverage
  • Performance benchmarks across different scenarios

Medium Priority

  • Custom serialization support (JSON, MessagePack, etc.)
  • Roslyn analyzers for best practices
  • Better debugger experience
  • Documentation and examples

Low Priority

  • LINQ expression tree support
  • Async state machine optimization
  • Native AOT compatibility testing

🐛 Reporting Issues

When reporting issues, please include:

  • .NET version
  • Operating system
  • Minimal reproducible example
  • Expected vs actual behavior
  • Whether Fody weaving ran (check for "ProcessedByFody" in assembly)

💡 Design Philosophy

This project follows these principles:

  1. Type safety at compile time - Full IntelliSense and compiler checks
  2. Zero cost at runtime - IL weaving eliminates abstractions
  3. Simplicity - Minimal API surface, clear transformations
  4. Transparency - Users should understand what the weaver does

📚 Understanding IL Weaving

Before contributing to the weaver, familiarize yourself with:

  • Mono.Cecil (IL manipulation library)
  • Fody (weaving framework)
  • .NET IL opcodes and stack behavior
  • C# compiler-generated code patterns

⚠️ Experimental Warnings

  • Breaking changes may occur between versions
  • Not recommended for production use yet
  • IL weaving can be fragile - test thoroughly
  • Debugger experience is suboptimal (shows object instead of OneOf)

📞 Communication

  • Open GitHub issues for bugs and feature requests
  • Discuss design decisions in issue comments before large PRs
  • Be respectful and constructive

Thank you for helping make OneOf.Fody better!