Skip to content

EXPERIMENTAL-WARNING.md

Latest commit

 

History

History
105 lines (77 loc) · 3 KB

EXPERIMENTAL-WARNING.md

File metadata and controls

105 lines (77 loc) · 3 KB

⚠️ EXPERIMENTAL PROJECT WARNING

This is an Experimental Alpha Release

AnAspect.OneOf is currently in early experimental stage (v0.1.0-alpha). This means:

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

⚠️ Use at Your Own Risk

  • NOT recommended for production use
  • Breaking changes will occur between versions
  • APIs may change significantly
  • Bugs and edge cases are expected

What "Experimental" Means

  1. Feature Incomplete

    • Only OneOf<T1, T2> supported (no higher arities)
    • Some methods not optimized (TryGet)
    • Limited transformation scope (locals only, not fields/parameters)

  2. Testing Limited

    • Basic functionality tested
    • Edge cases may not be covered
    • Performance characteristics may vary across scenarios

  3. Debugging Experience

    • Debugger shows object instead of OneOf<T1, T2> after weaving
    • Stack traces may be confusing
    • IL inspection required to verify transformations

  4. IL Weaving Risks

    • IL manipulation is inherently fragile
    • Can break with C# compiler changes
    • May interact poorly with other IL weavers
    • Native AOT compatibility unknown

When to Use

✅ Good for:

  • Experimentation and learning
  • Proof-of-concept projects
  • Performance research
  • Contributing to development

❌ Not ready for:

  • Production applications
  • Mission-critical systems
  • Shipped libraries
  • Long-term maintenance

Known Limitations

  1. Functional

    • Only 2-type OneOf supported
    • TryGet methods not weaved
    • No custom serialization
    • No analyzer support

  2. Technical

    • Debugger experience suboptimal
    • No official support
    • Documentation incomplete
    • Breaking changes expected

  3. Ecosystem

    • Not compatible with all other Fody weavers
    • May conflict with reflection-heavy libraries
    • Serialization requires custom handling

Stability Roadmap

We aim to reach these milestones before production-ready:

  • v0.2.0-alpha: Add OneOf<T1, T2, T3, T4> support
  • v0.3.0-alpha: Implement TryGet weaving
  • v0.4.0-beta: Field/parameter/return type retargeting
  • v0.5.0-beta: Comprehensive test coverage
  • v0.6.0-rc: Roslyn analyzers
  • v1.0.0: First stable release (API stable, production-ready)

Reporting Issues

If you encounter issues:

  1. Check if it's a known limitation (see above)
  2. Verify Fody ran (check for "ProcessedByFody" attribute)
  3. Inspect IL using ILSpy/dotPeek
  4. Open GitHub issue with minimal repro

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Alternatives

If you need production-ready discriminated unions, consider:

  • OneOf - Mature, stable
  • LanguageExt - Functional programming library
  • Plain inheritance/interfaces - Traditional OOP approach

By using this library, you acknowledge that it is experimental and accept the risks outlined above.

Last updated: 2024-XX-XX | Version: 0.1.0-alpha