Contributing to Orbit-RS

Thank you for your interest in contributing to Orbit-RS! This document provides guidelines and information about contributing to the project.

Table of Contents

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please treat all contributors and users with respect and create a welcoming environment for everyone.

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/yourusername/orbit-rs.git
cd orbit-rs

  3. Add the upstream remote:

    git remote add upstream https://github.com/original/orbit-rs.git

Development Setup

Prerequisites

Building the Project


# Build all crates
cargo build

# Build with all features
cargo build --all-features

# Build specific crate
cargo build --package orbit-shared

Running Tests


# Run all tests
cargo test

# Run tests for specific crate
cargo test --package orbit-shared

# Run tests with output
cargo test -- --nocapture

# Run ignored tests
cargo test -- --ignored

Running Examples


# Hello World example
cargo run --example hello-world

# Distributed Transactions example
cargo run --example distributed-transactions

Contributing Process

1. Choose What to Work On

2. Create a Branch

git checkout -b feature/your-feature-name

Branch naming conventions:

3. Make Changes

Follow the coding standards and guidelines outlined below.

4. Test Your Changes

Ensure all tests pass and add new tests for your changes:

cargo test
cargo clippy
cargo fmt --all

5. Commit Your Changes

Write clear, descriptive commit messages:

git commit -m "feat: add distributed transaction recovery mechanism

- Implement coordinator failover detection
- Add transaction checkpoint management  
- Include recovery event handlers
- Add comprehensive tests for recovery scenarios
"

Commit message format:

Coding Standards

Rust Style Guide

Code Organization

// File structure within modules
use std::...;           // Standard library
use external_crate::...;  // External dependencies  
use crate::...;         // Internal crate dependencies

// Constants
const MAX_RETRIES: u32 = 3;

// Type definitions
pub type TransactionId = String;

// Structs and enums

#[derive(Debug, Clone)]
pub struct MyStruct {
    // fields
}

// Trait definitions
pub trait MyTrait {
    // methods
}

// Implementations
impl MyStruct {
    // methods
}

// Tests (at bottom of file)

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_my_function() {
        // test code
    }
}

Transaction System Guidelines

When working on transaction-related code:

Documentation Standards

Example:

/// Begins a new distributed transaction across multiple participants.
///
/// This method initiates a 2-phase commit protocol that ensures ACID
/// properties across distributed actors. The transaction will timeout
/// after the specified duration.
///
/// # Arguments
///
/// * `timeout` - Optional timeout for the transaction. If None, uses
///   the configured default timeout.
///
/// # Returns
///
/// Returns a `TransactionId` that can be used to add operations and
/// commit the transaction.
///
/// # Errors
///
/// Returns `OrbitError::Internal` if the maximum number of concurrent
/// transactions has been exceeded.
///
/// # Example
///
/// ```rust
/// let tx_id = coordinator.begin_transaction(Some(Duration::from_secs(30))).await?;
/// // Add operations and commit...
/// ```
pub async fn begin_transaction(&self, timeout: Option<Duration>) -> OrbitResult<TransactionId> {
    // implementation
}

Testing

Types of Tests

  1. Unit Tests: Test individual functions and modules
  2. Integration Tests: Test component interactions
  3. Example Tests: Ensure examples compile and run
  4. Property Tests: Use proptest for property-based testing
  5. Benchmark Tests: Performance regression testing

Test Structure


#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::tempdir;
    
    #[tokio::test]
    async fn test_transaction_creation() {
        // Arrange
        let config = TransactionConfig::default();
        let coordinator = setup_test_coordinator(config).await;
        
        // Act
        let result = coordinator.begin_transaction(None).await;
        
        // Assert
        assert!(result.is_ok());
        let tx_id = result.unwrap();
        assert!(!tx_id.id.is_empty());
    }
    
    // Helper functions
    async fn setup_test_coordinator(config: TransactionConfig) -> TransactionCoordinator {
        // setup code
    }
}

Mocking and Test Utilities

Documentation

API Documentation

README and Guides

Performance Considerations

Transaction System Performance

Benchmarking


# Run benchmarks
cargo bench --package orbit-benchmarks

# Profile with perf (Linux)
cargo build --release
perf record --call-graph=dwarf target/release/your-binary
perf report

Submitting Changes

Pull Request Process

  1. Update documentation for any user-facing changes
  2. Add tests for new functionality
  3. Update CHANGELOG.md with your changes
  4. Ensure CI passes - all tests, linting, and formatting
  5. Request review from maintainers

Pull Request Template


## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature  
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Refactoring

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Added new tests for this change
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] CHANGELOG.md updated

Review Process

Getting Help

Recognition

Contributors will be recognized in:

Thank you for contributing to Orbit-RS!