Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
354 lines (279 loc) · 8.11 KB

CONTRIBUTING.md

File metadata and controls

354 lines (279 loc) · 8.11 KB

Contributing to PixelateR

Thank you for your interest in contributing to PixelateR! This document provides guidelines and information for contributors.

Table of Contents

Code of Conduct

By participating in this project, you agree to:

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on what's best for the community
  • Show empathy towards other community members

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/yourusername/pixelateR.git
cd pixelateR
  3. Add upstream remote: 
    git remote add upstream https://github.com/muhammad1438/pixelateR.git
  4. Create a branch for your changes: 
    git checkout -b feature/your-feature-name

Development Setup

Prerequisites

  • Rust 1.70+ (install via rustup)
  • Node.js 16+ and npm
  • FFmpeg (for video processing)
  • wasm-pack (for WebAssembly builds)

Building the Project

# Build CLI tool
cargo build

# Run tests
cargo test

# Build WASM module
cd wasm
wasm-pack build --target web
cd ..

# Build web interface
cd web
npm install
npm run build
cd ..

Running Development Server

# Terminal 1: Build WASM in watch mode
cd wasm
cargo watch -i pkg -s "wasm-pack build --target web"

# Terminal 2: Run web dev server
cd web-serve
npm install
npm start

Open http://localhost:8080 to see the web interface.

How to Contribute

Reporting Bugs

Before creating a bug report:

  • Check existing issues to avoid duplicates
  • Collect information about your environment (OS, Rust version, browser)
  • Create a minimal reproducible example if possible

Include in your bug report:

  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots or error messages
  • System information

Suggesting Enhancements

Enhancement suggestions are welcome! Please:

  • Use a clear and descriptive title
  • Provide detailed description of the proposed feature
  • Explain why this enhancement would be useful
  • Include examples or mockups if applicable

Pull Requests

Good pull requests include:

  • Clear description of changes
  • Reference to related issues
  • Tests for new functionality
  • Documentation updates
  • No unrelated changes

Coding Standards

Rust Code

  • Formatting: Use cargo fmt before committing
  • Linting: Run cargo clippy and fix warnings
  • Naming:
    • snake_case for functions and variables
    • PascalCase for types and traits
    • SCREAMING_SNAKE_CASE for constants
  • Comments:
    • Use /// for public API documentation
    • Use // for implementation comments
  • Error Handling: Prefer Result<T, E> over panics

Example:

/// Applies Bayer dithering to an image.
///
/// # Arguments
/// * `img` - The input image
/// * `palette` - The color palette to use
///
/// # Returns
/// The dithered image or an error
pub fn apply_bayer_dither(
    img: &Image,
    palette: &Palette,
) -> Result<Image, DitherError> {
    // Implementation
}

TypeScript Code

  • Formatting: Use Prettier (configured in web/)
  • Linting: Run ESLint
  • Types: Prefer explicit types over any
  • Naming:
    • camelCase for variables and functions
    • PascalCase for classes and interfaces
  • Comments: Use JSDoc for public APIs

Example:

/**
 * Transforms an image using the specified settings.
 * @param imageData - The input image data
 * @param settings - Transformation settings
 * @returns The transformed image data
 */
async function transformImage(
  imageData: ImageData,
  settings: TransformSettings
): Promise<ImageData> {
  // Implementation
}

Documentation

  • Keep README.md up to date
  • Document new features in relevant docs/
  • Add code examples for new functionality
  • Update CHANGELOG.md for significant changes

Testing

Unit Tests

# Run all tests
cargo test

# Run specific test
cargo test test_bayer_dithering

# Run with output
cargo test -- --nocapture

Write tests for:

  • New dithering algorithms
  • Color quantization logic
  • Edge detection filters
  • CLI argument parsing

Example test:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_bayer_threshold() {
        let threshold = bayer_threshold(0, 0);
        assert_eq!(threshold, 0.0 / 16.0);
    }
}

Integration Tests

Place integration tests in tests/:

cargo test --test integration_tests

Benchmarks

# Run benchmarks
cargo bench

# Specific benchmark
cargo bench floyd_steinberg

Submitting Changes

  1. Commit your changes:

    git add .
git commit -m "feat: add new dithering algorithm"

  2. Follow commit message conventions:

    • feat: New feature
    • fix: Bug fix
    • docs: Documentation changes
    • style: Formatting, no code change
    • refactor: Code restructuring
    • test: Adding tests
    • chore: Maintenance tasks

  3. Push to your fork:

    git push origin feature/your-feature-name

  4. Create a Pull Request:

    • Go to GitHub and click "New Pull Request"
    • Fill out the PR template
    • Link related issues
    • Request review

  5. Respond to feedback:

    • Address reviewer comments
    • Push additional commits if needed
    • Mark conversations as resolved

Project Structure

PixelateR/
├── src/
│   ├── cli/           # Command-line interface
│   ├── color/         # Color quantization and palettes
│   │   ├── palette.rs # Palette definitions (Pico8, etc.)
│   │   └── quantize.rs
│   ├── dither/        # Dithering algorithms
│   │   ├── bayer.rs   # Ordered dithering
│   │   ├── floyd.rs   # Error diffusion
│   │   └── riemersma.rs
│   ├── filter/        # Image filters
│   │   ├── brightness.rs
│   │   ├── contrast.rs
│   │   └── halftone.rs
│   ├── image/         # Core image types
│   └── video/         # Video processing (future)
├── wasm/              # WebAssembly bindings
│   └── src/lib.rs
├── web/               # TypeScript frontend
│   ├── src/
│   │   └── main.ts
│   └── index.html
├── tests/             # Integration tests
├── benches/           # Benchmarks
├── docs/              # Documentation
└── examples/          # Sample inputs/outputs

Key Files

  • src/lib.rs: Library entry point, exports public API
  • src/cli/main.rs: CLI tool entry point
  • wasm/src/lib.rs: WASM bindings for web interface
  • web/src/main.ts: Web application logic
  • Cargo.toml: Rust dependencies and metadata

Areas for Contribution

High Priority

  • GPU acceleration via wgpu
  • Additional color palettes (Gameboy, NES, C64)
  • Multithreaded batch processing
  • Pure Rust video encoding (rav1e)
  • Python bindings via PyO3

Medium Priority

  • Web interface: video upload support
  • Web interface: custom palette editor
  • Advanced filters (CRT scan lines, bloom)
  • More dithering algorithms (Atkinson, Sierra)
  • Color space conversions (LAB, LCH)

Documentation

  • Video tutorial for web interface
  • Algorithm comparison guide
  • Performance optimization guide
  • API documentation improvements

Testing

  • Increase test coverage to 80%+
  • Add visual regression tests
  • Benchmark suite for all algorithms
  • Cross-platform CI/CD

Getting Help

  • Questions: Open a GitHub Discussion
  • Bugs: Create an Issue with the bug template
  • Chat: Join our Discord (link in README)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Acknowledgments

Thank you for contributing to PixelateR! Your efforts help make pixel art processing accessible to everyone.