Contributing

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

Getting Started

1. Set Up Development Environment

First, clone and set up the repository:

git clone https://github.com/mwoelker/felico.git
cd felico
cargo build

2. Install Git Hooks

Install the pre-commit hooks to ensure code quality:

./scripts/git-hooks/install-hooks.sh

The pre-commit hook runs:

• cargo fmt - Format code
• cargo clippy -- -D warnings - Lint with strict warnings
• cargo test - Run all tests with RUSTFLAGS='-D warnings'

Building and Testing

Build Commands

cargo build          # Build project (dev profile)
cargo build --release # Build with optimizations
cargo test           # Run all tests
cargo fmt            # Format code
cargo clippy         # Lint (use: cargo clippy -- -D warnings)

Run a Single Test

cargo test test_name

Build Profiles

• dev: Fast compilation (opt-level=0), dependencies optimized (opt-level=3)
• release: Optimized for size (opt-level=“z”), LTO enabled, symbols stripped

Making Changes

Commit Message Format

Felico uses Conventional Commits. Format: type(scope): description

Valid types: wip, build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

Examples:

feat(parser): add support for while loops
fix(interpreter): resolve variable scope issue
docs(readme): update installation instructions
test(lexer): add tests for string escaping

Code Style

• Follow Rust idioms and conventions
• Run cargo fmt before committing
• Ensure cargo clippy passes with no warnings
• Add tests for new functionality
• Update documentation as needed

Project Structure

felico/
├── crates/
│   ├── felico_interpreter/  # Tree-walking interpreter
│   └── ...                   # Other crates
├── docs/                     # This documentation (mdBook)
├── scripts/                  # Build and development scripts
└── examples/                 # Example programs

Areas to Contribute

Code

• Parser: Improve syntax support
• Interpreter: Add new features or optimize performance
• Type system: Enhance type checking
• Error messages: Make errors more helpful
• Testing: Add test coverage

Documentation

• Fix typos or unclear explanations
• Add examples and tutorials
• Improve API documentation
• Translate documentation

Community

• Answer questions in issues
• Help review pull requests
• Share your Felico projects
• Report bugs with clear reproduction steps

Pull Request Process

1. Fork the repository and create a feature branch
2. Make your changes with clear, focused commits
3. Ensure all tests pass and add new tests if needed
4. Update documentation if you changed behavior
5. Submit a pull request with a clear description

Community Guidelines

Remember Felico’s core values:

• Fun: Keep contributions enjoyable and creative
• Friendly: Be respectful and assume good intentions
• Fast: Respect everyone’s time with clear communication

We welcome contributors of all experience levels. Don’t hesitate to ask questions!

Getting Help

• Issues: Open an issue on GitHub
• Discussions: Use GitHub Discussions for questions
• Documentation: Check this documentation site

License

By contributing, you agree that your contributions will be licensed under the same license as the project.