EricRollei-Download_Tools/CONTRIBUTING.md

Contributing to Download Tools for ComfyUI

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

Table of Contents

• Code of Conduct
• How to Contribute
• Development Setup
• Coding Standards
• Testing
• Submitting Changes
• License

Code of Conduct

This project and everyone participating in it is governed by common sense and mutual respect. We expect all contributors to:

• Be respectful and inclusive
• Accept constructive criticism gracefully
• Focus on what is best for the community
• Show empathy towards other community members

How to Contribute

Reporting Bugs

If you find a bug, please open an issue with:

1. Clear title and description
2. Steps to reproduce the problem
3. Expected behavior vs actual behavior
4. Environment details (OS, Python version, ComfyUI version)
5. Relevant logs or error messages
6. Screenshots if applicable

Suggesting Enhancements

Enhancement suggestions are welcome! Please open an issue with:

1. Clear description of the feature
2. Use case - why would this be useful?
3. Examples of how it would work
4. References to similar features in other tools (if applicable)

Contributing Code

1. Fork the repository and create a branch from main
2. Make your changes following our coding standards
3. Test thoroughly with real data
4. Update documentation if needed
5. Submit a pull request

Development Setup

Prerequisites

• Python 3.10 or higher
• ComfyUI installation
• Git

Setting Up Development Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/download_tools.git
cd download_tools

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1

# Linux/Mac:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies (if any)
pip install pytest black flake8

Testing Your Changes

1. Copy to ComfyUI custom_nodes:

   # Create symlink or copy to ComfyUI
   # Example: mklink /D "C:\ComfyUI\custom_nodes\download_tools" "C:\path\to\your\download_tools"
   

2. Start ComfyUI and test:

   • Verify nodes load correctly
   • Test with real-world data
   • Check for errors in console

3. Run manual tests:

   • Test each modified node
   • Verify backward compatibility
   • Check error handling

Coding Standards

Python Style Guide

We follow PEP 8 with some modifications:

• Line length: 100 characters (prefer 80-90)
• Indentation: 4 spaces (no tabs)
• Imports: Group in order (standard library, third-party, local)
• Docstrings: Use for all public functions, classes, and modules

File Headers

All Python files should include a header with license and credits:

"""
[Module Name] - [Brief Description]

Author: [Your Name] (GitHub: YourUsername)
Original Author: Eric Hiss (GitHub: EricRollei)
Contact: [eric@historic.camera, eric@rollei.us]
License: Dual License (CC BY-NC 4.0 / Commercial)
Copyright (c) 2025 Eric Hiss. All rights reserved.

[Additional description if needed]

Dependencies:
- List key dependencies used by this specific module
- Include their licenses

[Additional notes]
"""

Code Organization

# 1. Standard library imports
import os
import sys
from typing import Dict, List, Optional

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

# 3. Local imports
from .utils import helper_function

Error Handling

Always include comprehensive error handling:

try:
    # Your code here
    result = process_image(image)
except ValueError as e:
    print(f"Error: Invalid input - {e}")
    return None
except Exception as e:
    print(f"Unexpected error in process_image: {e}")
    import traceback
    traceback.print_exc()
    return None

Logging and Debug Output

Use print statements for user-facing messages:

print(f"[Gallery-dl] Processing {url}")
print(f"[Yt-dlp] Downloaded {count} videos")
print(f"[Web Scraper] ERROR: {error_message}")

ComfyUI Node Structure

Follow the established pattern for ComfyUI nodes:

class MyCustomNode:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "param1": ("STRING", {"default": ""}),
            },
            "optional": {
                "param2": ("INT", {"default": 0}),
            }
        }
    
    RETURN_TYPES = ("IMAGE",)
    FUNCTION = "process"
    CATEGORY = "download_tools"
    
    def process(self, param1, param2=0):
        """Process the input and return result."""
        try:
            # Your logic here
            return (result,)
        except Exception as e:
            print(f"Error in MyCustomNode: {e}")
            return (None,)

Testing

Manual Testing

1. Basic functionality: Does the node work as expected?
2. Edge cases: Empty inputs, invalid URLs, rate limits, authentication failures
3. Error handling: Graceful failures with helpful messages
4. Performance: Reasonable speed for typical use cases
5. Memory usage: No memory leaks or excessive consumption

Test Data

• Use realistic test data (actual URLs, various websites, public profiles)
• Test with both small and large inputs
• Test with corrupted or malformed data
• Document any test cases in Docs/ if they're useful examples

Regression Testing

• Ensure existing functionality still works
• Test with existing workflows if possible
• Check for backward compatibility

Submitting Changes

Pull Request Process

1. Update documentation for any user-facing changes
2. Add or update tests if applicable
3. Ensure your code follows the coding standards
4. Write a clear PR description including:
   • What changes were made
   • Why they were needed
   • How to test them
   • Any breaking changes

PR Description Template

## Description
Brief description of changes

## Motivation
Why is this change needed?

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
How was this tested?

## Screenshots (if applicable)
[Add screenshots here]

## Checklist
- [ ] Code follows project style guidelines
- [ ] Documentation updated
- [ ] Tested with real data
- [ ] No breaking changes (or documented if necessary)

Commit Messages

Use clear, descriptive commit messages:

Good examples:
- "Add support for multi-page PDF processing"
- "Fix memory leak in image processor"
- "Update README with new installation instructions"

Avoid:
- "fix bug"
- "update"
- "changes"

License

By contributing to this project, you agree that your contributions will be licensed under the same dual license as the project (CC BY-NC 4.0 for non-commercial use, separate commercial license required).

You also certify that:

1. You have the right to contribute the code
2. Your contribution is your original work or properly attributed
3. You understand the licensing terms

Questions?

If you have questions about contributing:

• Open an issue for general questions
• Email: eric@historic.camera or eric@rollei.us
• Check existing issues for similar questions

Acknowledgments

Thank you for taking the time to contribute! Your efforts help make this project better for everyone.

---

Remember: This is a working codebase used in production. Please test thoroughly and maintain backward compatibility whenever possible.