# Contributing to cpdb-rs
Thank you for your interest in contributing to cpdb-rs! This document provides guidelines and information for contributors.
## Getting Started
### Prerequisites
- Rust 1.85+ (2024 edition)
- cpdb-libs C library installed on your system
- Git
### Development Setup
1. Fork the repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/your-username/cpdb-rs.git
cd cpdb-rs
```
3. Add the upstream repository:
```bash
git remote add upstream https://github.com/OpenPrinting/cpdb-rs.git
```
4. Install dependencies:
```bash
cargo build
```
### Building and Testing
```bash
# Build the project
cargo build
# Run tests
cargo test
# Run tests with output
cargo test -- --nocapture
# Run specific test
cargo test test_name
# Check formatting
cargo fmt --all -- --check
# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
# Build documentation
cargo doc --no-deps --open
```
## Contribution Guidelines
### Code Style
- Follow Rust naming conventions
- Use `cargo fmt` to format code
- Use `cargo clippy` to catch common issues
- Write comprehensive documentation
- Add tests for new functionality
### Commit Messages
Use clear, descriptive commit messages:
```
feat: add printer options support
fix: handle null pointer in settings
docs: update README with new examples
test: add unit tests for media handling
```
### Pull Request Process
1. Create a feature branch from `main`:
```bash
git checkout -b feature/your-feature-name
```
2. Make your changes and commit them:
```bash
git add .
git commit -m "feat: add your feature"
```
3. Push your branch:
```bash
git push origin feature/your-feature-name
```
4. Create a pull request on GitHub
5. Ensure all CI checks pass
6. Address any review feedback
### Testing Requirements
- Add unit tests for new functionality
- Add integration tests for complex features
- Ensure all existing tests pass
- Test on multiple platforms when possible
### Documentation
- Update README.md for user-facing changes
- Add doc comments for public APIs
- Include examples in documentation
- Update CHANGELOG.md for significant changes
## Areas for Contribution
### High Priority
- [ ] Additional printer backends support
- [ ] Enhanced error handling and recovery
- [ ] Performance optimizations
- [ ] Cross-platform testing
- [ ] Documentation improvements
### Medium Priority
- [ ] Async/await support
- [ ] More comprehensive examples
- [ ] Benchmarking suite
- [ ] Fuzz testing
- [ ] Windows support (if feasible)
### Low Priority
- [ ] Additional utility functions
- [ ] More detailed logging
- [ ] Configuration management
- [ ] Plugin system
## Reporting Issues
### Bug Reports
When reporting bugs, please include:
- Operating system and version
- Rust version (`rustc --version`)
- cpdb-libs version
- Steps to reproduce
- Expected vs actual behavior
- Error messages or logs
### Feature Requests
For feature requests, please include:
- Use case description
- Proposed API design
- Implementation considerations
- Backward compatibility impact
## Code Review Process
### For Contributors
- Respond to review feedback promptly
- Make requested changes in new commits
- Ask questions if feedback is unclear
- Test changes thoroughly
### For Reviewers
- Be constructive and helpful
- Focus on code quality and correctness
- Check for security issues
- Verify tests and documentation
## Release Process
Releases are managed by maintainers. Since this project is structured as a workspace, **`cpdb-sys` must be published to crates.io before `cpdb-rs`**.
1. Update the version in `cpdb-sys/Cargo.toml`.
2. Update the version in `Cargo.toml` (both for `cpdb-rs` package version and the `cpdb-sys` dependency version in `[dependencies]`).
3. Update `CHANGELOG.md`.
4. Create a release tag (e.g., `v0.1.0`).
5. Publish `cpdb-sys` first:
```bash
cd cpdb-sys
cargo publish
```
6. Publish `cpdb-rs`:
```bash
cargo publish
```
7. Create the GitHub release.
## Community Guidelines
- Be respectful and inclusive
- Help others learn and grow
- Share knowledge and experience
- Follow the Rust Code of Conduct
## Getting Help
- GitHub Issues for bug reports and feature requests
- GitHub Discussions for questions and general discussion
- Rust Discord for real-time chat
- Documentation for API reference
## License
By contributing to cpdb-rs, you agree that your contributions will be licensed under the MIT License.
## Recognition
Contributors will be recognized in:
- CONTRIBUTORS.md file
- Release notes
- GitHub contributors page
Thank you for contributing to cpdb-rs!