Spaces:

MuhammadQasimShabbir3
/

HumanFace2ComicFaceGenerator

Sleeping

App Files Files Community

HumanFace2ComicFaceGenerator / CONTRIBUTING.md

MuhammadQasimShabbir3

Cursor

feat: complete production-ready deployment with model weights fix

874c9a7 4 months ago

preview code

Raw History Blame Contribute Delete

9.44 kB

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

	# 🤝 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! 🎉