Contributing to EQ Synapse

Thank you for your interest in contributing to EQ Synapse! This guide will help you get started with contributing to the project.

Getting Started

Development Environment Setup

1. Clone the repository:

   git clone https://github.com/energyquotient/syntropy.git
   cd syntropy
   

2. Build from source: See BUILDING.md for detailed build instructions

3. Run tests:

   cd server
   cargo test
   

Code Contribution Workflow

1. Branch Strategy

• main - Stable, production-ready code
• feature/* - New features
• fix/* - Bug fixes
• docs/* - Documentation updates

2. Making Changes

1. Create a feature branch:

   git checkout -b feature/your-feature-name
   

2. Make your changes following the coding standards below

3. Test your changes:

   cargo test
   cargo clippy -- -D warnings
   cargo fmt --check
   

4. Commit with clear messages:

   git commit -m "feat: add new feature description
   
   Detailed explanation of changes and why they were made.
   
   Co-Authored-By: Your Name <[email protected]>"
   

3. Commit Message Standards

Use conventional commit format:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Example:

feat: add harmonic analysis visualization

Implements real-time harmonic spectrum display using SciChart.
Updates API to expose harmonic data endpoints.

Fixes #123

4. Pull Request Process

1. Push your branch:

   git push origin feature/your-feature-name
   

2. Create a pull request on GitHub with:

   • Clear description of changes
   • Reference to related issues
   • Screenshots for UI changes
   • Test results

3. Code review: Address feedback from maintainers

4. Merge: Once approved, your PR will be merged

Coding Standards

Rust Code

• Follow Rust idioms: Use cargo clippy for linting
• Format code: Run cargo fmt before committing
• Error handling: Use Result and thiserror for error types
• Documentation: Add rustdoc comments for public APIs
• Safety: Document all unsafe blocks with // SAFETY: comments

Example:

#![allow(unused)]
fn main() {
/// Processes raw waveform data and extracts features.
///
/// # Arguments
/// * `data` - Raw ADC samples at 32 kHz
/// * `config` - Processing configuration
///
/// # Returns
/// Processed feature vector or error
///
/// # Errors
/// Returns `ProcessingError` if data is invalid or processing fails
pub fn process_waveform(
    data: &[i32],
    config: &Config,
) -> Result<Features, ProcessingError> {
    // Implementation
}
}

Python Code

• Follow PEP 8: Use black for formatting
• Type hints: Add type annotations for function signatures
• Documentation: Use docstrings for modules, classes, and functions

Documentation

• Update relevant docs: If you change behavior, update documentation
• Clear and concise: Write for both users and developers
• Examples: Provide code examples where helpful
• Keep up-to-date: Ensure docs match current code behavior

Testing Requirements

Unit Tests

• Coverage: Add tests for new functionality
• Edge cases: Test boundary conditions and error paths
• Fast: Unit tests should run quickly (<1s per test)

Integration Tests

• End-to-end: Test complete workflows
• Realistic data: Use representative test data
• Isolation: Tests should be independent

Performance Tests

• Critical paths: Benchmark performance-critical code
• Regression detection: Fail if performance degrades >10%

Architecture Guidelines

Rust Crate Organization

• eq-* - Core library crates (reusable components)
• synapse-* - Application binaries and services
• Separation of concerns: Keep business logic separate from I/O

Performance Considerations

• Real-time constraints: cpow-acquire and cpow-dual-sink have strict timing requirements
• Memory allocation: Minimize allocations in hot paths
• Lock-free when possible: Use atomic operations over mutexes for concurrent code

Security

• Input validation: Always validate external inputs
• No hardcoded secrets: Use environment variables or config files
• Least privilege: Run services with minimum required permissions

Code Review Checklist

Before submitting a PR, verify:

• Code compiles without warnings
• All tests pass
• New tests added for new functionality
• Documentation updated
• cargo clippy passes
• cargo fmt applied
• No TODO comments in production code
• Error handling is comprehensive
• Performance impact considered

Getting Help

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and discuss ideas
• Pull Requests: Propose code changes

Recognition

Contributors will be recognized in:

• Commit history (via Co-Authored-By)
• Release notes
• Project documentation

Thank you for contributing to EQ Synapse!