# 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` for fallible operations - Provide meaningful error context - Handle errors gracefully at the UI layer ```rust pub async fn sync_calendars(&mut self) -> CalDavResult { 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.