openrunner-rs 1.0.0

# Contributing to OpenRunner-RS

Thank you for your interest in contributing to OpenRunner-RS! This document provides guidelines and information for contributors.

## 🤝 How to Contribute

### Reporting Issues

1. **Search existing issues** first to avoid duplicates
2. **Use issue templates** when available
3. **Provide detailed information**:
   - Operating system and version
   - Rust version (`rustc --version`)
   - OpenRunner-RS version
   - Minimal reproduction case
   - Expected vs actual behavior

### Submitting Pull Requests

1. **Fork the repository** and create a feature branch
2. **Write clear commit messages** following conventional commits
3. **Add tests** for new functionality
4. **Update documentation** if needed
5. **Ensure CI passes** before submitting

## 🛠️ Development Setup

### Prerequisites

- Rust 1.70+ (MSRV)
- Git
- Shell interpreter (bash, sh, etc.)

### Local Development

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/openrunner-rs.git
cd openrunner-rs

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

# Install dependencies and build
cargo build

# Run tests
cargo test

# Run linting
cargo fmt
cargo clippy -- -D warnings

# Run examples
cargo run --example basic
cargo run --example advanced
```

### Testing

```bash
# Run all tests
cargo test

# Run specific tests
cargo test test_name

# Run integration tests
cargo test --test integration_test

# Run with coverage
cargo install cargo-tarpaulin
cargo tarpaulin --out Html

# Run benchmarks
cargo bench
```

## 📝 Code Style

### Formatting

- Use `cargo fmt` for code formatting
- Follow Rust naming conventions
- Use descriptive variable and function names

### Documentation

- Document all public APIs with `///` comments
- Include examples in documentation
- Update README.md for significant changes

### Error Handling

- Use `thiserror` for error types
- Provide descriptive error messages
- Include context in error chains

### Testing

- Write unit tests for all functions
- Include integration tests for major features
- Test error conditions and edge cases
- Use descriptive test names

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

    #[tokio::test]
    async fn test_function_name_should_behavior() {
        // Arrange
        let input = "test input";
        let expected = "expected output";
        
        // Act
        let result = function_name(input).await;
        
        // Assert
        assert_eq!(result.unwrap(), expected);
    }
}
```

## 🏗️ Architecture Guidelines

### Module Organization

- Keep modules focused and cohesive
- Use clear module boundaries
- Export only necessary items

### API Design

- Prioritize ergonomics and clarity
- Use builder patterns for complex configuration
- Provide sensible defaults
- Make APIs hard to misuse

### Performance

- Prefer async/await for I/O operations
- Avoid unnecessary allocations
- Use benchmarks to measure performance
- Profile before optimizing

## 🔍 Review Process

### Pull Request Requirements

- [ ] All tests pass
- [ ] Code is formatted (`cargo fmt`)
- [ ] No clippy warnings (`cargo clippy`)
- [ ] Documentation is updated
- [ ] CHANGELOG.md is updated (for notable changes)

### Review Criteria

- Code quality and readability
- Test coverage and quality
- Documentation completeness
- API design consistency
- Performance implications

## 📋 Commit Guidelines

Use [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

Types:
- `feat`: New features
- `fix`: Bug fixes
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Test additions or modifications
- `chore`: Maintenance tasks

Examples:
```
feat(runner): add timeout support for script execution
fix(error): improve error message for invalid paths
docs(readme): update installation instructions
test(integration): add tests for spawn functionality
```

## 🎯 Areas for Contribution

### High Priority

- Performance optimizations
- Additional platform support
- Enhanced error messages
- More comprehensive examples

### Medium Priority

- Additional I/O options
- Logging improvements
- Configuration validation
- Documentation improvements

### Low Priority

- Code cleanup
- Minor performance tweaks
- Additional utility functions

## 📚 Resources

- [Rust Book](https://doc.rust-lang.org/book/)
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- [tokio Documentation](https://docs.rs/tokio/)
- [thiserror Documentation](https://docs.rs/thiserror/)

## 🐛 Debugging

### Common Issues

1. **Tests failing locally**:
   ```bash
   # Clean build artifacts
   cargo clean
   cargo build
   cargo test
   ```

2. **Clippy warnings**:
   ```bash
   # Fix automatically where possible
   cargo clippy --fix
   ```

3. **Documentation build failures**:
   ```bash
   # Check doc generation
   cargo doc --no-deps
   ```

### Debugging Scripts

Enable logging for better debugging:

```rust
use env_logger;

#[tokio::main]
async fn main() {
    env_logger::init();
    // Your code here
}
```

Set log level:
```bash
RUST_LOG=debug cargo run --example basic
```

## 🚀 Release Process

(For maintainers)

1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Create git tag: `git tag -a v1.x.x -m "Release v1.x.x"`
4. Push tag: `git push origin v1.x.x`
5. GitHub Actions will automatically publish to crates.io

## 📞 Getting Help

- **GitHub Discussions**: For questions and community discussion
- **GitHub Issues**: For bug reports and feature requests
- **Documentation**: Check the [online docs](https://docs.rs/openrunner-rs)

## 📄 License

By contributing to OpenRunner-RS, you agree that your contributions will be licensed under both the MIT and Apache 2.0 licenses.