escher-execution-engine 0.1.2

# Contributing to Escher Execution Engine

Thank you for your interest in contributing to the Escher Execution Engine! This document provides guidelines and instructions for contributing to the project.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Code Standards](#code-standards)
- [Testing Guidelines](#testing-guidelines)
- [Submitting Changes](#submitting-changes)
- [Release Process](#release-process)

---

## Code of Conduct

This project adheres to professional standards of conduct. Please be respectful and constructive in all interactions.

---

## Getting Started

### Prerequisites

- Rust 1.70 or higher
- Git
- Basic understanding of async Rust and Tokio

### Setting Up Development Environment

1. **Clone the repository:**
```bash
git clone https://github.com/escher-dbai/v2-execution-engine-rust.git
cd v2-execution-engine-rust
```

2. **Build the project:**
```bash
cargo build
```

3. **Run tests:**
```bash
cargo test
```

4. **Check code quality:**
```bash
cargo fmt --check
cargo clippy -- -D warnings
```

---

## Development Workflow

### 1. Create a Feature Branch

```bash
# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name
```

### 2. Make Your Changes

- Write clear, concise commit messages
- Follow the existing code style and conventions
- Add tests for new functionality
- Update documentation as needed

### 3. Before Committing

Run the full check suite:

```bash
# Format code
cargo fmt

# Check for linting issues
cargo clippy -- -D warnings

# Run all tests
cargo test

# Run integration tests
cargo test --test integration_tests

# Optional: Run benchmarks if performance-related
cargo bench
```

### 4. Commit Your Changes

```bash
# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add new feature description"

# Or for bug fixes
git commit -m "fix: resolve issue description"
```

### Commit Message Conventions

Use conventional commit format:

- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation only
- `style:` - Code style changes (formatting, etc.)
- `refactor:` - Code refactoring
- `test:` - Adding or updating tests
- `perf:` - Performance improvements
- `chore:` - Maintenance tasks

---

## Code Standards

### Rust Best Practices

1. **No Deprecated Code** - Remove deprecated code entirely, never use `#[allow(deprecated)]`
2. **Import Scoping** - Keep imports in narrowest scope (prefer test module over file-level)
3. **Error Propagation** - Use `?` operator, avoid `.unwrap()` except in tests
4. **Async Ownership** - Clone Arc references before moving into spawned tasks
5. **Documentation** - All public items must have `///` doc comments
6. **Type Aliases** - Use type aliases for complex types

### Code Style

- **Always run `cargo fmt` before committing**
- Follow Rust 2021 edition style guide
- 100 character line limit (soft, enforced by rustfmt)
- Use meaningful variable and function names
- Add inline comments for complex logic

### Documentation Requirements

- Public APIs must have `///` doc comments
- Include examples in doc comments where appropriate
- Update [CLAUDE.md](./CLAUDE.md) for major changes
- Update [docs/](./docs/) directory for architectural changes

---

## Testing Guidelines

### Test Coverage

- All new features must include tests
- Aim for comprehensive test coverage
- Include both unit tests and integration tests

### Test Types

**Unit Tests:**
```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_feature_name() {
        // Test implementation
    }
}
```

**Integration Tests:**
Located in `tests/` directory:
```rust
// tests/integration_test.rs
#[tokio::test]
async fn test_end_to_end_scenario() {
    // Test implementation
}
```

### Running Tests

```bash
# Run all tests
cargo test

# Run specific test
cargo test test_name -- --exact

# Run with output
cargo test -- --nocapture

# Run only unit tests
cargo test --lib

# Run only integration tests
cargo test --test integration_tests
```

---

## Submitting Changes

### Pull Request Process

1. **Push your branch:**
```bash
git push origin feature/your-feature-name
```

2. **Create Pull Request:**
   - Go to GitHub repository
   - Click "New Pull Request"
   - Select your branch
   - Fill in PR template with:
     - Description of changes
     - Related issues (if any)
     - Testing performed
     - Checklist completion

3. **PR Checklist:**
   - [ ] Code follows project style guidelines
   - [ ] All tests pass (`cargo test`)
   - [ ] No clippy warnings (`cargo clippy -- -D warnings`)
   - [ ] Code is formatted (`cargo fmt --check`)
   - [ ] Documentation is updated
   - [ ] CHANGELOG.md is updated (if applicable)
   - [ ] New tests added for new features

4. **Review Process:**
   - Wait for code review
   - Address review comments
   - Push updates to same branch
   - Request re-review if needed

### PR Title Format

Use conventional commit format:
```
feat: add support for custom event handlers
fix: resolve timeout race condition
docs: update API documentation
```

---

## Release Process

### Version Numbering

Follow [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Creating a Release

**For Maintainers:**

1. **Update version in Cargo.toml:**
```toml
[package]
version = "0.2.0"  # Update version
```

2. **Update CHANGELOG.md:**
```markdown
## [0.2.0] - 2025-12-XX
### Added
- New feature description
### Fixed
- Bug fix description
```

3. **Commit version bump:**
```bash
git add Cargo.toml CHANGELOG.md
git commit -m "chore: bump version to 0.2.0"
git push origin main
```

4. **Create and push tag:**
```bash
git tag v0.2.0
git push origin v0.2.0
```

5. **Create GitHub Release:**
   - Go to GitHub Releases
   - Click "Create a new release"
   - Select tag: `v0.2.0`
   - Title: `Release v0.2.0`
   - Description: Copy from CHANGELOG.md
   - Publish release

---

## Project Structure

Understanding the codebase structure:

```
src/
├── lib.rs              # Public API exports
├── engine.rs           # ExecutionEngine (main entry point)
├── executor.rs         # Command execution logic
├── config.rs           # Configuration
├── types.rs            # Core data structures
├── events.rs           # Event system
├── errors.rs           # Error types
├── commands.rs         # Command builder
└── cleanup.rs          # Memory cleanup

tests/                  # Integration tests
examples/               # Usage examples
docs/                   # Documentation
```

---

## Getting Help

### Resources

- **[CLAUDE.md](./CLAUDE.md)** - Development guide and common patterns
- **[docs/](./docs/)** - Comprehensive documentation
- **[README.md](./README.md)** - Quick start guide

### Communication

- Open an issue for bugs or feature requests
- Use GitHub Discussions for questions
- Tag maintainers for urgent issues

---

## License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.

---

## Thank You!

Your contributions make this project better. We appreciate your time and effort!