# Contributing to cobt
Thank you for your interest in contributing to cobt! This document provides guidelines and instructions for contributing to the project.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [How to Contribute](#how-to-contribute)
- [Development Workflow](#development-workflow)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Documentation](#documentation)
- [Submitting Changes](#submitting-changes)
## Code of Conduct
Be respectful, constructive, and professional in all interactions. We aim to foster a welcoming and inclusive community.
## Getting Started
1. Fork the repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/Toby-Faucher/cobt.git
cd cobt
```
3. Add the upstream repository:
```bash
git remote add upstream https://github.com/Toby-Faucher/cobt.git
```
4. Build the project:
```bash
cargo build
```
5. Run the tests:
```bash
cargo test
```
## How to Contribute
### Reporting Bugs
- Check existing issues to avoid duplicates
- Use the GitHub issue tracker
- Include:
- A clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Your environment (Rust version, OS, etc.)
- Minimal code example if applicable
### Suggesting Features
- Open an issue describing the feature
- Explain the use case and benefits
- Be open to discussion and feedback
### Improving Documentation
Documentation improvements are always welcome! This includes:
- README enhancements
- API documentation (doc comments)
- Code examples
- Tutorials or guides
## Development Workflow
1. Create a new branch for your work:
```bash
git checkout -b feature/your-feature-name
```
Or for bug fixes:
```bash
git checkout -b fix/issue-description
```
2. Make your changes following the coding standards
3. Test your changes thoroughly
4. Commit your changes with clear, descriptive messages:
```bash
git commit -m "Add feature: description of what you did"
```
5. Keep your branch up to date with upstream:
```bash
git fetch upstream
git rebase upstream/master
```
6. Push your changes to your fork:
```bash
git push origin your-branch-name
```
7. Open a Pull Request on GitHub
## Coding Standards
### Rust Style
- Follow the official [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/)
- Run `cargo fmt` before committing to ensure consistent formatting
- Run `cargo clippy` and address any warnings
- Use meaningful variable and function names
- Keep functions focused and reasonably sized
### Documentation
- Add doc comments (`///`) for all public APIs
- Include examples in doc comments where helpful
- Document panics, errors, and safety requirements
- Use `//!` for module-level documentation
Example:
```rust
/// Searches for a key in the tree.
///
/// # Arguments
///
/// * `key` - The key to search for
///
/// # Returns
///
/// Returns `Some(&V)` if the key is found, `None` otherwise.
///
/// # Examples
///
/// ```
/// use cobt::CacheObliviousBTree;
///
/// let mut tree = CacheObliviousBTree::new();
/// tree.insert(1, "value");
/// assert_eq!(tree.search(&1), Some(&"value"));
/// ```
pub fn search(&self, key: &K) -> Option<&V> {
// implementation
}
```
## Testing
- Write tests for new functionality
- Ensure all tests pass: `cargo test`
- Run benchmarks if performance-related: `cargo bench`
- Add integration tests when appropriate
- Test edge cases and error conditions
## Documentation
- Update the README if you're adding user-facing features
- Add examples for new functionality
- Keep the CHANGELOG updated (if it exists)
- Ensure `cargo doc` builds without warnings
## Submitting Changes
### Pull Request Guidelines
- Create a focused PR that addresses a single concern
- Write a clear title and description
- Reference any related issues (e.g., "Fixes #123")
- Ensure all tests pass
- Respond to review feedback promptly
- Be patient - maintainers review PRs as time allows
### PR Checklist
Before submitting, verify:
- [ ] Code compiles without errors
- [ ] All tests pass (`cargo test`)
- [ ] Code is formatted (`cargo fmt`)
- [ ] No clippy warnings (`cargo clippy`)
- [ ] Documentation is updated
- [ ] Examples are added/updated if needed
- [ ] Commit messages are clear and descriptive
## Questions?
If you have questions that aren't covered here, feel free to:
- Open an issue for discussion
- Reach out to the maintainers
Thank you for contributing to cobt!