Contributing

​

Welcome contributors

​

Areas of interest

​

Standard library expansion

• String utilities - Advanced string manipulation functions
• Collections - Set operations, advanced list/dict methods
• Networking - HTTP client, socket support
• JSON/serialization - Parse and generate JSON
• Regular expressions - Pattern matching support
• Time/date - DateTime handling and formatting

​

Performance optimizations

• Compiler optimizations - Constant folding, dead code elimination
• VM improvements - Faster bytecode dispatch, specialized opcodes
• JIT enhancements - Support more loop patterns, function inlining
• Memory efficiency - Reduce allocations, improve GC heuristics

​

Language features

• Error handling - Exception system improvements
• Type annotations - Optional static typing
• Pattern matching - Match expressions
• Async/await - Asynchronous programming support
• Macros - Compile-time code generation

​

Documentation improvements

• API documentation - Complete standard library docs
• Tutorials - Beginner-friendly guides
• Examples - Real-world use cases
• Reference - Comprehensive language specification

​

Testing and quality

• Test coverage - Add tests for untested features
• Test framework - Automated test runner
• Benchmarks - Additional performance comparisons
• Fuzz testing - Find edge cases and crashes

​

Getting started

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/walrus.git
cd walrus

cargo build --release
cargo test

git checkout -b feature/my-contribution

​

Development workflow

​

Making changes

1. Write code - Implement your feature or fix
2. Test locally - Verify your changes work correctly
3. Add tests - Include tests for new functionality
4. Update docs - Document new features or changes
5. Run benchmarks - Check for performance regressions

​

Code style

• Run cargo fmt to format code
• Run cargo clippy to check for common issues
• Follow Rust naming conventions
• Add comments for complex logic

​

Testing your changes

# Run the interpreter
cargo run -- examples/showcase.walrus

# Test specific features
cargo run -- your_test.walrus

# Run in different modes
cargo run -- your_test.walrus -c  # Compiled (bytecode VM)
cargo run -- your_test.walrus -i  # Interpreted (tree-walking)

​

Benchmarking

cd benchmarks
./run_benchmarks.sh

​

Submitting changes

git add .
git commit -m "Add string split function to std/string module"

git push origin feature/my-contribution

​

Pull request guidelines

​

Good pull requests

​

PR description template

## Description
Brief description of what this PR does.

## Changes
- List of specific changes made
- Each change on its own line

## Testing
How did you test these changes?

## Related Issues
Fixes #123
Relates to #456

​

Architecture overview

​

Key modules

​

Execution flow

Source → Parser → AST → Interpreter → Result

Source → Parser → AST → Compiler → Bytecode → VM → Result

Source → Parser → AST → Compiler → Bytecode → VM → JIT → Native Code

​

Common contribution patterns

​

Adding a built-in function

1. Add the function to src/interpreter.rs or src/vm.rs
2. Update builtin dispatch in the appropriate module
3. Add hover docs to src/bin/walrus-lsp.rs
4. Write tests in tests/
5. Document in README.md or docs

​

Adding a standard library module

1. Create a new file in src/stdlib/
2. Implement module functions
3. Register module in the import system
4. Add examples and documentation
5. Write comprehensive tests

​

Adding a language feature

1. Update grammar in src/grammar.lalrpop
2. Add AST nodes in src/ast.rs
3. Implement in interpreter (src/interpreter.rs)
4. Implement in compiler (src/compiler.rs)
5. Implement in VM (src/vm.rs)
6. Update LSP if needed (src/lsp_support.rs)
7. Add tests and documentation

​

Community

​

Communication

• GitHub Issues - Bug reports and feature requests
• Pull Requests - Code contributions and reviews
• Discussions - Design discussions and questions

​

Code of conduct

• Be respectful and welcoming
• Provide constructive feedback
• Focus on what’s best for the project
• Help newcomers get started

​

License

​

Questions?

1. Check existing issues and discussions
2. Review this contributing guide
3. Open a new issue with the “question” label
4. Reach out to maintainers