Contributing Guide¶

Thank you for your interest in contributing to HeliosDB-Lite!

Getting Started¶

Prerequisites¶

Rust 1.75+ (stable)
Git
Optional: Docker for integration tests

Setup¶

# Clone the repository
git clone https://github.com/heliosdb/heliosdb-lite.git
cd heliosdb-lite

# Build the project
cargo build

# Run tests
cargo test

Development Workflow¶

Branch Strategy¶

main          ← stable releases only
  └── develop ← integration branch
        ├── feature/xxx  ← new features
        ├── fix/xxx      ← bug fixes
        └── docs/xxx     ← documentation

Making Changes¶

Fork the repository

Create a branch from develop:

git checkout -b feature/your-feature develop

Make changes following the code style guide
Write tests for new functionality
Run the test suite:
```
cargo test --all-features
```
Submit a pull request to develop

Code Style¶

Rust Guidelines¶

Follow standard Rust formatting (cargo fmt)
Use cargo clippy and fix all warnings
Document public APIs with doc comments
Use meaningful variable and function names

Example¶

/// Executes a SQL query and returns results.
///
/// # Arguments
///
/// * `sql` - The SQL query string
/// * `params` - Query parameters for prepared statements
///
/// # Returns
///
/// Query results or an error
///
/// # Example
///
/// ```
/// let result = db.query("SELECT * FROM users WHERE id = $1", &[Value::Int4(1)])?;
/// ```
pub fn query(&self, sql: &str, params: &[Value]) -> Result<QueryResult> {
    // Implementation
}

Commit Messages¶

Use conventional commits:

type(scope): description

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation only - refactor: Code change that neither fixes a bug nor adds a feature - test: Adding or updating tests - perf: Performance improvement - chore: Maintenance tasks

Examples:

feat(branching): add branch diff command
fix(parser): handle escaped quotes in strings
docs(api): update vector search examples

Testing¶

Test Categories¶

Category	Command	Purpose
Unit	`cargo test --lib`	Test individual functions
Integration	`cargo test --test '*'`	Test component interactions
Compatibility	`cargo test compatibility`	PostgreSQL compatibility

Writing Tests¶

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_query_simple_select() {
        let db = EmbeddedDatabase::new_memory().unwrap();
        db.execute("CREATE TABLE test (id INT)").unwrap();
        db.execute("INSERT INTO test VALUES (1)").unwrap();

        let result = db.query("SELECT * FROM test").unwrap();
        assert_eq!(result.rows.len(), 1);
    }
}

Test Data¶

Use small, focused test cases
Clean up test data after each test
Use in-memory databases for speed

Pull Request Process¶

Before Submitting¶

[ ] Code compiles without warnings
[ ] All tests pass
[ ] New tests added for new features
[ ] Documentation updated
[ ] Commit messages follow conventions

Review Process¶

Automated CI checks must pass
At least one maintainer review required
Address review feedback
Squash commits if requested
Maintainer merges to develop

PR Template¶

## Description
[Brief description of changes]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Refactoring

## Testing
[How was this tested?]

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] Code follows style guide

Architecture Guidelines¶

Adding New Features¶

Check existing patterns - Look at similar features
Update the parser - Add SQL syntax if needed
Implement in planner - Create logical plan nodes
Add executor support - Physical execution
Write tests - Unit and integration
Update documentation - User and developer docs

File Organization¶

src/
├── sql/
│   ├── parser.rs      ← SQL parsing
│   ├── planner.rs     ← Logical planning
│   └── executor/      ← Execution
├── storage/
│   └── ...            ← Storage layer
└── vector/
    └── ...            ← Vector search

Getting Help¶

Questions: Open a GitHub Discussion
Bugs: Open a GitHub Issue
Security: See Security Policy

Code of Conduct¶

Be respectful and inclusive. We welcome contributors of all experience levels and backgrounds.

License¶

By contributing, you agree that your contributions will be licensed under the same license as the project (Apache 2.0 or MIT, at your option).