# 🤝 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
```bash
# 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
```bash
# 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
```bash
# 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)

```python
# ✅ 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

```bash
# 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

```python
# 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

```python
# 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:
```bash
# 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

```python
# 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)

```python
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

```python
# 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

```bash
# 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`:
   ```markdown
   ## [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](https://pytorch.org/docs)
- [Python Style Guide (PEP 8)](https://www.python.org/dev/peps/pep-0008/)
- [Git Workflow](https://git-scm.com/book)
- [Gradio Docs](https://gradio.app/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

```bash
# 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

```bash
# 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

```bash
# 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! 🎉**