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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # 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**

```bash
# 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:

```bash
# 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**

```bash
# 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:

```bash
cargo fmt
```

### 2. **Linting**

All code must pass `clippy` without warnings:

```bash
cargo clippy -- -D warnings
```

### 3. **Documentation**

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

```rust
/// 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

```rust
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:

```rust
#[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:

```bash
cargo test --lib
```

### 2. **Integration Tests**

Test component interactions:

```bash
cargo test --test integration_tests
```

### 3. **Manual Testing**

Test with real CalDAV servers:

```bash
# 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.