Contributing to Sigil

Thank you for your interest in contributing to Sigil! This guide will help you get started.

Sigil is an open-source project, and we welcome contributions of all kinds: code, documentation, bug reports, feature requests, and community support.

Development Setup

Prerequisites

• Rust 1.75 or later
• LLVM 17 (for AOT compilation backend)
• Git

Clone and Build

# Clone the repository
git clone https://github.com/Daemoniorum-LLC/sigil-lang.git
cd sigil-lang

# Build the compiler
cd parser
cargo build --release

# Run tests
cargo test

# Run the interpreter
cargo run -- run ../examples/hello.sigil

Running with Different Backends

# Interpreter (default)
sigil run file.sigil

# Cranelift JIT
sigil jit file.sigil

# LLVM AOT (requires LLVM)
sigil compile file.sigil -o output
./output

Project Structure

sigil-lang/
├── parser/              # Main compiler crate
│   ├── src/
│   │   ├── lexer/       # Tokenizer
│   │   ├── parser/      # AST generation
│   │   ├── types/       # Type checker
│   │   ├── codegen/     # Code generation
│   │   │   ├── cranelift/   # JIT backend
│   │   │   └── llvm/        # AOT backend
│   │   ├── interpreter/ # Tree-walking interpreter
│   │   └── stdlib/      # Standard library
│   └── tests/           # Integration tests
├── examples/            # Example programs
├── docs/                # Documentation
└── website/             # sigil-lang.com source

Code Contributions

Areas for Contribution

Contribution Workflow

1. Fork the repository on GitHub
2. Create a branch for your feature: git checkout -b feature/my-feature
3. Make your changes with tests
4. Run tests: cargo test
5. Commit with a descriptive message
6. Push to your fork
7. Open a Pull Request

Documentation

Documentation contributions are highly valued. You can help by:

• Fixing typos and improving clarity
• Adding examples and tutorials
• Documenting undocumented features
• Translating documentation

Documentation lives in the docs/ directory and the website/ directory for sigil-lang.com.

Reporting Issues

When reporting issues, please include:

• Sigil version (sigil --version)
• Operating system and version
• Steps to reproduce
• Expected vs actual behavior
• Minimal code example if applicable

## Bug Report Template

**Version:** 0.2.0
**OS:** macOS 14.2

**Steps to reproduce:**
1. Create file with this code:
   ```sigil
   let x! = 42
   ```
2. Run `sigil run file.sigil`
3. Observe error

**Expected:** Program runs successfully
**Actual:** Compiler crashes with stack overflow

Code Style

Rust Code

• Follow standard Rust conventions (rustfmt)
• Use descriptive variable names
• Document public APIs with doc comments
• Prefer Result over panicking

/// Parses an expression from the token stream.
///
/// # Errors
/// Returns `ParseError` if the tokens don't form a valid expression.
pub fn parse_expression(&mut self) -> Result<Expr, ParseError> {
    // Implementation
}

Sigil Code (in examples/tests)

• Use evidence markers consistently
• Prefer morpheme operators for data transformation
• Include comments explaining the example's purpose

Commit Messages

We use conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Adding or modifying tests
• refactor: Code refactoring
• perf: Performance improvement
• chore: Build/tooling changes

Examples:

feat(parser): add support for async functions

fix(types): resolve infinite loop in evidence propagation

docs(stdlib): document List morpheme operators

Pull Requests

Good PRs include:

• Clear description of changes
• Tests for new functionality
• Documentation updates if needed
• Single logical change per PR