# Contributing to do-over
Thank you for your interest in contributing to do-over! This document provides guidelines and instructions for contributing.
## Code of Conduct
Please be respectful and constructive in all interactions. We welcome contributors of all experience levels.
## Getting Started
### Prerequisites
- Rust 1.70 or later
- Git
### Setup
1. Fork the repository on GitHub
2. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/do-over.git
cd do-over
```
3. Add the upstream remote:
```bash
git remote add upstream https://github.com/nwpz/do-over.git
```
4. Build and test:
```bash
cargo build
cargo test
```
## Development Workflow
### Running Tests
```bash
# Run all tests
cargo test
# Run tests with output
cargo test -- --nocapture
# Run a specific test
cargo test test_name
# Run tests for a specific module
cargo test retry::
```
### Running Examples
```bash
# Run a specific example
cargo run --example retry
# Build all examples
cargo build --examples
```
### Running Benchmarks
```bash
cargo bench
```
### Code Formatting
We use `rustfmt` for code formatting:
```bash
# Check formatting
cargo fmt -- --check
# Apply formatting
cargo fmt
```
### Linting
We use `clippy` for linting:
```bash
cargo clippy -- -D warnings
```
## Making Changes
### Branch Naming
- `feature/description` - New features
- `fix/description` - Bug fixes
- `docs/description` - Documentation changes
- `refactor/description` - Code refactoring
### Commit Messages
Follow conventional commit format:
```
type(scope): description
[optional body]
[optional footer]
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `refactor`: Code refactoring
- `test`: Adding tests
- `chore`: Maintenance
Examples:
```
feat(retry): add jitter to exponential backoff
fix(circuit-breaker): correct state transition timing
docs(readme): add installation instructions
```
### Pull Request Process
1. Create a feature branch from `main`
2. Make your changes with clear, atomic commits
3. Add or update tests as needed
4. Update documentation if applicable
5. Run `cargo fmt` and `cargo clippy`
6. Push your branch and create a Pull Request
7. Fill out the PR template
8. Wait for review and address feedback
## Code Style Guidelines
### General
- Follow Rust idioms and conventions
- Write clear, self-documenting code
- Add doc comments (`///`) to all public items
- Keep functions focused and small
- Prefer explicit error handling over panics
### Documentation
All public items should have documentation:
```rust
/// Brief description of the item.
///
/// More detailed explanation if needed.
///
/// # Examples
///
/// ```rust
/// use do_over::retry::RetryPolicy;
/// use std::time::Duration;
///
/// let policy = RetryPolicy::fixed(3, Duration::from_millis(100));
/// ```
///
/// # Errors
///
/// Returns an error if...
pub fn example_function() -> Result<(), Error> {
// ...
}
```
### Testing
- Write unit tests for all new functionality
- Include edge cases and error conditions
- Use descriptive test names:
```rust
#[test]
fn retry_policy_succeeds_after_transient_failure() {
}
```
## Adding a New Policy
When adding a new resilience policy:
1. Create a new module in `src/` (e.g., `src/my_policy.rs`)
2. Implement the `Policy<E>` trait
3. Add the module to `src/lib.rs`
4. Add comprehensive tests
5. Create an example in `examples/`
6. Update the README with documentation
7. Add an entry to CHANGELOG.md
### Policy Implementation Checklist
- [ ] Implements `Policy<E>` trait
- [ ] Implements `Clone` if possible
- [ ] Is `Send + Sync`
- [ ] Has comprehensive doc comments
- [ ] Has unit tests
- [ ] Has an example
- [ ] Is documented in README
## Reporting Issues
### Bug Reports
Include:
- Rust version (`rustc --version`)
- Operating system
- Minimal reproduction code
- Expected vs actual behavior
- Error messages or panic backtraces
### Feature Requests
Include:
- Use case description
- Proposed API (if applicable)
- Examples of similar features in other libraries
## Questions?
Feel free to open an issue for questions or join discussions on existing issues.
## License
By contributing, you agree that your contributions will be licensed under the MIT OR Apache-2.0 license.