Contributing to modtector

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

Table of Contents

Getting Started
Development Setup
Contributing Guidelines
Code Style
Testing
Documentation
Submitting Changes
Issue Reporting

Getting Started

Prerequisites

Rust 1.70 or higher
Cargo (included with Rust)
Git
Basic knowledge of bioinformatics and RNA modifications

Fork and Clone

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/your-username/modtector.git
cd modtector

Add upstream remote:

git remote add upstream https://github.com/TongZhou2017/modtector.git

Development Setup

Install dependencies:
```
cargo build
```
Run tests:
```
cargo test
```
Check code style:
```
cargo fmt
cargo clippy
```

Contributing Guidelines

Types of Contributions

We welcome various types of contributions:

Bug fixes: Fix existing issues
New features: Add new functionality
Documentation: Improve documentation
Tests: Add or improve tests
Performance: Optimize existing code
Examples: Add usage examples

Contribution Process

Check existing issues: Look for existing issues or discussions
Create an issue: If no existing issue, create one to discuss
Fork and branch: Create a feature branch
Make changes: Implement your changes
Test: Ensure all tests pass
Document: Update documentation if needed
Submit PR: Create a pull request

Branch Naming

Use descriptive branch names:

fix/issue-123-description
feature/new-normalization-method
docs/update-user-guide
test/add-integration-tests

Code Style

Rust Style Guidelines

Follow Rust community standards:

Formatting: Use cargo fmt
Linting: Use cargo clippy
Naming: Use snake_case for variables and functions
Documentation: Document public functions and structs

Code Formatting

# Format code
cargo fmt

# Check formatting
cargo fmt -- --check

Linting

# Run clippy
cargo clippy

# Run clippy with all warnings
cargo clippy -- -W clippy::all

Documentation

Document all public functions and structs:

/// Calculate reactivity scores between modified and unmodified samples.
///
/// # Arguments
///
/// * `mod_data` - Modified sample data
/// * `unmod_data` - Unmodified sample data
/// * `method` - Reactivity calculation method
///
/// # Returns
///
/// * `Result<Vec<f64>, Error>` - Calculated reactivity scores
///
/// # Examples
///
/// ```
/// let reactivity = calculate_reactivity(mod_data, unmod_data, "current")?;
/// ```
pub fn calculate_reactivity(
    mod_data: &[f64],
    unmod_data: &[f64],
    method: &str,
) -> Result<Vec<f64>, Box<dyn Error>> {
    // Implementation
}

Testing

Test Structure

Organize tests by module:

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

    #[test]
    fn test_calculate_reactivity() {
        // Test implementation
    }

    #[test]
    fn test_normalize_signals() {
        // Test implementation
    }
}

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_calculate_reactivity

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

# Run integration tests
cargo test --test integration_tests

Test Data

Use small, representative test data:

#[test]
fn test_pileup_analysis() {
    let test_bam = "tests/data/sample.bam";
    let test_fasta = "tests/data/reference.fa";
    
    // Test implementation
}

Integration Tests

Create integration tests in tests/ directory:

// tests/integration_tests.rs
use modtector;

#[test]
fn test_full_workflow() {
    // Test complete workflow
}

Documentation

Code Documentation

Document all public APIs:

/// Normalize signals using specified method.
///
/// # Arguments
///
/// * `signals` - Input signal data
/// * `method` - Normalization method
///
/// # Returns
///
/// * `Result<Vec<f64>, Error>` - Normalized signals
pub fn normalize_signals(signals: &[f64], method: &str) -> Result<Vec<f64>, Box<dyn Error>> {
    // Implementation
}

User Documentation

Update user-facing documentation:

README.md: Update main documentation
docs/: Update user guides and examples
CHANGELOG.md: Document changes
API documentation: Update API docs

Documentation Standards

Use clear, concise language
Provide examples where helpful
Include error conditions
Document parameter ranges and defaults

Submitting Changes

Pull Request Process

Create feature branch:
```
git checkout -b feature/new-feature
```
Make changes:
- Implement your changes
- Add tests
- Update documentation

Commit changes:

git add .
git commit -m "Add new normalization method"

Push to fork:
```
git push origin feature/new-feature
```
Create pull request:
- Go to GitHub
- Click “New Pull Request”
- Fill out the template

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Test addition

## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Documentation
- [ ] Code documented
- [ ] User documentation updated
- [ ] API documentation updated

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] No breaking changes
- [ ] Backward compatibility maintained

Review Process

Automated checks: CI/CD pipeline runs
Code review: Maintainers review code
Testing: Verify functionality
Documentation: Check documentation updates
Approval: Maintainer approves
Merge: Changes merged to main branch

Issue Reporting

Bug Reports

When reporting bugs, include:

Environment:
- Operating system
- Rust version
- modtector version
Reproduction steps:
- Exact command used
- Input data description
- Expected vs actual behavior
Error messages:
- Full error output
- Log files
- Stack traces
Additional context:
- Related issues
- Workarounds tried
- Impact assessment

Feature Requests

When requesting features, include:

Use case: Why is this feature needed?
Proposed solution: How should it work?
Alternatives: What alternatives were considered?
Implementation: Any implementation ideas?

Issue Template

## Bug Report / Feature Request

### Description
Brief description of the issue or feature request

### Environment
- OS: [e.g., Ubuntu 20.04]
- Rust version: [e.g., 1.70.0]
- modtector version: [e.g., v0.9.2]

### Steps to Reproduce (for bugs)
1. Step 1
2. Step 2
3. Step 3

### Expected Behavior
What you expected to happen

### Actual Behavior
What actually happened

### Additional Context
Any other relevant information

Development Workflow

Daily Workflow

Sync with upstream:

git fetch upstream
git checkout main
git merge upstream/main

Create feature branch:
```
git checkout -b feature/your-feature
```
Make changes:
- Write code
- Add tests
- Update documentation
Test changes:
```
cargo test
cargo clippy
cargo fmt
```

Commit and push:

git add .
git commit -m "Descriptive commit message"
git push origin feature/your-feature

Release Process

Version bump: Update version in Cargo.toml
Changelog: Update CHANGELOG.md
Tag release: Create git tag
Build release: Create release build
Publish: Publish to crates.io (if applicable)

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

Expected Behavior

Be respectful and inclusive
Accept constructive criticism
Focus on what’s best for the community
Show empathy towards others

Unacceptable Behavior

Harassment or discrimination
Trolling or inflammatory comments
Personal attacks
Inappropriate language or imagery

Enforcement

Violations will be addressed by project maintainers and may result in:

Warning
Temporary ban
Permanent ban

Getting Help

Communication Channels

GitHub Issues: For bugs and feature requests
GitHub Discussions: For questions and discussions
Email: For sensitive issues
Documentation: Check existing docs first

Mentorship

New contributors can:

Ask for help in GitHub Discussions
Request code review
Ask for guidance on implementation
Seek clarification on requirements

Resources

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation
Community acknowledgments

Thank you for contributing to modtector! Your contributions help make RNA modification detection more accessible and reliable for the scientific community.