Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
225 lines (159 loc) · 4.79 KB

CONTRIBUTING.md

File metadata and controls

225 lines (159 loc) · 4.79 KB
Raw

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: 
    git clone https://github.com/your-username/cpdb-rs.git
cd cpdb-rs
  3. Add the upstream repository: 
    git remote add upstream https://github.com/OpenPrinting/cpdb-rs.git
  4. Install dependencies: 
    cargo build

Building and Testing

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

    git checkout -b feature/your-feature-name

  2. Make your changes and commit them:

    git add .
git commit -m "feat: add your feature"

  3. Push your branch:

    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:
cd cpdb-sys
cargo publish
  1. Publish cpdb-rs:
cargo publish
  1. 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!