Contributing to FileSyncHub

Thank you for your interest in contributing to FileSyncHub! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Code of Conduct

We follow the Rust Code of Conduct. Please read it before contributing.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/your-username/FileSyncHub.git
cd FileSyncHub
  3. Add the upstream remote: 
    git remote add upstream https://github.com/original-owner/FileSyncHub.git

Development Setup

Prerequisites

Setting Up the Development Environment

  1. Install development dependencies: 
    cargo install cargo-watch cargo-audit cargo-tarpaulin
  2. Set up pre-commit hooks: 
    cp hooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit
  3. Create test credentials: 
    mkdir -p credentials
cp examples/credentials/* credentials/

Making Contributions

Branch Naming Convention

Commit Messages

Follow the Conventional Commits specification:

type(scope): description

[optional body]

[optional footer]

Types:

Code Style

We follow the Rust standard style guide with some additional rules:

General Guidelines

Specific Rules

  1. Error Handling: 
    // Good
let result = operation().context("Failed to perform operation")?;

// Avoid
let result = operation().unwrap();
  2. Async/Await: 
    // Good
async fn process_file(path: &Path) -> Result<()> {
    let data = read_file(path).await?;
    process_data(data).await
}
  3. Error Types: 
    // Good
#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
}

Testing

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with coverage
cargo tarpaulin

Writing Tests

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

    #[tokio::test]
    async fn test_file_upload() -> Result<()> {
        // Arrange
        let client = create_test_client().await?;
        let test_file = create_temp_file()?;

        // Act
        let result = client.upload_file(&test_file).await;

        // Assert
        assert!(result.is_ok());
        Ok(())
    }
}

Documentation

Code Documentation

Example:

/// Uploads a file to the cloud storage.
///
/// # Arguments
///
/// * `path` - Path to the file to upload
/// * `chunk_size` - Size of each chunk in bytes
///
/// # Examples
///
/// ```
/// # use filesynchub::upload_file;
/// # async fn example() -> Result<()> {
/// let result = upload_file("path/to/file", 1024).await?;
/// # Ok(())
/// # }
/// ```
pub async fn upload_file(path: &Path, chunk_size: usize) -> Result<()> {
    // Implementation
}

User Documentation

Pull Request Process

  1. Update documentation
  2. Add tests for new features
  3. Ensure CI passes
  4. Update CHANGELOG.md
  5. Request review
  6. Address feedback

PR Template

## Description
Brief description of changes

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

## Testing
Describe how you tested the changes

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Formatting checked

Additional Resources