Contributor Guide

Getting Started

1. Fork and clone the repository:

git clone https://github.com/sailfin/sailfin.git
cd sailfin

2. Set up the development environment:

make env       # Create Conda environment
make compile   # Build the compiler from seed
make test      # Verify everything works

3. Create a feature branch:

git checkout -b feature/my-feature alpha

Development Workflow

Making Changes

1. Edit compiler source in compiler/src/*.sfn
2. Rebuild: make compile
3. Run tests: make test
4. Validate self-hosting: make check

Adding a Language Feature

1. Update the parser (compiler/src/parser.sfn)
2. Add AST nodes (compiler/src/ast.sfn)
3. Update the emitter (compiler/src/emit_native.sfn)
4. Extend LLVM lowering (compiler/src/llvm/lowering/)
5. Add regression tests (compiler/tests/)
6. Update docs/spec.md and docs/status.md

Self-Hosting Invariant

The compiler must always compile itself. Before submitting:

make compile   # Build from seed
make check     # Validate seedcheck binary
make test      # Full test suite

Branch Strategy

• main — Stable releases
• alpha — Prerelease builds (-alpha suffix)
• Feature branches merge to alpha

Principles

• Fix the compiler, not the build script. Don’t add fixup passes — fix the root cause in compiler/src/.
• Reduce complexity. The fixup pass count should decrease over time.
• Build must be fast and deterministic. Under 5 minutes, zero retries.

Submitting Changes

1. Ensure make check and make test pass
2. Open a PR against the alpha branch
3. Include test coverage for new features or bug fixes
4. Update documentation if the change affects language behavior