---
title: "Contributing Guide"
---

# Contributing Guide

Thank you for your interest in contributing to HeliosDB Nano.

## Getting Started

### Prerequisites

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

### Setup

```bash
# Clone the repository
git clone https://github.com/HeliosDatabase/HeliosDB-Nano.git
cd heliosdb-nano

# 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

1. **Fork** the repository
2. **Create a branch** from `develop`:
   ```bash
   git checkout -b feature/your-feature develop
   ```
3. **Make changes** following the code style guide
4. **Write tests** for new functionality
5. **Run the test suite**:
   ```bash
   cargo test --all-features
   ```
6. **Submit a pull request** to `develop`

## Code Style

### Rust Guidelines

- Follow standard Rust formatting (`cargo fmt`)
- Use `static analysis checks` and fix all warnings
- Document public APIs with doc comments
- Use meaningful variable and function names

### Example

```rust
/// 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

```rust
#[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

1. Automated CI checks must pass
2. At least one maintainer review required
3. Address review feedback
4. Squash commits if requested
5. Maintainer merges to `develop`

### PR Template

```markdown
## 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

1. **Check existing patterns** - Look at similar features
2. **Update the parser** - Add SQL syntax if needed
3. **Implement in planner** - Create logical plan nodes
4. **Add executor support** - Physical execution
5. **Write tests** - Unit and integration
6. **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](https://www.heliosdb.com/docs/nano/resources/security/)

## 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, the Apache License 2.0.