ccxt-rust 0.1.3

# Contributing to ccxt-rust

Thank you for your interest in contributing to ccxt-rust! This guide will help you get started.

## Table of Contents

- [How to Contribute](#how-to-contribute)
- [Development Setup](#development-setup)
- [Code Style](#code-style)
- [Commit Messages](#commit-messages)
- [Pull Request Process](#pull-request-process)
- [Testing Requirements](#testing-requirements)

## How to Contribute

We welcome contributions in the following areas:

- **Bug fixes** - Help us squash bugs!
- **New features** - Exchange implementations, API endpoints
- **Documentation** - Improve guides, fix typos, add examples
- **Tests** - Increase test coverage
- **Performance** - Optimize critical paths
- **Code quality** - Refactoring, better error handling

### Finding Good First Issues

Look for issues labeled:
- `good first issue` - Suitable for newcomers
- `help wanted` - Community contributions welcome
- `documentation` - Documentation improvements

## Development Setup

### Prerequisites

- Rust 1.91+ (`rustc --version`)
- Cargo (comes with Rust)
- Git

### Fork and Clone

```bash
# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/ccxt-rust.git
cd ccxt-rust

# Add upstream remote
git remote add upstream https://github.com/Praying/ccxt-rust.git
```

### Build and Test

```bash
# Build all packages
cargo build --workspace

# Run tests
cargo test --workspace

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

# Format code
cargo fmt --all

# Run linter
cargo clippy --all-targets --all-features
```

### Development Workflow

1. **Sync with upstream**
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```

2. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **Make your changes**
   - Write code following our style guidelines
   - Add tests for new functionality
   - Update documentation

4. **Commit your changes**
   ```bash
   git add .
   git commit -m "feat: add your feature description"
   ```

5. **Push to your fork**
   ```bash
   git push origin feature/your-feature-name
   ```

6. **Create Pull Request**
   - Go to the original repository on GitHub
   - Click "New Pull Request"
   - Fill in the PR template

## Code Style

### Rust Edition

This project uses **Rust 2021** edition.

### Formatting

- Use `cargo fmt` for automatic formatting
- Maximum line width: 100 characters
- Use 4 spaces for indentation

### Naming Conventions

- **Structs/Enums**: `PascalCase` (e.g., `ExchangeConfig`, `OrderType`)
- **Functions/Methods**: `snake_case` (e.g., `fetch_ticker`, `create_order`)
- **Constants**: `SCREAMING_SNAKE_CASE` (e.g., `MAX_RETRY_ATTEMPTS`)
- **Acronyms**: Keep uppercase in names (e.g., `API`, `OHLCV`, not `Api`, `Ohlcv`)

### Documentation

All public items must have documentation:

```rust
/// Brief one-line summary.
///
/// More detailed explanation...
///
/// # Examples
///
/// ```
/// use ccxt_core::Exchange;
///
/// let ticker = exchange.fetch_ticker("BTC/USDT").await?;
/// ```
pub async fn fetch_ticker(&self, symbol: &str) -> Result<Ticker> {
    // ...
}
```

### Error Handling

- Use `thiserror` for custom error types
- Use `anyhow::Result` for application errors
- Never use `.unwrap()` on recoverable paths
- Provide context for errors:

```rust
use ccxt_core::error::ContextExt;

some_operation()
    .context("Failed to fetch ticker")?;
```

### Linting

We enforce strict linting:

```bash
# This will fail if there are warnings
cargo clippy --all-targets --all-features -- -D warnings
```

Common clippy warnings to avoid:
- `unwrap_used` - Use proper error handling
- `expect_used` - Use proper error handling
- `panic` - Use Result instead
- `todo!` - Implement or leave a note

## Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/) specification:

### Format

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

[optional body]

[optional footer(s)]
```

### Types

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

### Examples

```bash
feat(exchange): add support for OCO orders

fix(binance): correct timestamp parsing for trades

docs(readme): update installation instructions

refactor(http): simplify retry logic

test(trades): add integration tests for fetch_my_trades
```

### Branch Naming

- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation
- `refactor/` - Refactoring
- `test/` - Test additions

Example: `feature/binance-oco-orders`, `fix/timestamp-parsing`

## Pull Request Process

### Before Submitting

1. **Check existing PRs** - Avoid duplicate work
2. **Update documentation** - Include docs for new features
3. **Add tests** - Maintain test coverage
4. **Run linter** - `cargo clippy` must pass
5. **Format code** - `cargo fmt`
6. **Update CHANGELOG.md** - Add entry to "Unreleased" section

### PR Title

Use the same format as commit messages:

```
feat(exchange): add support for OCO orders
fix(binance): correct timestamp parsing
docs(readme): update installation instructions
```

### PR Description

Include:
- **Why**: What problem does this solve?
- **What**: What changes were made?
- **How**: How was it implemented?
- **Testing**: How was it tested?
- **Breaking changes**: List any breaking changes

### PR Checklist

- [ ] Tests pass (`cargo test`)
- [ ] Clippy passes (`cargo clippy -- -D warnings`)
- [ ] Code is formatted (`cargo fmt`)
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Commits follow conventional format

## Testing Requirements

### Unit Tests

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

    #[test]
    fn test_parse_symbol() {
        let symbol = parse_symbol("BTC/USDT").unwrap();
        assert_eq!(symbol.base, "BTC");
        assert_eq!(symbol.quote, "USDT");
    }
}
```

### Integration Tests

Integration tests require credentials. They are disabled by default:

```bash
# Enable integration tests
ENABLE_INTEGRATION_TESTS=true cargo test --test binance_integration_test
```

### Test Coverage

- Aim for 80%+ coverage on new code
- Add tests for bug fixes (regression tests)
- Include edge cases in tests

### Running Tests

```bash
# All tests
cargo test

# Specific package
cargo test -p ccxt-core

# Specific test
cargo test test_parse_symbol

# With output
cargo test -- --nocapture

# Run examples as tests
cargo test --examples
```

## Development Workflow

### Making Changes

1. **Check out the main branch** and ensure it's up to date
   ```bash
   git checkout main
   git pull upstream main
   ```

2. **Create a feature branch** from main
   ```bash
   git checkout -b feature/your-feature
   ```

3. **Implement your changes** with tests
   ```bash
   # Edit files, add tests
   cargo test
   ```

4. **Commit frequently** with meaningful messages
   ```bash
   git add .
   git commit -m "feat: add new feature"
   ```

5. **Sync and rebase** before pushing
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```

6. **Push to your fork**
   ```bash
   git push origin feature/your-feature
   ```

7. **Create Pull Request** on GitHub

### Review Process

- At least one maintainer must approve your PR
- All CI checks must pass
- Address review feedback promptly
- Keep commits clean (squash/rebase as needed)

### After Merge

- **Delete your feature branch** after merge
- **Sync your fork** with upstream
  ```bash
  git checkout main
  git pull upstream main
  git push origin main
  ```

## Questions?

- Open a GitHub Discussion for general questions
- Open an Issue for bugs or feature requests
- Join our community chat (if available)

---

Thank you for contributing to ccxt-rust! 🚀