# Contributing to Ruchy
Thank you for your interest in contributing to Ruchy! **With our historic self-hosting achievement (v1.5.0), you can now contribute to the Ruchy compiler using Ruchy itself!**
## 🎉 Self-Hosting Development
**NEW**: Ruchy is now fully self-hosting! This means:
- **Write compiler features in Ruchy**: Use familiar Ruchy syntax to implement parser, type inference, and codegen improvements
- **Bootstrap development cycle**: Test your changes immediately with `ruchy run` and `ruchy transpile --minimal`
- **Enhanced type safety**: Algorithm W type inference catches errors during development
- **Direct Rust output**: See exactly what Rust code your Ruchy contributions generate
## Code of Conduct
Please be respectful and constructive in all interactions. We aim to maintain a welcoming and inclusive community.
## Getting Started
### Traditional Rust Development
1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/ruchy`
3. Create a feature branch: `git checkout -b feature/your-feature`
4. Make your changes in Rust (`src/` directory)
5. Run tests: `make test` (fast tests, ~5 seconds)
6. Run linting: `make lint`
7. Commit with descriptive message
8. Push to your fork
9. Create a Pull Request
### 🆕 Self-Hosting Development (Recommended!)
1. Fork and clone as above
2. Create a feature branch: `git checkout -b feature/your-feature-ruchy`
3. **Write your feature in Ruchy** (see `bootstrap_*.ruchy` examples)
4. Test immediately: `ruchy run your_feature.ruchy`
5. Transpile to Rust: `ruchy transpile your_feature.ruchy --minimal --output feature.rs`
6. Integrate the generated Rust into the codebase
7. Run full test suite: `make test`
8. Commit both the `.ruchy` source and generated `.rs` files
9. Create a Pull Request showcasing self-hosting development!
## Development Setup
### Prerequisites
- Rust 1.75 or later
- cargo-nextest: `cargo install cargo-nextest`
- cargo-llvm-cov: `cargo install cargo-llvm-cov`
### Building
```bash
cargo build --all-features --workspace
```
### Testing
```bash
# Run fast tests only (~5 seconds after initial build)
make test
# Run all tests including slow/integration tests
make test-all
# Run tests with nextest (better output)
make test-nextest
# Run specific test
cargo test test_name
# Run with coverage
make coverage
```
### Linting
```bash
# Format code
cargo fmt --all
# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
# Or use make
make lint
```
## Quality Standards (v1.9.1 - Language Complete)
### Code Quality - Toyota Way (Zero Defects)
- **Zero SATD**: No TODO/FIXME/HACK comments - track in GitHub Issues instead
- **Zero Warnings**: All code must pass `make lint` with `-D warnings` flag
- **Complexity < 50**: All functions must have cyclomatic complexity under 50
- **Tested**: New features require tests with 80% minimum coverage
- **Documented**: Public APIs need documentation with examples
- **Language Features**: 19% book compatibility, 100% one-liners working
### Testing Requirements
- Unit tests for new functionality
- Property-based tests for complex logic
- Integration tests for user-facing features
- Coverage minimum: 80% for all modules
- Use `ruchy test --coverage` to verify
### Revolutionary Development Tools
As of v0.10.0, Ruchy provides world-first development tools:
```bash
# Formal verification (World's First)
ruchy provability script.ruchy --verify
# Automatic BigO complexity detection (World's First)
ruchy runtime script.ruchy --bigo
# Enhanced AST analysis
ruchy ast script.ruchy --json --metrics
# Professional testing with coverage
ruchy test --coverage --threshold 80
# Code formatting
ruchy fmt script.ruchy --check
# Grammar-based linting
ruchy lint script.ruchy --strict
```
### Mandatory Quality Gates (BLOCKING)
All commits must pass these quality gates (enforced by pre-commit hooks):
```bash
# 1. Basic functionality must work
# 2. Zero warnings allowed
make lint # Runs: cargo clippy -- -D warnings
# 3. Zero SATD comments
! grep -r "TODO\|FIXME\|HACK" src/ --include="*.rs"
# 4. Coverage threshold
ruchy test --coverage --threshold 80
# 5. Complexity check (via PMAT if installed)
pmat check --max-complexity 50 --fail-fast
```
### Extreme Quality Engineering
We follow extreme quality engineering principles:
1. **Canonical AST**: All transformations use normalized representation
2. **Reference Interpreter**: Semantic verification against ground truth
3. **Deterministic Builds**: Reproducible compilation guaranteed
4. **Error Recovery**: Parser continues on malformed input
5. **Provenance Tracking**: Full audit trail of transformations
6. **Formal Verification**: Mathematical correctness via `ruchy provability`
7. **Performance Analysis**: Automatic BigO detection via `ruchy runtime`
## Architecture
### Project Structure
```
ruchy/
├── src/
│ ├── frontend/ # Parser and lexer
│ ├── middleend/ # Type inference and analysis
│ ├── backend/ # Code generation
│ ├── runtime/ # REPL and execution
│ ├── transpiler/ # Core transpilation logic
│ ├── parser/ # Error recovery system
│ └── testing/ # Test infrastructure
├── ruchy-cli/ # Command-line interface
├── tests/ # Integration tests
├── examples/ # Example programs
└── docs/ # Documentation
```
### Key Components
- **Parser**: Recursive descent with Pratt parsing
- **Type System**: Hindley-Milner with Algorithm W
- **Transpiler**: AST to Rust code generation
- **REPL**: Interactive development environment
## Submitting Changes
### Pull Request Process
1. Ensure all tests pass
2. Update documentation if needed
3. Add entry to CHANGELOG.md
4. Ensure PR description explains:
- What changes were made
- Why they were needed
- How they were tested
### Commit Messages
Follow conventional commits format:
```
type(scope): description
[optional body]
[optional footer]
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `test`: Testing
- `refactor`: Code refactoring
- `perf`: Performance improvement
- `chore`: Maintenance
Example:
```
feat(repl): add variable persistence across commands
Implements state management for REPL sessions to maintain
variable bindings between commands.
Fixes #123
```
## Testing Guidelines
### Test Categories
1. **Unit Tests**: In `src/*/tests.rs` or `#[cfg(test)]` modules
2. **Integration Tests**: In `tests/` directory
3. **Property Tests**: Using proptest for invariants
4. **Snapshot Tests**: For regression detection
5. **Chaos Tests**: Environmental variance testing
### Writing Tests
```rust
#[test]
fn test_feature() {
// Arrange
let input = "test input";
// Act
let result = function_under_test(input);
// Assert
assert_eq!(result, expected);
}
```
## Documentation
### Code Documentation
```rust
/// Brief description of the function.
///
/// # Arguments
///
/// * `param` - Description of parameter
///
/// # Returns
///
/// Description of return value
///
/// # Examples
///
/// ```
/// use ruchy::function;
/// let result = function(input);
/// ```
pub fn function(param: Type) -> Result<Output> {
// Implementation
}
```
### User Documentation
- Update README.md for user-facing changes
- Add examples to `examples/` directory
- Update CLI help text if needed
## Release Process
1. Update version in Cargo.toml
2. Update CHANGELOG.md
3. Create release notes
4. Tag release: `git tag v0.x.x`
5. Push tag: `git push origin v0.x.x`
## Getting Help
- Open an issue for bugs or features
- Ask questions in discussions
- Check existing issues before creating new ones
## License
By contributing, you agree that your contributions will be licensed under the same terms as the project (MIT OR Apache-2.0).