Contributing - Musfiq0/enhanced-screens-comparison GitHub Wiki

🤝 Contributing

Welcome to the Enhanced Screens Comparison project! We appreciate your interest in contributing and helping make video comparison better for everyone.

🌟 Ways to Contribute

🐛 Bug Reports

Help us improve by reporting issues you encounter:

  • Use the issue tracker on GitHub
  • Provide detailed information about the problem
  • Include system information and error messages
  • Steps to reproduce the issue

💡 Feature Requests

Suggest new features or improvements:

  • Check existing issues to avoid duplicates
  • Describe the use case and expected behavior
  • Explain why the feature would be valuable
  • Consider implementation complexity

📖 Documentation

Improve our documentation:

  • Fix typos and grammar errors
  • Add examples and use cases
  • Improve clarity of instructions
  • Expand wiki pages with detailed information

💻 Code Contributions

Contribute code improvements:

  • Bug fixes and stability improvements
  • New features and enhancements
  • Performance optimizations
  • Code quality improvements

🚀 Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/enhanced-screens-comparison.git
cd enhanced-screens-comparison

# Add upstream remote
git remote add upstream https://github.com/Musfiq0/enhanced-screens-comparison.git

2. Set Up Development Environment

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Install development tools (optional)
pip install black flake8 pytest mypy

3. Verify Setup

# Test the application
python comparev2.py --demo
python gui_app.py

# Run any existing tests
pytest  # If tests are available

📋 Contribution Guidelines

Code Standards

Python Style

  • Follow PEP 8 for Python code style
  • Use type hints where applicable
  • Write docstrings for functions and classes
  • Keep functions focused and single-purpose

Code Formatting

# Format code before submitting
black comparev2.py gui_app.py

# Check code style
flake8 comparev2.py gui_app.py

# Type checking (optional but recommended)
mypy comparev2.py gui_app.py

Example Code Style

def process_video_frame(
    video_path: str, 
    frame_number: int,
    output_path: str,
    crop_settings: Optional[Dict[str, int]] = None
) -> bool:
    """
    Extract and process a single frame from video.
    
    Args:
        video_path: Path to the input video file
        frame_number: Frame number to extract (0-based)
        output_path: Path for the output screenshot
        crop_settings: Optional crop configuration
        
    Returns:
        True if frame processed successfully, False otherwise
        
    Raises:
        FileNotFoundError: If video file doesn't exist
        VideoProcessingError: If frame extraction fails
    """
    try:
        # Implementation here
        return True
    except Exception as e:
        logger.error(f"Frame processing failed: {e}")
        return False

Commit Guidelines

Commit Message Format

type(scope): brief description

Detailed explanation of the changes, if necessary.
Can span multiple lines.

- List specific changes if helpful
- Reference issue numbers with #123
- Explain why, not just what

Commit Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Build process, dependency updates

Examples

feat(gui): add drag and drop support for video files

Implements native drag and drop functionality using tkinterdnd2.
Users can now drag video files directly from Windows Explorer
into the application instead of using the file browser.

- Add tkinterdnd2 dependency
- Implement drop zone highlighting
- Auto-configure dropped videos
- Support multiple file drops

Closes #45

fix(processing): handle videos with corrupted frames

Improves error handling when videos contain corrupted or
unreadable frames. Now skips problematic frames and continues
processing instead of failing completely.

Fixes #67

Branch Strategy

Branch Naming

feature/description      # New features
bugfix/issue-description # Bug fixes  
docs/improvement        # Documentation updates
refactor/component      # Code refactoring

Example Workflow

# Create feature branch
git checkout -b feature/upload-retry-mechanism

# Make changes and commit
git add .
git commit -m "feat(upload): add retry mechanism for failed uploads"

# Push to your fork
git push origin feature/upload-retry-mechanism

# Create pull request on GitHub

🔧 Development Workflow

1. Issue First

  • Check existing issues before starting work
  • Create an issue for significant changes
  • Discuss approach for complex features
  • Get feedback before implementation

2. Development Process

# Keep your fork updated
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/your-feature

