Contributing

We welcome contributions to GUI Image Studio! This guide will help you get started with contributing to the project.

Getting Started

Prerequisites

  • Python 3.8 or later

  • Git for version control

  • Basic knowledge of image processing concepts

  • Familiarity with Tkinter/CustomTkinter (for GUI contributions)

Development Setup

  1. Fork and Clone the Repository

    git clone https://github.com/yourusername/gui-image-studio.git
cd gui-image-studio

  2. Create a Virtual Environment

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install Development Dependencies

    pip install -e .[dev]

  4. Verify Installation

    python scripts/verify-install.py
pytest tests/

Types of Contributions

Code Contributions

  • Bug fixes and improvements

  • New image processing features

  • GUI enhancements

  • Performance optimizations

  • Documentation improvements

Non-Code Contributions

  • Bug reports and feature requests

  • Documentation improvements

  • Example applications

  • Testing and quality assurance

  • Community support

Areas Needing Help

  • Advanced image filters and effects

  • Animation tools and timeline features

  • Plugin system development

  • Performance optimization

  • Cross-platform compatibility

  • Accessibility improvements

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

  • Follow the coding standards (see below)

  • Add tests for new functionality

  • Update documentation as needed

  • Test your changes thoroughly

3. Run Quality Checks

# Run tests
pytest tests/

# Check code formatting
black --check src/

# Run linting
flake8 src/

# Type checking
mypy src/

4. Commit Your Changes

git add .
git commit -m "Add feature: your feature description"

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Coding Standards

Python Style

  • Follow PEP 8 style guidelines

  • Use Black for code formatting

  • Maximum line length: 88 characters

  • Use type hints for all public functions

Code Organization

"""
Module docstring describing the module's purpose.
"""

import standard_library_modules
import third_party_modules
import local_modules

# Constants
DEFAULT_QUALITY = 95

class ExampleClass:
    """Class docstring."""

    def __init__(self, param: str) -> None:
        """Initialize with parameter."""
        self.param = param

    def public_method(self, arg: int) -> str:
        """Public method with type hints and docstring."""
        return self._private_method(arg)

    def _private_method(self, arg: int) -> str:
        """Private method (prefixed with underscore)."""
        return f"{self.param}: {arg}"

Documentation Standards

  • Use Google-style docstrings

  • Include type hints in function signatures

  • Provide examples for complex functions

  • Document all public APIs

def process_image(image: Image.Image, filter_type: str, intensity: float = 1.0) -> Image.Image:
    """Apply a filter to an image.

    Args:
        image: The input PIL Image object
        filter_type: Type of filter to apply ('blur', 'sharpen', 'emboss')
        intensity: Filter intensity from 0.0 to 1.0 (default: 1.0)

    Returns:
        Processed PIL Image object

    Raises:
        ValueError: If filter_type is not supported
        TypeError: If image is not a PIL Image object

    Example:
        >>> image = get_image("photo.jpg")
        >>> blurred = process_image(image, "blur", 0.5)
        >>> save_image(blurred, "blurred_photo.jpg")
    """
    # Implementation would go here
    if filter_type not in ['blur', 'sharpen', 'emboss']:
        raise ValueError(f"Unsupported filter type: {filter_type}")

    # Apply the filter based on type and intensity
    # This is a placeholder implementation
    return image

Testing Guidelines

Test Structure

tests/
├── test_image_loader.py      # Test core image operations
├── test_image_studio.py      # Test GUI components
├── test_generator.py         # Test resource generation
├── test_cli.py              # Test command-line interface
└── fixtures/                # Test images and data
    ├── sample_image.png
    └── sample_animation.gif

Writing Tests

import pytest
from PIL import Image
import gui_image_studio

class TestImageLoader:
    """Test cases for image loading functionality."""

    def test_load_valid_image(self):
        """Test loading a valid image file."""
        image = gui_image_studio.get_image("tests/fixtures/sample_image.png")
        assert isinstance(image, Image.Image)
        assert image.size == (100, 100)

    def test_load_nonexistent_image(self):
        """Test loading a non-existent image file."""
        with pytest.raises(FileNotFoundError):
            gui_image_studio.get_image("nonexistent.png")

    @pytest.mark.parametrize("color,expected", [
        ("#FF0000", (255, 0, 0)),
        ("#00FF00", (0, 255, 0)),
        ("#0000FF", (0, 0, 255)),
    ])
    def test_apply_tint_colors(self, color, expected):
        """Test tinting with different colors."""
        image = Image.new("RGB", (10, 10), "white")
        tinted = gui_image_studio.apply_tint(image, color)
        # Add assertions to verify tinting worked correctly

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_image_loader.py

# Run with coverage
pytest --cov=gui_image_studio

# Run tests matching pattern
pytest -k "test_load"

Pull Request Guidelines

Before Submitting

  • Ensure all tests pass

  • Update documentation if needed

  • Add changelog entry for significant changes

  • Rebase your branch on the latest main

Pull Request Template

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] New tests added for new functionality
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Changelog updated (if applicable)

Review Process

  1. Automated checks run (CI/CD)

  2. Code review by maintainers

  3. Address feedback and make changes

  4. Final approval and merge

Issue Reporting

Bug Reports

Use the bug report template and include:

  • GUI Image Studio version

  • Python version and platform

  • Steps to reproduce

  • Expected vs actual behavior

  • Error messages and stack traces

  • Sample images (if relevant)

Feature Requests

Use the feature request template and include:

  • Clear description of the feature

  • Use case and motivation

  • Proposed implementation (if any)

  • Examples from other tools

Security Issues

For security vulnerabilities:

Documentation Contributions

Types of Documentation

  • API documentation (docstrings)

  • User guides and tutorials

  • Example applications

  • Developer documentation

Documentation Standards

  • Use reStructuredText (.rst) format

  • Follow existing structure and style

  • Include code examples

  • Test all code examples

Building Documentation

cd docs/
make html
# Open _build/html/index.html in browser

Community Guidelines

Code of Conduct

  • Be respectful and inclusive

  • Focus on constructive feedback

  • Help newcomers learn and contribute

  • Maintain professional communication

Communication Channels

  • GitHub Issues for bugs and features

  • GitHub Discussions for questions

  • Pull Request reviews for code feedback

Recognition

Contributors are recognized in:

  • CONTRIBUTORS.md file

  • Release notes

  • Documentation credits

  • Annual contributor highlights

Getting Help

For Contributors

  • Check existing issues and pull requests

  • Read the developer documentation

  • Ask questions in GitHub Discussions

  • Join the contributor chat (if available)

Mentorship

New contributors can request mentorship:

  • Comment on “good first issue” labels

  • Ask for guidance in discussions

  • Pair programming sessions (when available)

Release Process

Version Numbering

We follow Semantic Versioning (SemVer):

  • MAJOR.MINOR.PATCH (e.g., 1.2.3)

  • MAJOR: Breaking changes

  • MINOR: New features (backward compatible)

  • PATCH: Bug fixes (backward compatible)

Release Checklist

  1. Update version numbers

  2. Update CHANGELOG.md

  3. Run full test suite

  4. Build and test packages

  5. Create release tag

  6. Deploy to PyPI

  7. Update documentation

Thank You!

Thank you for contributing to GUI Image Studio! Your contributions help make this project better for everyone.

Questions?

If you have questions about contributing:

  • Check the FAQ in our documentation

  • Search existing GitHub issues

  • Create a new discussion

  • Contact the maintainers

We appreciate your time and effort in making GUI Image Studio better!