Contributing

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

Getting Started

Prerequisites

Before contributing, ensure you have:

Python 3.7 or higher
Git installed
A GitHub account
Basic knowledge of OpenGL and Python

Fork and Clone

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/markxbrooks/picogl.git
cd picogl

Add upstream remote:

git remote add upstream https://github.com/markxbrooks/picogl.git

Create a feature branch:

git checkout -b feature/your-feature-name

Development Setup

Install Dependencies

Install in development mode:

pip install -e .[dev]

Install additional dependencies:

pip install -e .[dev,qt]

Verify installation:

python -c "import picogl; print('PicoGL installed successfully')"

Set Up Pre-commit Hooks

Install pre-commit:

pip install pre-commit

Install hooks:

pre-commit install

Run hooks manually:

pre-commit run --all-files

Development Workflow

Making Changes

Create a feature branch: .. code-block:: bash

git checkout -b feature/your-feature-name
Make your changes: - Write code following the style guidelines - Add tests for new functionality - Update documentation as needed
Test your changes: .. code-block:: bash

python -m unittest discover tests pytest tests/ –cov=picogl
Format and lint: .. code-block:: bash

black picogl/ tests/ flake8 picogl/ tests/ mypy picogl/ tests/
Commit your changes: .. code-block:: bash

git add . git commit -m “Add feature: brief description”
Push to your fork: .. code-block:: bash

git push origin feature/your-feature-name
Create a pull request on GitHub

Code Style

Formatting

PicoGL uses Black for code formatting:

Configuration:

