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:

1. Search existing issues first
2. 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:

1. Check the roadmap for planned features
2. Search existing feature requests
3. 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
• Translate documentation

Contribute Code

Ready to code? Here's how:

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

Development Setup

Prerequisites

• Git
• Rust (latest stable)
• LLVM 15+

Clone and Build

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

# Build
cargo build

# Run tests
cargo test

# Run the compiler
cargo run -- repl

Project Structure

keel/
├── crates/
│   ├── keel-parser/     # Lexer and parser
│   ├── keel-ast/        # Abstract syntax tree
│   ├── keel-types/      # Type system
│   ├── keel-compiler/   # Code generation
│   └── keel-runtime/    # Runtime library
├── stdlib/              # Standard library
├── tests/               # Integration tests
└── docs/                # Documentation

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, codegen, runtime, stdlib, docs, cli

Pull Request Process

1. Create a branch from main:

   git checkout -b feature/my-feature
   

2. Make changes with clear commits

3. Add tests for new functionality

4. Update documentation if needed

5. Run the test suite:

   cargo test
   

6. Push and create PR:

   git push origin feature/my-feature
   

7. Respond to review feedback

PR Checklist

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

Testing

Unit Tests

cargo test -p keel-parser    # Test specific crate
cargo test                   # Test everything

Integration Tests

cargo test --test integration

Test Files

Place test cases in tests/cases/:

tests/cases/
├── pass/           # Should compile successfully
│   └── basic.kl
├── fail/           # Should produce errors
│   └── type_error.kl
└── run/            # Should compile and run
    └── hello.kl

Debugging

Compiler Flags

# Show parsed AST
keel build --dump-ast

# Show typed AST
keel build --dump-typed

# Show generated IR
keel build --dump-ir

Logging

RUST_LOG=debug cargo run -- build
RUST_LOG=keel_parser=trace cargo run -- build

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 MIT License.

Recognition

Contributors are recognized in:

• CONTRIBUTORS file
• Release notes
• Website credits

Thank you for contributing to Keel!