Skip to content

Latest commit

 

History

History
363 lines (276 loc) · 10.6 KB

CONTRIBUTING.md

File metadata and controls

363 lines (276 loc) · 10.6 KB

Contributing to rust-ibapi

Thank you for your interest in contributing! This guide will help you get started.

Important: Feature Flags

rust-ibapi enables the asynchronous client by default.

  • Default build (cargo build) uses the async client, available as client::Client.
  • Sync-only: cargo build --no-default-features --features sync keeps the blocking client on client::Client.
  • Combined: cargo build --no-default-features --features "sync async" exposes the async client on client::Client and the blocking API under client::blocking::Client.

Run commands for every configuration that your change touches (default async, sync-only, and combined when applicable).

Quick Start

  1. Fork the repository on GitHub
  2. Clone your fork: git clone https://github.com/<your-username>/rust-ibapi
  3. Test your setup:
    cargo test                          # default async client
    cargo test --no-default-features --features sync
    cargo test --all-features           # async + blocking
  4. Make your changes
  5. Verify all modes work:
    cargo test
    cargo test --no-default-features --features sync
    cargo test --all-features
    cargo clippy --all-targets
    cargo clippy --all-targets --no-default-features --features sync
    cargo clippy --all-targets --all-features
    cargo fmt
  6. Submit a pull request

Contribution Flow

graph TD
    Fork[1. Fork Repository<br/>on GitHub]
    Clone[2. Clone Your Fork]
    Branch[3. Create Feature Branch]
    Code[4. Make Changes]
    TestAsync[5a. Test Async<br/>cargo test]
    TestSync[5b. Test Sync-only<br/>cargo test --no-default-features --features sync]
    Clippy[6. Run Clippy<br/>Both modes]
    Format[7. Format Code<br/>cargo fmt]
    Commit[8. Commit Changes]
    Push[9. Push to Fork]
    PR[10. Create Pull Request]
    CI[11. CI Checks Pass]
    Review[12. Code Review]
    Merge[13. Merge!]
    
    Fork --> Clone
    Clone --> Branch
    Branch --> Code
    Code --> TestAsync
    Code --> TestSync
    TestAsync --> Clippy
    TestSync --> Clippy
    Clippy --> Format
    Format --> Commit
    Commit --> Push
    Push --> PR
    PR --> CI
    CI --> Review
    Review --> Merge
    
    style Fork fill:#e3f2fd
    style Merge fill:#c8e6c9
    style TestAsync fill:#fff9c4
    style TestSync fill:#fff9c4
Loading

Branches

Branch Purpose
main Active development (next major release)
v2-stable Maintenance branch for v2.x releases
v1-stable Maintenance branch for v1.x releases

Bug fixes and security patches for older releases should target the appropriate stable branch.

Table of Contents

Development Setup

Prerequisites

  1. Install Rust
  2. Install development tools:
    cargo install cargo-llvm-cov   # For code coverage
    cargo install cargo-audit       # For security audits
  3. Fork and clone the repository
  4. Verify your environment works with both features:
    # Test async (the default)
    cargo test
    
    # Test sync-only
    cargo test --no-default-features --features sync

Recommended IDE Setup

  • VS Code with rust-analyzer extension
  • Configure rustfmt and clippy for automatic formatting and linting

Making Changes

Basic Workflow

  1. Create a feature branch:

    git checkout -b feature/your-feature-name
  2. Make your changes following our code style guidelines

  3. Test every feature mode:

    cargo test
    cargo test --no-default-features --features sync
    cargo test --all-features
  4. Run quality checks:

    cargo fmt
    cargo clippy --all-targets -- -D warnings
    cargo clippy --all-targets --no-default-features --features sync -- -D warnings
    cargo clippy --all-targets --all-features -- -D warnings

Common Tasks

  • Adding a new API method: See Extending the API
  • Fixing a bug: Include a test that reproduces the issue
  • Improving documentation: Update both code docs and markdown files
  • Adding examples: Create both sync and async versions in examples/

Testing

Running Tests

Always test every feature mode:

# Run all tests, one leg per feature configuration
cargo test
cargo test --no-default-features --features sync
cargo test --all-features

# Run specific test
cargo test test_name
cargo test test_name --no-default-features --features sync

# Run with output
cargo test --no-default-features --features sync -- --nocapture