# Make changes, test, commit
git add .
git commit -m "descriptive commit message"

# Push and create PR
git push origin feature/your-feature

3. Testing Your Changes

# Test core functionality
python comparev2.py --demo

# Test GUI
python gui_app.py

# Test specific features
python comparev2.py  # Interactive mode

# Build and test executable (if relevant)
python build_exe.py
dist\screenshot_comparison.exe --demo

4. Documentation Updates

  • Update README.md if adding user-facing features
  • Update wiki pages for detailed documentation
  • Add code comments for complex logic
  • Update requirements.txt if adding dependencies

📝 Pull Request Process

Before Submitting

  • Code follows style guidelines
  • Tests pass (if tests exist)
  • Documentation updated if needed
  • No merge conflicts with main branch
  • Commit messages are clear

PR Description Template

## Description
Brief description of the changes and their purpose.

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Tested on Windows 10/11
- [ ] GUI functionality verified
- [ ] CLI functionality verified
- [ ] No regressions in existing features

## Screenshots (if applicable)
Add screenshots for GUI changes or visual improvements.

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings

## Related Issues
Fixes #(issue number)

Review Process

  1. Automated checks run automatically
  2. Manual review by maintainers
  3. Feedback and iteration if needed
  4. Approval and merge when ready

🎯 Contribution Ideas

Beginner-Friendly

  • Fix typos in documentation
  • Improve error messages with more helpful text
  • Add crop presets for new streaming services
  • Enhance tooltips and user guidance

Intermediate

  • Add new video formats support
  • Improve upload reliability with better error handling
  • Add configuration presets for common workflows
  • Enhance progress reporting with more detailed status

Advanced

  • New processing backends integration
  • Cross-platform support (Linux, macOS)
  • Performance optimizations for large videos
  • Advanced upload services integration

Specific Areas

Video Processing

  • New backends: FFmpeg, ImageIO, etc.
  • Quality improvements: Better scaling algorithms
  • Performance: Parallel processing, memory optimization
  • Format support: New video containers and codecs

User Interface

  • Accessibility: Better keyboard navigation, screen reader support
  • Usability: Improved workflows, better defaults
  • Visual: Modern styling, better icons
  • Features: Batch processing, template saving

Upload Integration

  • New services: Additional comparison hosting platforms
  • Reliability: Better error handling, retry logic
  • Features: Collection management, metadata preservation
  • Authentication: API key management, OAuth support

Documentation

  • Tutorials: Step-by-step guides for common tasks
  • Examples: Real-world use cases and configurations
  • API docs: Comprehensive function and class documentation
  • Troubleshooting: Common issues and solutions

🏆 Recognition

Contributors

All contributors are recognized in:

  • README.md contributors section
  • Release notes for significant contributions
  • GitHub insights automatically track contributions

Types of Recognition

  • Code contributors: Direct code improvements
  • Documentation contributors: Docs, examples, tutorials
  • Issue reporters: High-quality bug reports and feature requests
  • Community helpers: Answering questions, helping users

📞 Getting Help

Where to Ask Questions

  • GitHub Discussions: General questions and ideas
  • GitHub Issues: Bug reports and feature requests
  • Pull Request Comments: Code-specific questions
  • Wiki Pages: Comprehensive documentation

Response Times

  • Issues: We aim to respond within 48 hours
  • Pull Requests: Initial review within 72 hours
  • Questions: Community and maintainers help when available

Contact

  • GitHub: Primary communication channel
  • Issues: For bug reports and feature requests
  • Discussions: For general questions and ideas

📜 Code of Conduct

Our Standards

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and improve
  • Respect different perspectives and experiences

Unacceptable Behavior

  • Harassment or discriminatory language
  • Personal attacks or inflammatory comments
  • Spam or off-topic content
  • Violation of others' privacy

Enforcement

  • Issues are addressed promptly and fairly
  • Consequences range from warnings to bans
  • Appeals process available for disputed actions

Thank you for contributing to Enhanced Screens Comparison! Together, we make video comparison better for everyone. 🙏