Skip to content

Contributing to KotaDB

Thank you for your interest in contributing to KotaDB! This project is developed 100% by LLM coding tools, with agents communicating through GitHub issues, PRs, and commits.

How to Contribute

For Human Contributors

  1. Report Issues: Create an issue for bugs or feature requests
  2. Submit PRs: Fork the repo, create a branch, and submit a pull request
  3. Improve Docs: Help improve documentation or add examples
  4. Test & Review: Test new features and review pull requests

For LLM Agents

Follow the Agent Communication Protocol:

# Always comment on issues when working
gh issue comment <issue-number> --body "Starting work on this issue..."

# Create detailed PR descriptions
gh pr create --title "feat: Add feature X" --body "Detailed description..."

# Document all changes
gh api repos/:owner/:repo/commits/<sha>/comments --method POST --field body="..."

Development Workflow

1. Setup Development Environment

# Clone the repository
git clone https://github.com/jayminwest/kota-db.git
cd kota-db

# Install development tools
cargo install just
cargo install cargo-watch

# Run development server
just dev

2. Before Making Changes

# Create a new branch
git checkout -b feature/your-feature-name

# Run tests to ensure clean state
just test

# Check code quality
just check

3. Make Your Changes

Follow the 6-Stage Risk Reduction Methodology: 1. Write tests first (TDD) 2. Define contracts 3. Implement pure functions 4. Add observability 5. Include adversarial tests 6. Use the component library

4. Test Your Changes

# Run all tests
just test

# Run specific test
cargo test test_name

# Run with coverage
just coverage

# Performance tests
just test-perf

5. Code Quality Checks

# Format code
just fmt

# Run clippy (must pass with no warnings)
just clippy

# Security audit
just audit

# Run all checks
just ci

6. Submit Your Changes

# Commit with conventional commit message
git commit -m "feat(component): add new feature"

# Push to your fork
git push origin feature/your-feature-name

# Create PR via GitHub CLI
gh pr create --title "feat: Add feature" --body "Description..."

Code Style Guidelines

Rust Conventions

  • Use descriptive names
  • Prefer immutability
  • Use the type system for safety
  • Handle all errors explicitly
  • Add comprehensive documentation

Example Code Style

/// Validates and creates a new document path
/// 
/// # Arguments
/// * `path` - The path to validate
/// 
/// # Returns
/// * `Result<ValidatedPath>` - The validated path or error
/// 
/// # Example
/// ```
/// let path = validate_document_path("/docs/example.md")?;
/// ```
pub fn validate_document_path(path: &str) -> Result<ValidatedPath> {
    // Implementation with proper error handling
}

Testing Requirements

Test Coverage Goals

  • Unit tests: >90% coverage
  • Integration tests: All major workflows
  • Property tests: Core algorithms
  • Performance tests: Sub-10ms latency

Writing Tests

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

    #[tokio::test]
    async fn test_feature() -> Result<()> {
        // Arrange
        let storage = create_test_storage().await?;

        // Act
        let result = storage.operation().await?;

        // Assert
        assert_eq!(result, expected);
        Ok(())
    }
}

Documentation

Code Documentation

  • Document all public APIs
  • Include examples in doc comments
  • Explain complex algorithms
  • Add architecture decision records

Documentation Types

  • API Docs: Generated from code comments
  • User Guides: In the docs/ directory
  • Examples: Working code in examples/
  • Architecture: Design documents in docs/

Getting Help

  • GitHub Issues: Search existing issues or create new ones
  • Discussions: Ask questions in GitHub Discussions
  • Documentation: Read the comprehensive docs
  • Examples: Check the examples directory

Recognition

Contributors are recognized in: - GitHub contributors page - Release notes - Documentation credits

Thank you for contributing to KotaDB! 🚀