CONTRIBUTING.md

🤝 Contributing Guidelines

Thank you for your interest in contributing to the Human Face to Comic Face Generator! This document provides guidelines and instructions for contributing.

Code of Conduct

Be respectful, inclusive, and constructive. We welcome contributions from people of all backgrounds and experience levels.

How to Contribute

1. Report Bugs

Before reporting, check if the issue already exists.

To report a bug:

• Click "Issues" → "New Issue" → "Bug Report"
• Provide:
  • Clear, descriptive title
  • Steps to reproduce
  • Expected vs actual behavior
  • Your environment (OS, Python version, GPU model)
  • Error message/traceback

2. Suggest Features

To suggest a feature:

• Click "Issues" → "New Issue" → "Feature Request"
• Explain the use case and benefits
• Provide examples if possible
• Link related issues

3. Submit Code

Fork & Clone

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/your-username/HumanFace2ComicFaceGenerator
cd HumanFace2ComicFaceGenerator
git remote add upstream https://github.com/original-author/HumanFace2ComicFaceGenerator

Create a Branch

# Update from upstream
git fetch upstream
git rebase upstream/main

# Create feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-name

Make Changes

• Follow the coding style (see below)
• Make small, focused commits
• Write descriptive commit messages
• Test your changes thoroughly

Commit Messages

# Format: type(scope): description

# Examples:
feat(app): add batch processing support
fix(model): resolve CUDA OOM on large images
docs(readme): update installation instructions
refactor(inference): optimize model loading
test(app): add integration tests
perf(inference): reduce memory footprint

Push & Create PR

# Push to your fork
git push origin feature/your-feature-name

# Create Pull Request on GitHub
# - Provide clear description
# - Link related issues (#123)
# - Explain testing performed

Code Style

Python Style Guide (PEP 8)

# ✅ Good
def convert_face(input_image: Image.Image, resolution: int = 256) -> Image.Image:
    """Convert human face to comic style.
    
    Args:
        input_image: PIL Image of face (RGB, any size)
        resolution: Output resolution (64, 128, or 256)
    
    Returns:
        PIL Image of comic-style face
    
    Raises:
        ValueError: If resolution not in [64, 128, 256]
    """
    if resolution not in [64, 128, 256]:
        raise ValueError("Resolution must be 64, 128, or 256")
    
    # Implementation...
    return output_image


# ❌ Bad
def convert(img, res):
    # No docstring, no type hints
    return output

Formatting

# Use black for formatting
pip install black
black app.py

# Use flake8 for linting
pip install flake8
flake8 app.py --max-line-length=100

# Use isort for imports
pip install isort
isort app.py

Import Organization

# Standard library
import os
import sys
from pathlib import Path

# Third-party
import torch
import numpy as np
from PIL import Image

# Local
from app import convert_face
from utils import load_model

Testing

Unit Tests

# tests/test_app.py
import unittest
from PIL import Image
from app import convert_face

class TestConvertFace(unittest.TestCase):
    def setUp(self):
        """Set up test fixtures"""
        self.test_image = Image.new('RGB', (256, 256), color='red')
    
    def test_basic_conversion(self):
        """Test basic conversion"""
        result, status = convert_face(self.test_image, 256)
        self.assertIsNotNone(result)
        self.assertEqual(result.size, (256, 256))
        self.assertIn("Success", status)
    
    def test_invalid_resolution(self):
        """Test error handling"""
        with self.assertRaises(ValueError):
            convert_face(self.test_image, 512)
    
    def tearDown(self):
        """Clean up"""
        pass

if __name__ == '__main__':
    unittest.main()

Run tests:

# Run all tests
python -m pytest tests/ -v

# Run specific test
python -m pytest tests/test_app.py::TestConvertFace::test_basic_conversion -v

# With coverage
pip install pytest-cov
pytest tests/ --cov=app --cov-report=html

Integration Tests

# tests/test_integration.py
def test_end_to_end_conversion():
    """Test full pipeline"""
    # Download test image
    # Run conversion
    # Verify output
    # Check performance
    pass

Documentation

Docstring Format (Google Style)