# Generate coverage report (covers sync + async in one run)
cargo llvm-cov --all-features --html --open

Writing Tests

  • Use table-driven tests for comprehensive coverage
  • Share test data between sync/async implementations
  • Test error cases and edge conditions
  • See Testing Patterns for detailed guidelines

Integration Testing

The project uses a MockGateway for integration tests:

  • Tests real TCP connections
  • Verifies protocol correctness
  • Ensures sync/async parity

Code Style

Key Guidelines

  • Follow Rust API Guidelines
  • Use cargo fmt before committing
  • Address all cargo clippy warnings
  • Keep comments concise and meaningful
  • Avoid stating the obvious in comments

Feature-Specific Code

The sync and async features can be enabled independently or together. Use explicit guards so intent is clear:

// For sync-capable code (applies in both sync-only and combined builds)
#[cfg(feature = "sync")]
use std::thread;

// For async-only code
#[cfg(feature = "async")]
use tokio::task;

// For code that should compile only when sync is enabled without async
#[cfg(all(feature = "sync", not(feature = "async")))]
fn sync_only_behavior() { /* ... */ }

See Code Style Guidelines for more details.

Submitting Pull Requests

Before Submitting

  1. Test every mode you touched - default async, sync-only, and combined (--all-features) when relevant
  2. Run quality checks - one clippy leg per feature configuration, matching CI:
    cargo fmt --check
    cargo clippy --all-targets -- -D warnings
    cargo clippy --all-targets --no-default-features --features sync -- -D warnings
    cargo clippy --all-targets --all-features -- -D warnings
  3. Update documentation if needed
  4. Add tests for new functionality
  5. Check coverage hasn't decreased significantly

Pull Request Process

  1. Push your branch to your fork
  2. Create a pull request against the main branch
  3. Fill out the PR template with:
    • Description of changes
    • Testing performed
    • Any breaking changes
  4. Wait for CI checks to pass
  5. Address review feedback
  6. Once approved, your PR will be merged

Commit Messages

  • Use clear, descriptive commit messages
  • Start with a verb (Add, Fix, Update, Remove)
  • Reference issues when applicable: "Fix #123: Description"

Documentation

Types of Documentation

  1. Code Documentation - Rust doc comments (/// and //!)
  2. Examples - Working code in examples/ directory
  3. Guides - Markdown files in docs/ directory
  4. API Reference - Generated from doc comments

Documentation Standards

  • Keep explanations clear and concise
  • Include examples for complex functionality
  • Update relevant docs when changing behavior
  • Test all code examples

Key Documentation Files

Advanced Topics

For more complex contributions, see these guides:

Domain Type Pattern

The codebase uses newtype wrappers for type safety:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct AccountId(pub String);

impl Deref for AccountId {
    type Target = str;
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl From<String> for AccountId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

This pattern provides:

  • Type safety (can't mix different ID types)
  • Self-documenting code
  • Zero runtime overhead
  • Better IDE support

Troubleshooting

Environment Variables

# Enable debug logging
RUST_LOG=debug cargo run --no-default-features --features sync --example example_name

# Record TWS messages for debugging
IBAPI_RECORDING_DIR=/tmp/tws-messages cargo run --no-default-features --features sync --example example_name

Common Issues

  • "You must enable at least one of the 'sync' or 'async' features" - --no-default-features drops the async client; add --features sync or --features async after it
  • "mutually exclusive features" - Update to the latest main; older commits required choosing only one feature
  • Tests failing - Ensure you're running the suite for every relevant feature combination
  • Clippy warnings - Run clippy for default, sync-only, and --all-features

For detailed solutions, see the Troubleshooting Guide.

Getting Help

  • Check existing issues
  • Ask questions in discussions
  • Review the documentation
  • Look at existing examples in examples/

Creating Releases

For maintainers creating new releases:

  1. Bump PR: Cargo.toml version, date the [Unreleased] section of CHANGELOG.md, update install snippets in README.md and docs/
  2. Squash-merge once CI is green
  3. Annotated tag on the squash commit: git tag -a vX.Y.Z <sha> -m "Release X.Y.Z", push it
  4. Publish the GitHub release
  5. Publish to crates.io with cargo publish

The full procedure, including the changelog audit and release-notes format, is the /release Claude Code skill in .claude/skills/release.

Thank you for contributing to rust-ibapi!