Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
195 lines (152 loc) · 6.36 KB

CONTRIBUTING.md

File metadata and controls

195 lines (152 loc) · 6.36 KB
Raw

Contributing to Fugue

Thank you for your interest in contributing to Fugue! This document provides guidelines for contributing to the project.

Community

  • Discord: Join our Discord server
  • Issues & Bugs: Open an issue with the Bug Report template.
  • Feature Requests: Open an issue with the Feature Request template.
  • RFCs: Open an issue with the RFC template.
  • Zotero: Joing our Zotero group

Quick Start

git clone https://github.com/alexnodeland/fugue.git
cd fugue
cargo test --all-features

Development Setup

Prerequisites

  • Rust 1.70+ (install via rustup)
  • Git

Building and Testing

# Run all tests
make test

# Format code
make fmt

# Lint code  
make lint

# Run benchmarks
make bench

# Generate coverage report
make coverage

# Run all checks
make all

Or use cargo directly:

cargo test --all-features
cargo fmt
cargo clippy -- -D warnings

Contributing Guidelines

Issues

  • Use GitHub Issues for bug reports and feature requests
  • Provide clear reproduction steps for bugs
  • Include relevant code examples

Pull Requests

  • Fork the repository and create a short-lived feature branch from main (trunk-based development)
  • Rebase your branch to the top of main before submitting PR
  • Use semantic commit messages (e.g., feat:, fix:, docs:, refactor:)
  • Add tests for new functionality
  • Ensure all CI checks pass before requesting review
  • PRs are squash merged to maintain linear history
  • Update documentation as needed

Versioning

  • We follow Semantic Versioning (SemVer)
  • Breaking changes increment major version
  • New features increment minor version
  • Bug fixes increment patch version

Code Style

  • Follow Rust standard formatting (cargo fmt)
  • Address all clippy warnings (cargo clippy -- -D warnings)
  • Add documentation for public APIs
  • Include examples in documentation

Project Structure

graph LR
    A["🎻 Fugue<br/>Monadic Probabilistic Programming"] --> B["📦 Core Module"]
    A --> C["🔬 Inference Module"]
    A --> D["⚙️ Runtime Module"]
    A --> E["🎛️ Macros Module"]
    A --> F["⚠️ Error Module"]

    B --> B1["📍 Address System<br/>addr!(), scoped_addr!()"]
    B --> B2["📊 Distributions<br/>10 type-safe distributions"]
    B --> B3["🧩 Model<T><br/>Monadic composition"]
    B --> B4["🔢 Numerical<br/>Stable algorithms"]

    B2 --> B2A["bool: Bernoulli"]
    B2 --> B2B["u64: Poisson, Binomial"]
    B2 --> B2C["usize: Categorical"]
    B2 --> B2D["f64: Normal, Beta, Gamma, etc."]

    C --> C1["🔗 MCMC<br/>Adaptive Metropolis-Hastings"]
    C --> C2["🎯 SMC<br/>Particle filtering"]
    C --> C3["📈 VI<br/>Mean-field approximation"]
    C --> C4["🎲 ABC<br/>Likelihood-free inference"]
    C --> C5["📊 Diagnostics<br/>R-hat, ESS, validation"]

    D --> D1["🎭 Handler System<br/>Effect interpreters"]
    D --> D2["📝 Trace System<br/>Execution history"]
    D --> D3["💾 Memory Optimization<br/>Pooling & COW"]

    D1 --> D1A["PriorHandler"]
    D1 --> D1B["ReplayHandler"]
    D1 --> D1C["ScoreGivenTrace"]
    D1 --> D1D["Safe variants"]

    E --> E1["prob!<br/>Do-notation"]
    E --> E2["plate!<br/>Vectorization"]

    F --> F1["FugueError<br/>Rich error context"]

    G["📚 Documentation"] --> G1["User Guide<br/>20+ pages"]
    G --> G2["API Reference<br/>Complete rustdoc"]
    G --> G3["14 Examples<br/>Real-world scenarios"]

    H["🧪 Testing"] --> H1["82+ Unit Tests"]
    H --> H2["9+ Integration Tests"]
    H --> H3["158+ Doctests"]
    H --> H4["Property-based Tests"]

    I["⚡ Benchmarks"] --> I1["MCMC Performance<br/>Adaptation & diagnostics"]
    I --> I2["Memory Optimization<br/>Pooling & COW traces"]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#ffebee
    style G fill:#f1f8e9
    style H fill:#e3f2fd
    style I fill:#fff8e1
Loading

Directory Structure

fugue/
├── src/
│   ├── core/                   # Core probabilistic programming abstractions
│   │   ├── address.rs          # Hierarchical addressing system
│   │   ├── distribution.rs     # Type-safe distributions (10 built-in)
│   │   ├── model.rs            # Monadic Model<T> abstraction
│   │   └── numerical.rs        # Numerically stable algorithms
│   ├── inference/              # Inference algorithms
│   │   ├── mh.rs               # MCMC (Adaptive Metropolis-Hastings)
│   │   ├── smc.rs              # Sequential Monte Carlo
│   │   ├── vi.rs               # Variational Inference
│   │   ├── abc.rs              # Approximate Bayesian Computation
│   │   └── diagnostics.rs      # R-hat, ESS, validation
│   ├── runtime/                # Execution engine
│   │   ├── handler.rs          # Effect handler system
│   │   ├── interpreters.rs     # Built-in handlers
│   │   ├── trace.rs            # Execution history recording
│   │   └── memory.rs           # Memory optimization (pooling, COW)
│   ├── macros/                 # Ergonomic macros
│   │   └── mod.rs              # prob!, plate!, addr! macros
│   └── error.rs                # Comprehensive error handling
├── examples/                   # 14 complete examples
│   ├── bayesian_coin_flip.rs
│   ├── linear_regression.rs
│   ├── mixture_models.rs
│   ├── hierarchical_models.rs
│   └── ...
├── benches/                    # Performance benchmarks
│   ├── mcmc_benchmarks.rs      # MCMC adaptation & diagnostics
│   └── memory_benchmarks.rs    # Memory pooling & COW traces
├── tests/                      # Integration tests
├── docs/                       # User guide & documentation
│   ├── src/                    # mdBook source
│   └── api/                    # API documentation
└── target/                     # Build artifacts

Questions?

Open an issue or start a discussion on GitHub. We're happy to help!