[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'

Usage:

# Format all Python files
black picogl/ tests/

# Check formatting
black --check picogl/ tests/

Linting

PicoGL uses flake8 for linting:

Configuration:

[flake8]
max-line-length = 88
extend-ignore = E203, W503
exclude =
    .git,
    __pycache__,
    .venv,
    _build,
    dist

Usage:

# Lint all Python files
flake8 picogl/ tests/

Type Checking

PicoGL uses mypy for type checking:

Configuration:

[mypy]
python_version = 3.7
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
disallow_incomplete_defs = True
check_untyped_defs = True
disallow_untyped_decorators = True
no_implicit_optional = True
warn_redundant_casts = True
warn_unused_ignores = True
warn_no_return = True
warn_unreachable = True
strict_equality = True

Usage:

# Type check all Python files
mypy picogl/ tests/

Documentation

PicoGL uses Sphynx/RST-style docstrings:

Example:

def create_mesh_data(vertices, colors, normals=None):
    """Create mesh data from vertex information.

    :param vertices: Array of vertex positions (N, 3)
    :param colors: Array of vertex colors (N, 3)
    :param normals: Optional array of vertex normals (N, 3)
    :returns: MeshData: Mesh data object
    :raises: ValueError: If vertices or colors are invalid
            TypeError: If input types are incorrect
    """
    pass

Testing

Writing Tests

Test Structure:

class TestNewFeature(unittest.TestCase):
    def setUp(self):
        # Set up test data
        pass

    def tearDown(self):
        # Clean up test data
        pass

    def test_basic_functionality(self):
        """Test basic functionality."""
        # Arrange
        input_data = create_test_data()
        expected_result = create_expected_result()

        # Act
        actual_result = function_under_test(input_data)

        # Assert
        self.assertEqual(actual_result, expected_result)

    def test_edge_cases(self):
        """Test edge cases."""
        # Test edge cases
        pass

    def test_error_conditions(self):
        """Test error conditions."""
        # Test error conditions
        pass

Test Naming: * Use descriptive names * Include what is being tested * Include expected outcome

Test Documentation: * Document complex tests * Explain test purpose * Include expected behavior

Running Tests

Run all tests:

python -m unittest discover tests

Run specific test:

python -m unittest tests.test_new_feature

Run with coverage:

pytest tests/ --cov=picogl

Run with verbose output:

python -m unittest discover tests -v

Test Requirements

Coverage Requirements: * Overall: 80% * Critical modules: 90% * New code: 95%

Test Categories: * Unit tests for individual functions * Integration tests for component interactions * Performance tests for rendering * Compatibility tests for different platforms

Test Mocking: * Mock OpenGL functions * Mock external dependencies * Use test fixtures for common data

Documentation

Updating Documentation

API Documentation: * Update docstrings for new functions * Add examples for new features * Update type hints

User Documentation: * Update installation guide * Add new examples * Update troubleshooting guide

Developer Documentation: * Update development guide * Add architecture notes * Update contributing guide

Building Documentation

Build HTML documentation:

sphinx-build -b html doc/ doc/_build/html

Build PDF documentation:

sphinx-build -b latex doc/ doc/_build/latex
cd doc/_build/latex && make

View documentation:

open doc/_build/html/index.html

Pull Request Process

Creating Pull Requests

Ensure your branch is up to date: .. code-block:: bash

git fetch upstream git rebase upstream/main
Push your changes: .. code-block:: bash

git push origin feature/your-feature-name
Create pull request on GitHub: - Use descriptive title - Provide detailed description - Link to related issues - Include screenshots if applicable
Wait for review: - Address review comments - Make requested changes - Update tests if needed

Pull Request Template

Title: Brief description of changes

Description: * What changes were made * Why changes were made * How changes were tested * Any breaking changes

Checklist: * [ ] Code follows style guidelines * [ ] Tests cover new functionality * [ ] Documentation is updated * [ ] No breaking changes * [ ] Performance impact considered * [ ] Cross-platform compatibility maintained

Review Process

Review Criteria: * Code quality and style * Test coverage and quality * Documentation completeness * Performance impact * Compatibility considerations

Review Timeline: * Initial review within 1 week * Follow-up reviews as needed * Final approval from maintainers

Addressing Reviews: * Respond to all comments * Make requested changes * Ask questions if unclear * Update tests if needed

Types of Contributions

Bug Fixes

Reporting Bugs: * Use GitHub issues * Provide detailed information * Include steps to reproduce * Attach relevant files

Fixing Bugs: * Create bug fix branch * Write tests for the bug * Fix the issue * Verify fix with tests

Bug Fix Template:

**Bug Description**: Brief description of the bug
**Steps to Reproduce**:
1. Step 1
2. Step 2
3. Step 3
**Expected Behavior**: What should happen
**Actual Behavior**: What actually happens
**Environment**: OS, Python version, etc.
**Additional Context**: Any other relevant information

Feature Requests

Requesting Features: * Use GitHub issues * Provide detailed description * Explain use case * Consider implementation complexity

Implementing Features: * Create feature branch * Write comprehensive tests * Update documentation * Consider backward compatibility

Feature Request Template:

**Feature Description**: Brief description of the feature
**Use Case**: Why is this feature needed
**Proposed Solution**: How should it work
**Alternatives**: Other approaches considered
**Additional Context**: Any other relevant information

Documentation Improvements

Types of Documentation: * API documentation * User guides * Examples * Tutorials * Troubleshooting guides

Improving Documentation: * Fix typos and errors * Add missing information * Improve clarity * Add examples

Documentation Template:

**Documentation Type**: API/User/Example/etc.
**Section**: Which section needs improvement
**Current State**: What's wrong or missing
**Proposed Changes**: What should be changed
**Additional Context**: Any other relevant information

Performance Improvements

Performance Issues: * Identify bottlenecks * Measure current performance * Propose optimizations * Test performance impact

Performance Improvements: * Profile code * Implement optimizations * Add performance tests * Measure improvements

Performance Template:

**Performance Issue**: What is slow
**Current Performance**: Measured performance
**Proposed Optimization**: How to improve
**Expected Improvement**: Expected performance gain
**Additional Context**: Any other relevant information

Code Quality Improvements

Code Quality Issues: * Identify code smells * Refactor complex code * Improve readability * Add type hints

Code Quality Improvements: * Refactor code * Add type hints * Improve documentation * Add tests

Code Quality Template:

**Code Quality Issue**: What needs improvement
**Current State**: Current code quality
**Proposed Changes**: How to improve
**Expected Benefits**: What will be improved
**Additional Context**: Any other relevant information

Community Guidelines

Code of Conduct

Be Respectful: * Use welcoming and inclusive language * Be respectful of differing viewpoints * Accept constructive criticism gracefully

Be Collaborative: * Focus on what is best for the community * Show empathy towards other community members * Help others learn and grow

Be Professional: * Use appropriate language * Be constructive in feedback * Follow project guidelines

Communication

GitHub Issues: * Use for bug reports and feature requests * Provide detailed information * Be responsive to questions

GitHub Discussions: * Use for general questions * Share ideas and feedback * Help other community members

Pull Requests: * Use for code contributions * Provide detailed descriptions * Be responsive to reviews

Email: * Use for sensitive issues * Contact maintainers directly * Use appropriate subject lines

Getting Help

Documentation: * Check the documentation first * Look for similar issues * Read the troubleshooting guide

Community: * Ask questions on GitHub Discussions * Search existing issues * Join community discussions

Maintainers: * Contact maintainers for urgent issues * Use appropriate communication channels * Be patient with responses

Resources: * OpenGL documentation * Python documentation * PyOpenGL documentation * Platform-specific guides

Recognition

Contributors: * All contributors are recognized * Contributors are listed in README * Significant contributions are highlighted

Types of Contributions: * Code contributions * Documentation improvements * Bug reports * Feature requests * Community help

Recognition Process: * Automatic recognition for contributions * Manual recognition for significant contributions * Regular contributor spotlights

Thank you for contributing to PicoGL! Your contributions help make the project better for everyone.