Thank you for your interest in contributing! This guide will help you get started.
rust-ibapi enables the asynchronous client by default.
- Default build (
cargo build) uses the async client, available asclient::Client. - Sync-only:
cargo build --no-default-features --features synckeeps the blocking client onclient::Client. - Combined:
cargo build --no-default-features --features "sync async"exposes the async client onclient::Clientand the blocking API underclient::blocking::Client.
Run commands for every configuration that your change touches (default async, sync-only, and combined when applicable).
- Fork the repository on GitHub
- Clone your fork:
git clone https://github.com/<your-username>/rust-ibapi - Test your setup:
cargo test # default async client cargo test --no-default-features --features sync cargo test --all-features # async + blocking
- Make your changes
- 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
- Submit a pull request
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
| 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.
- Branches
- Development Setup
- Making Changes
- Testing
- Code Style
- Submitting Pull Requests
- Documentation
- Advanced Topics
- Install Rust
- Install development tools:
cargo install cargo-llvm-cov # For code coverage cargo install cargo-audit # For security audits
- Fork and clone the repository
- Verify your environment works with both features:
# Test async (the default) cargo test # Test sync-only cargo test --no-default-features --features sync
- VS Code with rust-analyzer extension
- Configure rustfmt and clippy for automatic formatting and linting
-
Create a feature branch:
git checkout -b feature/your-feature-name
-
Make your changes following our code style guidelines
-
Test every feature mode:
cargo test cargo test --no-default-features --features sync cargo test --all-features
-
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
- 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/
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- 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
The project uses a MockGateway for integration tests:
- Tests real TCP connections
- Verifies protocol correctness
- Ensures sync/async parity
- Follow Rust API Guidelines
- Use
cargo fmtbefore committing - Address all
cargo clippywarnings - Keep comments concise and meaningful
- Avoid stating the obvious in comments
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.
- Test every mode you touched - default async, sync-only, and combined (
--all-features) when relevant - 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
- Update documentation if needed
- Add tests for new functionality
- Check coverage hasn't decreased significantly
- Push your branch to your fork
- Create a pull request against the
mainbranch - Fill out the PR template with:
- Description of changes
- Testing performed
- Any breaking changes
- Wait for CI checks to pass
- Address review feedback
- Once approved, your PR will be merged
- Use clear, descriptive commit messages
- Start with a verb (Add, Fix, Update, Remove)
- Reference issues when applicable: "Fix #123: Description"
- Code Documentation - Rust doc comments (
///and//!) - Examples - Working code in
examples/directory - Guides - Markdown files in
docs/directory - API Reference - Generated from doc comments
- Keep explanations clear and concise
- Include examples for complex functionality
- Update relevant docs when changing behavior
- Test all code examples
- Quick Start Guide - Get started quickly with rust-ibapi
- Architecture Overview - System design and components
- API Patterns - Common usage patterns
- Feature Flags - Detailed feature flag guide
- Examples Guide - How to run and write examples
For more complex contributions, see these guides:
- Extending the API - Adding new TWS API functionality
- Architecture Details - Deep dive into system design
- Testing Patterns - Advanced testing techniques
- Build and Test - CI/CD and build configuration
- Troubleshooting - Common issues and solutions
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
# 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- "You must enable at least one of the 'sync' or 'async' features" -
--no-default-featuresdrops the async client; add--features syncor--features asyncafter 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.
- Check existing issues
- Ask questions in discussions
- Review the documentation
- Look at existing examples in
examples/
For maintainers creating new releases:
- Bump PR:
Cargo.tomlversion, date the[Unreleased]section ofCHANGELOG.md, update install snippets inREADME.mdanddocs/ - Squash-merge once CI is green
- Annotated tag on the squash commit:
git tag -a vX.Y.Z <sha> -m "Release X.Y.Z", push it - Publish the GitHub release
- 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!