A043-studios-ComfyUI_HunyuanWorldnode/CONTRIBUTING.md

# Contributing to ComfyUI-HunyuanWorld

Thank you for your interest in contributing to ComfyUI-HunyuanWorld! We welcome contributions from the community.

## 🤝 How to Contribute

### Reporting Bugs
1. Check if the bug has already been reported in [Issues](https://github.com/A043-studios/ComfyUI_HunyuanWorldnode/issues)
2. If not, create a new issue using the bug report template
3. Include as much detail as possible (OS, Python version, error logs, etc.)

### Suggesting Features
1. Check if the feature has already been requested
2. Create a new issue using the feature request template
3. Describe your use case and why the feature would be valuable

### Contributing Code

#### Setting Up Development Environment
```bash
# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements.txt
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install
```

#### Making Changes
1. Create a new branch for your feature/fix:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Make your changes following our coding standards:
   - Use Black for code formatting: `black .`
   - Use isort for import sorting: `isort .`
   - Follow PEP 8 guidelines
   - Add type hints where appropriate
   - Write docstrings for new functions/classes

3. Add tests for new functionality:
   ```bash
   # Run tests
   pytest tests/
   
   # Run with coverage
   pytest --cov=hunyuanworld tests/
   ```

4. Update documentation:
   - Update README.md if needed
   - Update CHANGELOG.md
   - Add docstrings to new code
   - Update example workflows if applicable

5. Commit your changes:
   ```bash
   git add .
   git commit -m "feat: add new feature description"
   ```
   
   Use conventional commit messages:
   - `feat:` for new features
   - `fix:` for bug fixes
   - `docs:` for documentation changes
   - `style:` for formatting changes
   - `refactor:` for code refactoring
   - `test:` for adding tests
   - `chore:` for maintenance tasks

6. Push to your fork and create a Pull Request:
   ```bash
   git push origin feature/your-feature-name
   ```

#### Pull Request Guidelines
- Fill out the PR template completely
- Ensure all tests pass
- Update documentation as needed
- Keep PRs focused on a single feature/fix
- Write clear commit messages
- Be responsive to feedback

## 🧪 Testing

### Running Tests
```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_nodes.py

# Run with coverage
pytest --cov=hunyuanworld --cov-report=html
```

### Test Categories
- **Unit tests**: Test individual functions/classes
- **Integration tests**: Test node interactions
- **Compatibility tests**: Test with different Python/PyTorch versions
- **Performance tests**: Test memory usage and speed

### Writing Tests
- Place tests in the `tests/` directory
- Name test files `test_*.py`
- Use descriptive test names
- Test both success and failure cases
- Mock external dependencies when appropriate

## 📝 Documentation

### Code Documentation
- Write clear docstrings for all public functions/classes
- Use Google-style docstrings
- Include parameter types and return types
- Provide usage examples for complex functions

### User Documentation
- Update README.md for user-facing changes
- Add examples to `example_workflows.json`
- Update troubleshooting section for common issues
- Keep documentation up-to-date with code changes

## 🎨 Code Style

### Python Style Guide
- Follow PEP 8
- Use Black for formatting (line length: 100)
- Use isort for import sorting
- Use type hints where possible
- Prefer descriptive variable names

### Example:
```python
from typing import Optional, Tuple
import torch
from PIL import Image

def process_image(
    image: Image.Image, 
    target_size: Tuple[int, int] = (512, 512),
    normalize: bool = True
) -> torch.Tensor:
    """
    Process an input image for 3D generation.
    
    Args:
        image: Input PIL image
        target_size: Target dimensions (width, height)
        normalize: Whether to normalize pixel values to [0,1]
        
    Returns:
        Processed image tensor
        
    Example:
        >>> img = Image.open("test.jpg")
        >>> tensor = process_image(img, (1024, 1024))
    """
    # Implementation here
    pass
```

## 🚀 Release Process

### Version Numbering
We follow [Semantic Versioning](https://semver.org/):
- `MAJOR.MINOR.PATCH`
- Major: Breaking changes
- Minor: New features (backward compatible)
- Patch: Bug fixes (backward compatible)

### Release Checklist
- [ ] Update version in `setup.py` and `pyproject.toml`
- [ ] Update `CHANGELOG.md`
- [ ] Run full test suite
- [ ] Update documentation
- [ ] Create release PR
- [ ] Tag release after merge
- [ ] Publish to PyPI (if applicable)

## 🏷️ Issue Labels

- `bug`: Something isn't working
- `enhancement`: New feature or request
- `documentation`: Improvements or additions to docs
- `good first issue`: Good for newcomers
- `help wanted`: Extra attention is needed
- `question`: Further information is requested
- `wontfix`: This will not be worked on

## 💬 Community Guidelines

### Be Respectful
- Use welcoming and inclusive language
- Be respectful of differing viewpoints
- Accept constructive criticism gracefully
- Focus on what's best for the community

### Be Helpful
- Help newcomers get started
- Share knowledge and experience
- Provide constructive feedback
- Be patient with questions

## 📞 Getting Help

- **Questions**: Open a GitHub issue with the `question` label
- **Bugs**: Use the bug report template
- **Features**: Use the feature request template
- **Security**: Email security issues privately (if applicable)

## 🙏 Recognition

Contributors will be recognized in:
- `CONTRIBUTORS.md` file
- Release notes
- GitHub contributors page

Thank you for contributing to ComfyUI-HunyuanWorld! 🌍✨