Contributing to Colorium

Thank you for your interest in contributing to Colorium! This guide will help you get started with contributing to the project.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

  • Python 3.8 or higher
  • Git
  • Basic knowledge of Python and color science

Development Setup

1
2
3
4
5
6
7
8
9
10
11
12
13
# Fork and clone the repository
git clone https://github.com/your-username/colorium.git
cd colorium

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

# Install development dependencies
pip install -e ".[dev]"

# Verify installation
pytest -v

Project Structure

colorium/ ├── src/ │ └── colorium/ │ ├── __init__.py │ ├── color.py # Core Color class │ ├── core.py # Parser and factory functions │ ├── converters.py # Color space conversions │ ├── constants.py # Named color constants │ ├── constants_colors.py # Pre-defined color constants │ ├── filters.py # Color filters │ ├── filter_base.py # Base filter classes │ └── utils.py # Utility functions ├── tests/ │ ├── test_color.py │ ├── test_core.py │ ├── test_converters.py │ ├── test_constants.py │ ├── test_filters.py │ ├── test_distance.py │ ├── test_color_formats.py │ └── test_utils.py ├── docs/ # Documentation ├── examples/ # Example scripts ├── pyproject.toml # Project configuration ├── pytest.ini # Test configuration └── README.md # Project README

Development Workflow

Making Changes

  1. Create a new branch for your changes:
1
git checkout -b feature/your-feature-name

  1. Make your changes following the coding standards

  2. Write or update tests for your changes

  3. Run tests to verify everything works:

1
pytest -v
  1. Check code coverage:
1
pytest --cov=colorium
  1. Format your code:
1
black src/ tests/
  1. Run linter:
1
flake8 src/ tests/
  1. Run type checker:
1
mypy src/
  1. Commit your changes:
1
2
git add .
git commit -m "feat: add your feature description"
  1. Push to your fork:
1
git push origin feature/your-feature-name
  1. Open a pull request

Commit Message Format

We follow conventional commits:

<type>(<scope>): <description> [optional body] [optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Code style
  • refactor: Refactoring
  • perf: Performance
  • test: Testing
  • chore: Maintenance

Example:

feat(filters): add vignette filter Adds VignetteFilter class for edge darkening effect. Supports configurable intensity and center position. Closes #123

Adding New Features

Adding a New Color Space

  1. Add conversion functions to converters.py:
1
2
3
4
5
6
7
def rgb_to_newspace(r, g, b):
    """Convert RGB to new color space"""
    return {'c1': ..., 'c2': ..., 'c3': ...}

def newspace_to_rgb(c1, c2, c3):
    """Convert new color space to RGB"""
    return {'r': ..., 'g': ..., 'b': ...}
  1. Add methods to Color class in color.py:
1
2
3
4
5
6
7
8
9
def to_newspace(self):
    """Convert to new color space"""
    return rgb_to_newspace(self.red, self.green, self.blue)

@classmethod
def from_newspace(cls, c1, c2, c3, opacity=1.0):
    """Create from new color space"""
    rgb = newspace_to_rgb(c1, c2, c3)
    return cls(rgb['r'], rgb['g'], rgb['b'], opacity)
  1. Add string conversion:
1
2
3
4
def to_newspace_string(self):
    """Convert to new color space string"""
    values = self.to_newspace()
    return f"newspace({values['c1']}, {values['c2']}, {values['c3']})"
  1. Add tests in tests/test_converters.py:
1
2
3
4
def test_rgb_to_newspace(self):
    """Test RGB to new space conversion"""
    result = rgb_to_newspace(255, 0, 0)
    assert result['c1'] == ...

Adding a New Filter

  1. Create filter class in filters.py:
1
2
3
4
5
6
7
8
9
10
class NewFilter(ColorFilter):
    """Apply new effect to a color"""

    def __init__(self, intensity=1.0):
        super().__init__(name=f"NewFilter({intensity})")
        self.intensity = clamp(intensity, 0.0, 1.0)

    def apply(self, color: Color) -> Color:
        # Implementation
        return Color(...)
  1. Add tests in tests/test_filters.py:
1
2
3
4
5
6
def test_new_filter(self):
    """Test new filter"""
    filter = NewFilter(0.5)
    color = Color(100, 150, 200)
    result = filter.apply(color)
    assert isinstance(result, Color)

Adding a New Named Color

  1. Add to COLOR_NAMES in constants.py:
1
2
3
4
COLOR_NAMES = [
    # ... existing names ...
    "NewColorName",
]
  1. Add corresponding hex to COLOR_HEXES:
1
2
3
4
COLOR_HEXES = [
    # ... existing hexes ...
    "123456",
]

Testing Guidelines

Writing Tests

  • Place tests in tests/ directory
  • Name test files with test_ prefix
  • Name test functions with test_ prefix
  • Use descriptive test names
  • Each test should be independent

Test Coverage

Aim for high test coverage:

1
2
pytest --cov=colorium --cov-report=html
# Open htmlcov/index.html in browser

Example Test

1
2
3
4
5
6
7
8
9
10
def test_new_feature(self):
    """Test description"""
    # Setup
    color = Color(255, 0, 0)

    # Execute
    result = color.new_method()

    # Assert
    assert result == expected_value

Documentation Guidelines

Docstrings

All public functions and classes must have docstrings:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
def function_name(param1: type, param2: type) -> return_type:
    """
    Brief description of what the function does.

    More detailed description if needed.

    Args:
        param1: Description of first parameter.
        param2: Description of second parameter.

    Returns:
        Description of return value.

    Example:
        >>> function_name(1, 2)
        3
    """
    pass

README Updates

Update README.md when adding new features or changing behavior.

Examples

Add examples to examples/ directory when adding new features:

1
2
3
4
5
6
# examples/new_feature.py
"""Example usage of new feature."""

from colorium import Color

# Example code here

Pull Request Process

Before Submitting

  1. Update your fork with upstream changes
  2. Run all tests
  3. Check code coverage
  4. Format code with Black
  5. Run linter
  6. Run type checker
  7. Update documentation

Pull Request Checklist

  • Code follows style guidelines
  • Tests pass locally
  • New features have tests
  • Documentation is updated
  • Commit messages follow conventions
  • PR description is clear and complete
  • All CI checks pass

PR Template

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
## Description

Brief description of the changes.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Other

## Testing

Describe how you tested your changes.

## Checklist

- [ ] I have read the CONTRIBUTING guide
- [ ] My code follows the style guidelines
- [ ] I have added tests that prove my fix/feature works
- [ ] I have updated the documentation
- [ ] All tests pass locally

## Related Issues

Closes #123

Release Process

Version Numbering

Follow Semantic Versioning:

  • MAJOR: Incompatible API changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Release Steps

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md
  3. Commit changes
  4. Create a GitHub release
  5. Build and publish to PyPI:
1
2
3
4
5
6
7
8
# Clean build
rm -rf dist/ build/ *.egg-info

# Build
python -m build

# Upload to PyPI
python -m twine upload dist/*

Getting Help

  • GitHub Issues: For bugs and feature requests
  • Discussions: For questions and discussions
  • Email: tryuzr@gmail.com

License

By contributing to Colorium, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Colorium! 🚀

On this page
34 sections