Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (95 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

135 lines (95 loc) · 4.38 KB
Raw

Contributing to ilo

Thanks for your interest in contributing to ilo!

Getting Started

git clone https://github.com/ilo-lang/ilo
cd ilo
cargo test

Shared build cache (recommended)

ilo development typically involves many worktrees (one per fix / feature branch). By default each worktree gets its own target/ directory and these add up fast, historically into the tens of GB on a single developer machine. Set a shared cache once in your shell config:

# ~/.zshrc or ~/.bashrc
export CARGO_TARGET_DIR="$HOME/.cargo-shared"
mkdir -p "$CARGO_TARGET_DIR"

All worktrees then share one build cache. Cargo namespaces artefacts per package + feature combination internally, so this is safe across branches.

Empirical discipline

Claims about ilo's performance, token count, or runtime behaviour need benchmarks or tests, not assertions. "Measured, not asserted" is the rule. If you're tightening a hot path, add a criterion bench or a deterministic timing harness. If you're claiming a token win in docs, the number comes from the benchmark, not from rounding what feels right.

The binary-size tripwire (tests/binary_size.rs) is one expression of this: AOT output for a trivial program is checked against a ceiling on every CI run, so dep upgrades that inflate the runtime fail loudly instead of drifting silently.

Strategic context

Longer-form plans for upcoming phases live in zero-gap-specs/ (separate repo). Briefs there set the why; PRs here implement the how.

Development

  • Run tests: cargo test
  • Run clippy: cargo clippy -- -W clippy::all
  • Run a program: cargo run -- 'f x:n>n;*x 2' 5

Pull Requests

  1. Fork the repo and create a feature branch from next
  2. Make your changes
  3. Ensure cargo test and cargo clippy pass
  4. Submit a PR with a clear description of the change

Patches against the current release line (a fix for 26.5 that needs to ship as 26.5.1) branch from main instead. See README.md#versioning for the full branch / tag model.

Architecture

The pipeline flows: Lexer -> Parser -> AST -> Verifier -> Interpreter/VM/Cranelift JIT

Key source files:

  • src/lexer/mod.rs - tokenizer
  • src/parser/mod.rs - parser producing AST
  • src/ast/mod.rs - AST types
  • src/verify.rs - static type checker
  • src/interpreter/mod.rs - tree-walking interpreter
  • src/vm/mod.rs - register-based VM
  • src/codegen/python.rs - Python transpiler
  • src/diagnostic/ - error codes and reporting

Community

Language Spec

See SPEC.md for the full language specification. Changes to language syntax or semantics should update the spec.

Golden-file diagnostics

ilo pins the JSON shape of its diagnostic output with golden snapshot files stored under conformance/diagnostics/. When you change a diagnostic message, add a phase field, or add a new error code, CI will fail on a diff unless you also update the matching snapshot.

Running the golden tests

cargo test --features golden

Updating (blessing) snapshots

If you intentionally changed a diagnostic's JSON shape, re-bless the affected golden files:

cargo test --features golden -- --bless

This rewrites every conformance/diagnostics/<CODE>.expected.json whose content has changed. Review the diff with git diff conformance/ before committing — the snapshot is part of the stability contract.

You can also bless a single code by running the specific test:

ILO_GOLDEN_BLESS=1 cargo test --features golden golden_ilo_t004

Adding a new error code

  1. Add the entry to src/diagnostic/registry.rs with a phase field set to the correct Phase::* variant.
  2. Run cargo test --features golden -- --bless to generate the initial golden file.
  3. Commit both the registry change and the new .expected.json file.

Provenance surface

conformance/provenance-surface.json maps every language feature to the compiler function that owns it and the fixture that exercises it. When you add a new feature or move code to a different function, update this file to keep the map accurate. The provenance_surface_is_valid golden test will catch structural problems.

License

By contributing, you agree that your contributions will be licensed under the MIT License.