alvaro/caldavpuller
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Split documentation into separate files

Browse source 
- Move development details to DEVELOPMENT.md
- Move contributing guidelines to CONTRIBUTING.md
- Add LICENSE file with MIT license
- Add CONTRIBUTORS.md for attribution
- Update README.md to focus on user-facing information
- Improve documentation structure and navigation
This commit is contained in:
Alvaro Soliverez 2025-10-04 12:33:59 -03:00
parent 8362ebe44b
commit 37e9bc2dc1
5 changed files with 826 additions and 122 deletions
Download patch file Download diff file Expand all files Collapse all files

358
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,358 @@
# 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.