foxhunt/DEVELOPMENT.md

Development Guide

Overview

This guide provides essential information for developing the Foxhunt HFT Trading System. Follow these practices to maintain code quality and system reliability.

Git Hooks

This project uses automated git hooks to maintain code quality and prevent regressions.

Pre-Commit Hook

Location: .git/hooks/pre-commit

Purpose: Prevents commits that would degrade code quality

Checks Performed:

1. Compilation Verification - Blocks commits with compilation errors
2. Warning Count Threshold - Blocks commits if warnings exceed 50
3. Code Quality Checks - Warns about common issues:
   • .unwrap() usage (suggests using ? operator)
   • .expect() with empty messages
   • TODO/FIXME comment counts

Example Output:

🔍 Running pre-commit quality checks...

📋 Checking compilation...
✅ Compilation check passed

📊 Checking warning count...
✅ Warning count acceptable (43/50)

🔎 Checking for common issues...
✅ All pre-commit checks passed!

Bypassing (Emergency Only):

git commit --no-verify

Warning: Only use this for genuine emergencies. Bypassing the hook can introduce technical debt.

Pre-Push Hook

Location: .git/hooks/pre-push

Purpose: Ensures code changes are properly tested before pushing

Checks Performed:

1. Test Suite Execution - Runs workspace tests (excluding integration tests)
2. Compilation Verification - For main/master branch pushes
3. Uncommitted Changes Detection - Warns about uncommitted files

Example Output:

🔍 Running pre-push checks...

📌 Pushing to main - running full quality checks

📋 Verifying compilation...
✅ Compilation verified

🧪 Running test suite...
   (Skipping integration tests: redis, kill_switch)

✅ All tests passed!

Bypassing (Emergency Only):

git push --no-verify

Code Quality Standards

Warning Management

Current Status: 302 warnings (target: <50)

Priority Warning Types:

1. unused_imports - Clean up unused imports immediately
2. missing_debug_implementations - Add #[derive(Debug)] where possible
3. non_snake_case - Rename fields to follow Rust naming conventions
4. missing_docs - Add documentation for public items

Quick Fix Commands:

# Check specific warning types
cargo clippy --workspace -- -W unused-imports

# Auto-fix some warnings
cargo fix --workspace --allow-dirty

# Check warning count
cargo check --workspace 2>&1 | grep "warning:" | wc -l

Best Practices

1. Error Handling

   • ❌ Avoid: .unwrap() and .expect("")
   • ✅ Use: ? operator, proper error types, descriptive error messages

2. Code Documentation

   • Add doc comments for public functions, structs, and modules
   • Include examples in doc comments for complex functionality

3. Testing

   • Write unit tests for new functionality
   • Update integration tests when changing service interfaces
   • Run tests before pushing: cargo test --workspace --lib

4. Performance Considerations

   • This is an HFT system - every nanosecond matters
   • Profile changes that affect hot paths
   • Use #[inline] judiciously for critical functions

Development Workflow

Standard Workflow

1. Create Feature Branch

   git checkout -b feature/my-feature
   

2. Make Changes

   • Write code
   • Add tests
   • Update documentation

3. Check Quality

   # Check compilation and warnings
   cargo check --workspace
   
   # Run tests
   cargo test --workspace --lib
   
   # Format code
   cargo fmt --all
   

4. Commit Changes

   git add .
   git commit -m "feat: add new feature"
   # Pre-commit hook runs automatically
   

5. Push to Remote

   git push origin feature/my-feature
   # Pre-push hook runs automatically
   

Fixing Warning Regressions

If your commit is blocked due to warnings:

# See all warnings
cargo check --workspace 2>&1 | grep "warning:"

# Count warnings by type
cargo check --workspace 2>&1 | grep "warning:" | sort | uniq -c | sort -rn

# Fix a specific file
cargo fix --bin trading-service --allow-dirty

Hook Maintenance

If you need to update the hooks:

# Edit hooks
vim .git/hooks/pre-commit
vim .git/hooks/pre-push

# Make executable (if needed)
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push

# Test hooks
.git/hooks/pre-commit
.git/hooks/pre-push

Warning Threshold Policy

Current Threshold: 50 warnings Current Count: 302 warnings

Goal: Reduce warnings to under threshold through incremental improvements.

Strategy:

1. Wave 19 (Current): Set up enforcement infrastructure (hooks)
2. Wave 20: Fix unused imports and missing Debug implementations
3. Wave 21: Address non_snake_case and missing documentation
4. Wave 22: Final cleanup and threshold reduction to 25

Monitoring:

# Quick warning count
make check-warnings  # If you add this to Makefile

# Or directly
cargo check --workspace 2>&1 | grep "warning:" | wc -l

Continuous Integration

When CI is set up, these same checks will run automatically:

• Compilation verification
• Warning count threshold
• Test suite execution
• Code formatting checks
• Security audits

Getting Help

• Architecture Questions: See CLAUDE.md for system design
• Configuration: See config/ crate and PostgreSQL schemas
• Testing: See tests/ directory for examples
• Performance: See docs/performance.md (if exists)

Emergency Procedures

If you absolutely must bypass the hooks:

1. Understand the Risk: You're introducing technical debt
2. Document Why: Add a TODO comment explaining the bypass
3. Create a Ticket: Track the issue for future resolution
4. Use --no-verify Sparingly:

   git commit --no-verify -m "emergency: fix production issue"
   

Version History

• 2025-10-01: Initial development guide with git hooks
• 2025-09-27: Project reached compilation success milestone
• Earlier: Extensive ML models and service architecture implemented

---

Remember: These hooks exist to prevent regressions and maintain code quality. They're your friends, not obstacles.