def your_function(param1: str, param2: int = 10) -> dict:
    """Brief one-line description.
    
    More detailed explanation if needed.
    Can span multiple lines and include examples.
    
    Args:
        param1: Description of param1
        param2: Description of param2 (default: 10)
    
    Returns:
        dict: Description of return value with keys:
            - 'result' (str): The result
            - 'status' (str): Status message
    
    Raises:
        ValueError: When param1 is empty
        TypeError: When param2 is not int
    
    Example:
        >>> result = your_function("test", 20)
        >>> print(result['status'])
        'Success'
    """
    pass

README Updates

• Keep it accurate and current
• Update Table of Contents if adding sections
• Add examples when describing new features
• Include GPU/CPU requirements
• Update version numbers

Performance Guidelines

Before Optimizing

• Measure first with timeit or cProfile
• Optimize bottlenecks, not random code
• Profile with GPU stats: torch.cuda.memory_allocated()

Common Optimizations

# Use mixed precision (AMP)
from torch.cuda.amp import autocast
with autocast():
    output = model(input_tensor)

# Reduce memory allocation
torch.cuda.empty_cache()

# Optimize batch size
batch_size = 8  # Tune based on VRAM

# Use quantization for CPU inference
import torch.quantization
model = torch.quantization.quantize_dynamic(
    model, {torch.nn.Linear}, dtype=torch.qint8
)

Issue Labels

• bug: Something isn't working
• enhancement: New feature request
• documentation: Docs improvements
• good first issue: Good for newcomers
• help wanted: Need community help
• in progress: Someone is working on it
• blocked: Waiting on something

PR Review Process

What Reviewers Look For

1. Code Quality

   • Follows style guide
   • Well-tested
   • Efficient implementation
   • Good variable names

2. Documentation

   • Docstrings present
   • Comments where needed
   • README updated if applicable

3. Testing

   • Unit tests included
   • Edge cases covered
   • No regression in existing tests

4. Performance

   • No significant slowdown
   • Memory usage reasonable
   • GPU/CPU compatible

Responding to Review

• Respond to all comments
• Push fixes as new commits (don't force push)
• Re-request review after updates
• Ask for clarification if needed

Development Setup

# Install dev dependencies
pip install -r requirements.txt
pip install black flake8 isort pytest pytest-cov

# Pre-commit hook (auto-format)
pip install pre-commit
pre-commit install

# Format and lint
black app.py
isort app.py
flake8 app.py
pytest tests/ -v

Release Process

1. Update version in:

   • config.json
   • MODEL_CARD.md
   • README.md

2. Update CHANGELOG.md:

   ## [1.1.0] - 2026-06-20
   
   ### Added
   - Batch processing support
   
   ### Fixed
   - CUDA OOM on large images
   
   ### Changed
   - Improved inference speed by 30%
   

3. Create GitHub Release with tag v1.1.0

4. Deploy to Hugging Face Spaces

Community

• GitHub Discussions: Ask questions
• Issues: Report bugs or request features
• Pull Requests: Submit code improvements
• Hugging Face: Community feedback on Spaces

Resources

• PyTorch Docs
• Python Style Guide (PEP 8)
• Git Workflow
• Gradio Docs

Questions?

• Open an issue with your question
• Tag maintainers (@your-username)
• Check existing issues/discussions first

---

Common Contribution Scenarios

Scenario 1: Found a Bug

# 1. Create issue describing bug
# 2. Fork and clone
git clone https://github.com/your-username/HumanFace2ComicFaceGenerator
cd HumanFace2ComicFaceGenerator

# 3. Create fix branch
git checkout -b fix/issue-name

# 4. Write failing test
# tests/test_bug.py: Add test that fails with current code

# 5. Fix the bug
# app.py: Make changes

# 6. Verify fix
pytest tests/test_bug.py -v  # Should pass now

# 7. Commit and push
git add -A
git commit -m "fix: resolve bug description"
git push origin fix/issue-name

# 8. Create PR linking to issue (#123)

Scenario 2: Add New Feature

# 1. Create feature branch
git checkout -b feature/batch-processing

# 2. Implement feature with tests
# 3. Update documentation
# 4. Check performance
# 5. Submit PR with description and examples

Scenario 3: Improve Documentation

# 1. Find unclear section in README or docs
# 2. Create branch
git checkout -b docs/clarify-setup

# 3. Update documentation
# 4. Commit and push
# 5. Submit PR

---

Thank you for contributing! 🎉