caldavpuller/CONTRIBUTING.md

Contributing to CalDAV Calendar Synchronizer

Thank you for your interest in contributing to the CalDAV Calendar Synchronizer! This document provides guidelines and information for contributors.

Getting Started

Prerequisites

• Rust 1.70 or newer
• Git
• Basic familiarity with CalDAV protocol
• Understanding of async/await in Rust

Development Setup

1. Fork and Clone

   # Fork the repository on your Forgejo instance
   git clone ssh://git@gitea.soliverez.com.ar/YOUR_USERNAME/caldavpuller.git
   cd caldavpuller
   
   # Add upstream remote
   git remote add upstream ssh://git@gitea.soliverez.com.ar/alvaro/caldavpuller.git
   

2. Install Development Tools

   # Install Rust toolchain
   rustup update stable
   rustup component add rustfmt clippy rust-analyzer
   
   # Verify installation
   cargo --version
   rustfmt --version
   clippy --version
   

3. Build and Test

   # Build the project
   cargo build
   
   # Run tests
   cargo test
   
   # Check formatting
   cargo fmt --check
   
   # Run linter
   cargo clippy -- -D warnings
   

Development Workflow

1. Create a Branch

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-fix-name

2. Make Changes

• Follow the existing code style
• Add tests for new functionality
• Update documentation as needed
• Ensure all tests pass

3. Commit Changes

Use clear, descriptive commit messages:

# Good commit message
git commit -m "feat: Add support for calendar color filtering

- Add color field to CalendarInfo struct
- Implement color-based filtering in CalendarFilter
- Add configuration option for color preferences
- Add unit tests for color filtering logic"

# Another good example
git commit -m "fix: Handle timezone parsing errors gracefully

- Add proper error handling for unknown timezone identifiers
- Return meaningful error messages to users
- Add integration tests for timezone edge cases"

4. Submit Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on Forgejo
# Provide clear description of changes and testing done

Code Style and Standards

1. Formatting

Use rustfmt with default settings:

cargo fmt

2. Linting

All code must pass clippy without warnings:

cargo clippy -- -D warnings

3. Documentation

• Document all public APIs with /// comments
• Include examples for complex functionality
• Update README and other documentation as needed

/// Filters calendars based on user-defined criteria.
///
/// # Examples
///
/// ```
/// use caldav_sync::CalendarFilter;
///
/// let filter = CalendarFilter::new()
///     .with_selected_calendars(vec!["Work".to_string()]);
/// 
/// assert!(filter.should_import_calendar("Work"));
/// assert!(!filter.should_import_calendar("Personal"));
/// ```
pub struct CalendarFilter {
    // ...
}

4. Error Handling

• Use Result<T, CalDavError> for fallible operations
• Provide meaningful error context
• Handle errors gracefully at the UI layer

pub async fn sync_calendars(&mut self) -> CalDavResult<SyncStats> {
    let calendars = self.discover_calendars().await
        .context("Failed to discover calendars")?;
    
    // ... rest of implementation
}

5. Testing

Write comprehensive tests:

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

    #[tokio::test]
    async fn test_calendar_filtering() {
        let filter = CalendarFilter::new()
            .with_selected_calendars(vec!["Work".to_string()]);
        
        assert!(filter.should_import_calendar("Work"));
        assert!(!filter.should_import_calendar("Personal"));
    }
}

Testing

1. Unit Tests

Test individual components in isolation:

cargo test --lib

2. Integration Tests

Test component interactions:

cargo test --test integration_tests

3. Manual Testing

Test with real CalDAV servers:

# Build and run with debug logging
cargo build
./target/debug/caldav-sync --debug --list-events

4. Test Coverage

Aim for high test coverage, especially for:

• Configuration parsing
• Error handling paths
• Calendar filtering logic
• Timezone conversions

Types of Contributions

1. Bug Fixes

• Check existing issues for bug reports
• Create minimal reproduction case
• Add tests that fail before the fix
• Fix the issue and ensure tests pass

2. New Features

• Open issue for discussion first
• Design the feature interface
• Implement with tests
• Update documentation

3. Documentation

• Improve README and guides
• Add code examples
• Fix typos and clarity issues
• Translate documentation if possible

4. Performance Improvements

• Profile existing code
• Identify bottlenecks
• Implement optimizations
• Add benchmarks for verification

Areas Needing Help

1. Enhanced CalDAV Support

• Better support for CalDAV extensions
• Handling of recurring events
• Support for attachments and attendees

2. User Experience

• Interactive configuration wizard
• Progress indicators for long operations
• Better error messages and recovery

3. Testing Infrastructure

• Mock CalDAV server for testing
• Automated testing in CI/CD
• Performance benchmarks

4. Documentation

• User guides for different platforms
• API documentation
• Troubleshooting guides

Code Review Process

1. Self-Review

Before submitting, review your own changes:

• Code follows project style
• Tests are comprehensive
• Documentation is updated
• No debug code or TODOs left

2. Review Criteria

Maintainers will review for:

• Correctness and safety
• Performance implications
• User experience impact
• Code maintainability

3. Feedback

Be prepared to:

• Answer questions about your changes
• Make requested modifications
• Discuss alternative approaches
• Update tests based on feedback

Release Process

1. Version Management

• Follow semantic versioning (MAJOR.MINOR.PATCH)
• Update version in Cargo.toml
• Create git tag for releases

2. Changelog

Maintain CHANGELOG.md with:

• New features
• Bug fixes
• Breaking changes
• Migration notes

3. Release Checklist

• All tests pass
• Documentation updated
• Version numbers updated
• Changelog updated
• Release tag created
• Release artifacts built

Support and Communication

1. Issues and Questions

• Use GitHub issues for bug reports and feature requests
• Check existing issues before creating new ones
• Provide clear, reproducible examples

2. Discussions

• Use discussions for general questions
• Share ideas and suggestions
• Ask for help with development

3. Code of Conduct

Be respectful and constructive:

• Welcome newcomers and help them learn
• Assume good faith in interactions
• Focus on what is best for the community
• Show empathy towards other community members

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• Git commit history
• Project documentation

Thank you for contributing to the CalDAV Calendar Synchronizer! Your contributions help make this project better for everyone.