Contributing to Keel

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

Ways to Contribute

Report Bugs

Found a bug? Please report it:

Search existing issues first
Create a new issue with:
- Keel version (keel --version)
- Operating system
- Minimal reproduction case
- Expected vs actual behavior

Suggest Features

Have an idea? We'd love to hear it:

Check the roadmap for planned features
Search existing feature requests
Open a discussion or issue describing:
- The problem you're solving
- Your proposed solution
- Alternatives considered

Improve Documentation

Documentation improvements are always welcome:

Fix typos and unclear wording
Add examples
Improve tutorials

Contribute Code

Ready to code? Here's how:

Find or create an issue to work on
Comment that you're working on it
Fork the repository
Make your changes
Submit a pull request

Development Setup

Prerequisites

Git
Rust (latest stable)
Nix (recommended, provides all dependencies via flake.nix)

Clone and Build

# Clone the repository
git clone https://codeberg.org/Keel/keel-core.git
cd keel-core

# Enter nix dev environment
nix develop

# Build
cargo build

# Run tests
cargo test

# Start the REPL
cargo run -- repl

Code Style

Rust Code

Follow standard Rust conventions
Run cargo fmt before committing
Run cargo clippy and address warnings
Add tests for new functionality

Keel Code

Use keel fmt for consistent formatting
Follow the style of existing stdlib code
Document public functions

Commits

Write clear commit messages:

component: Short description (50 chars max)

Longer explanation if needed. Wrap at 72 characters.
Explain what and why, not how.

Fixes #123

Components: parser, types, compiler, runtime, stdlib, docs, refactor, fix, test, chore

Pull Request Process

Create a branch from main:
```
git checkout -b feature/my-feature
```
Make changes with clear commits
Add tests for new functionality
Update documentation if needed
Run the test suite:
```
cargo test
```
Push and create PR:
```
git push origin feature/my-feature
```
Respond to review feedback

PR Checklist

Tests pass locally
Code follows style guidelines
Documentation updated
Commit messages are clear
PR description explains changes

Testing

Run All Tests

cargo test                   # Run all tests
cargo test -- --nocapture    # Run with stdout output

Run Specific Test Modules

cargo test integration::     # Integration tests
cargo test stdlib::          # Standard library tests
cargo test parser::          # Parser tests
cargo test compiler::        # Compiler tests

Test Structure

Tests are organised within the tests/ directory:

tests/
├── integration/    # Full-program integration tests (.rs files)
│   ├── fixtures/   # Keel source files used by tests
│   └── data/       # Test data files (CSV, JSON, Parquet, etc.)
├── compiler/       # Compiler-specific tests
├── parser/         # Parser tests
├── stdlib/         # Standard library tests
└── runtime/        # Runtime/VM tests

Debugging

Logging

RUST_LOG=debug cargo run -- run myfile.kl
RUST_LOG=keel_core=trace cargo run -- run myfile.kl

Time Machine

Keel includes a time-machine debugger (behind the time-machine feature flag) that provides a unified timeline across all compilation phases — lexer, parser, compiler, and VM execution.

Getting Help

Questions: Open a discussion
Stuck on an issue: Comment asking for guidance
Design decisions: Discuss before implementing

Code of Conduct

Be respectful and inclusive. We follow the Contributor Covenant.

License

By contributing, you agree that your contributions will be licensed under the AGPL-3.0.

Thank you for contributing to Keel!