MatthewClayHarrison-ComfyUI-MetaMan/CONTRIBUTING.md

Contributing to MetaMan

Thank you for considering contributing to MetaMan! This project aims to create universal metadata interoperability across AI image generation platforms.

🤝 How to Contribute

Types of Contributions Welcome

• New Platform Support: Add templates for new AI image generation services
• Bug Fixes: Fix parsing errors, conversion issues, or template problems
• Feature Enhancements: Improve existing functionality or add new capabilities
• Documentation: Improve setup guides, examples, or API documentation
• Testing: Add test cases, validation scripts, or example workflows
• Optimization: Performance improvements or code quality enhancements

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/MetaMan.git
   cd MetaMan
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run tests to ensure everything works:

   python test_installation.py
   python validation.py
   

Development Process

1. Create a feature branch:

   git checkout -b feature/your-feature-name
   

2. Make your changes following these guidelines:

   • Follow existing code style and conventions
   • Add docstrings to new functions and classes
   • Update templates and schema as needed
   • Add validation tests for new features

3. Test your changes:

   python test_installation.py
   python validation.py
   

4. Commit your changes:

   git add .
   git commit -m "Add feature: your descriptive commit message"
   

5. Push to your fork:

   git push origin feature/your-feature-name
   

6. Create a Pull Request on GitHub

🔧 Adding New Platform Support

To add support for a new AI image generation service:

1. Create Service Template

Copy an existing template and modify:

cp templates/services/automatic1111.yaml templates/services/newservice.yaml

Key sections to update:

• service_name: Unique identifier for the service
• output_format: How metadata should be formatted
• field_mappings: How universal fields map to service fields
• png_chunk: How metadata is stored in PNG files
• validation: Service-specific validation rules

2. Update Universal Schema (if needed)

If the new service has unique metadata fields:

1. Add fields to templates/universal_schema.yaml
2. Specify supported_by list including your new service
3. Define field types, validation rules, and mappings

3. Test Your Template

Run validation to ensure your template is correct:

python validation.py

4. Add Examples

Create example metadata files in the examples/ directory showing:

• Typical metadata from your service
• Expected conversion output
• Any special handling requirements

📝 Code Style Guidelines

• Python: Follow PEP 8 with 4-space indentation
• YAML: Use 2-space indentation, consistent key ordering
• Comments: Document complex logic and platform-specific quirks
• Error Handling: Always include try/catch blocks for external API calls
• Type Hints: Use type hints for function parameters and return values

🧪 Testing

Running Tests

# Full test suite
python test_installation.py

# Template validation
python validation.py

# Test specific service template
python validation.py templates/services/yourservice.yaml

Adding Tests

When adding new features:

1. Add test cases to validation.py
2. Include both positive and negative test scenarios
3. Test edge cases (malformed metadata, missing fields, etc.)
4. Verify cross-platform conversion accuracy

📚 Documentation

README Updates

When adding new features, update:

• Feature list in main README.md
• Compatibility matrix
• Usage examples
• Installation requirements

Template Documentation

Each service template should include:

• Clear description of the service and its metadata format
• Examples of typical metadata structures
• Notes about any special handling or limitations
• Links to official service documentation

🐛 Bug Reports

When reporting bugs:

1. Use GitHub Issues with a descriptive title
2. Include steps to reproduce the issue
3. Provide sample data (metadata, images, workflows)
4. Specify your environment (Python version, OS, ComfyUI version)
5. Include error messages and stack traces

Bug Report Template

**Bug Description:**
Brief description of the issue

**Steps to Reproduce:**
1. Load image with metadata from [service]
2. Use MetaMan node with operation [operation]
3. Error occurs when...

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Environment:**
- OS: [e.g., Windows 10, macOS 12, Ubuntu 20.04]
- Python: [e.g., 3.9.7]
- ComfyUI: [version]
- MetaMan: [version/commit]

**Sample Data:**
[Attach sample image or provide metadata text]

💡 Feature Requests

For new features:

1. Check existing issues to avoid duplicates
2. Describe the use case - why is this needed?
3. Propose implementation if you have ideas
4. Consider compatibility with existing features

🔄 Release Process

1. Version Numbering: We follow semantic versioning (MAJOR.MINOR.PATCH)
2. Changelog: Update CHANGELOG.md with new features and fixes
3. Testing: All tests must pass before release
4. Tagging: Create Git tags for releases
5. Documentation: Update installation and setup guides

📞 Getting Help

• GitHub Discussions: For questions and general discussion
• Issues: For bug reports and feature requests
• Documentation: Check README.md and SETUP.md first

🏆 Recognition

Contributors will be recognized in:

• README.md contributors section
• Release notes for significant contributions
• Special thanks for new platform support

📄 License

By contributing to MetaMan, you agree that your contributions will be licensed under the same MIT License as the project.

---

Thank you for helping make AI image metadata universal and interoperable! 🎉