Contributing to MGT-python

We welcome contributions to the Musical Gestures Toolbox for Python! This guide will help you get started with contributing to the project.

Getting Started

Fork and Clone

Fork the repository on GitHub: https://github.com/fourMs/MGT-python

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/MGT-python.git
cd MGT-python

Add upstream remote:

git remote add upstream https://github.com/fourMs/MGT-python.git

Development Environment

Set up virtual environment

# Create virtual environment
python -m venv mgt-dev
source mgt-dev/bin/activate  # Linux/macOS
# mgt-dev\Scripts\activate   # Windows

# Install in development mode
pip install -e .

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

Development Dependencies

# Testing
pip install pytest pytest-cov

# Code quality
pip install black flake8 isort mypy

# Documentation
pip install mkdocs mkdocs-material mkdocstrings[python]

# Optional: Jupyter for notebook development
pip install jupyter notebook

Development Workflow

1. Create a Feature Branch

Always work on a feature branch, never directly on master:

git checkout master
git pull upstream master
git checkout -b feature/your-feature-name

2. Make Your Changes

Follow the coding standards and patterns established in the codebase:

Code Style Guidelines

PEP 8 compliance for Python code
4 spaces for indentation (no tabs)
Line length: Maximum 88 characters (Black default)
Imports: Group and sort imports using isort
Docstrings: Use Google-style docstrings

Example Function Documentation

def mg_example_function(video_path, param1=None, param2=False):
    """
    Brief description of the function.
    
    Longer description explaining what the function does,
    how it works, and any important details.
    
    Args:
        video_path (str): Path to the input video file.
        param1 (int, optional): Description of param1. Defaults to None.
        param2 (bool, optional): Description of param2. Defaults to False.
        
    Returns:
        dict: Dictionary containing:
            - 'output_path': Path to generated output file
            - 'data': Processed data array
            
    Raises:
        FileNotFoundError: If video_path does not exist.
        ValueError: If param1 is negative.
        
    Example:
        >>> result = mg_example_function('video.mp4', param1=10)
        >>> print(result['output_path'])
        'video_processed.mp4'
    """
    # Implementation here
    pass

3. Code Quality Checks

Before committing, run these checks:

Formatting

# Format code with Black
black musicalgestures/

# Sort imports
isort musicalgestures/

# Check formatting
black --check musicalgestures/
isort --check-only musicalgestures/

Linting

# Check code style
flake8 musicalgestures/

# Type checking (optional but recommended)
mypy musicalgestures/

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=musicalgestures tests/

# Run specific test file
pytest tests/test_video.py

# Run specific test
pytest tests/test_video.py::test_video_loading

4. Add Tests

All new functionality should include tests. Add tests to the appropriate file in the tests/ directory:

Test Structure

import pytest
import musicalgestures as mg
from pathlib import Path


class TestNewFeature:
    """Test suite for new feature."""
    
    def test_basic_functionality(self):
        """Test basic functionality works as expected."""
        # Arrange
        video_path = mg.examples.dance
        
        # Act
        result = mg.new_feature(video_path)
        
        # Assert
        assert result is not None
        assert Path(result['output_path']).exists()
    
    def test_error_handling(self):
        """Test that errors are handled appropriately."""
        with pytest.raises(FileNotFoundError):
            mg.new_feature('nonexistent_file.mp4')
    
    def test_parameter_validation(self):
        """Test parameter validation."""
        video_path = mg.examples.dance
        
        # Test invalid parameter
        with pytest.raises(ValueError):
            mg.new_feature(video_path, invalid_param=-1)

5. Update Documentation

Docstrings

Ensure all new functions and classes have proper docstrings following the Google style.

User Documentation

If adding user-facing features, update the relevant documentation files:

docs/user-guide/ - User guide sections
docs/examples.md - Add usage examples
docs/api-reference/ - API documentation (auto-generated from docstrings)

Changelog

Add entry to CHANGELOG.md (if it exists) or prepare release notes.

6. Commit Your Changes

Commit Message Format

Use clear, descriptive commit messages:

# Good commit messages
git commit -m "Add optical flow visualization method"
git commit -m "Fix memory leak in video processing"
git commit -m "Update documentation for audio analysis"

# Include issue references when applicable
git commit -m "Fix video loading issue (#123)"

Commit Best Practices

Make atomic commits (one logical change per commit)
Write descriptive commit messages
Reference issues in commit messages when applicable

Types of Contributions

Bug Fixes

Check existing issues - Make sure the bug hasn't been reported
Create an issue if one doesn't exist
Fix the bug and add a test to prevent regression
Reference the issue in your pull request

New Features

Discuss the feature by creating an issue first
Follow existing patterns in the codebase
Add comprehensive tests
Update documentation
Consider backward compatibility

Documentation Improvements

Fix typos and grammatical errors
Improve existing documentation clarity
Add missing documentation
Create new examples and tutorials
Improve code comments

Examples and Tutorials

Create Jupyter notebooks demonstrating features
Add real-world use cases
Improve existing examples
Add visualizations and plots

Pull Request Process

1. Prepare Your Pull Request

Before creating a PR:

# Sync with upstream
git checkout master
git pull upstream master

# Rebase your feature branch
git checkout feature/your-feature-name
git rebase master

# Run all checks
black musicalgestures/
isort musicalgestures/
flake8 musicalgestures/
pytest

2. Create Pull Request

Title: Clear, descriptive title
Description: Explain what changes were made and why
Testing: Describe how the changes were tested
Documentation: Note any documentation updates
Issues: Reference any related issues

PR Template Example

## Description
Brief description of changes made.

## Changes Made
- Added new feature X
- Fixed bug Y  
- Updated documentation Z

## Testing
- [ ] All existing tests pass
- [ ] Added new tests for new functionality
- [ ] Tested manually with sample videos

## Documentation
- [ ] Updated docstrings
- [ ] Updated user guide
- [ ] Added examples

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated

3. Review Process

Automated checks must pass (CI/CD)
Code review by maintainers
Address feedback promptly
Update PR as needed

Code Organization

File Structure

musicalgestures/
├── __init__.py              # Package initialization
├── _video.py               # Video processing (MgVideo class)
├── _audio.py               # Audio processing (MgAudio class)
├── _flow.py                # Optical flow analysis
├── _utils.py               # Utility functions
├── _motionvideo.py         # Motion video creation
├── _motiongrams.py         # Motiongram generation
└── ...                     # Other specialized modules

Naming Conventions

Files: Use underscore prefix for internal modules (_video.py)
Classes: PascalCase (MgVideo, MgAudio)
Functions: snake_case (mg_motion_video, create_motiongram)
Variables: snake_case (frame_count, output_path)
Constants: UPPER_CASE (DEFAULT_THRESHOLD, MAX_FRAMES)

Testing Guidelines

Test Categories

Unit Tests: Test individual functions/methods
Integration Tests: Test component interactions
End-to-End Tests: Test complete workflows
Performance Tests: Test with large files (optional)

Test Data

Use the built-in example videos for consistency:

import musicalgestures as mg

# Use example videos in tests
video_path = mg.examples.dance
audio_path = mg.examples.pianist

Mocking External Dependencies

For tests that don't require actual video processing:

from unittest.mock import patch, MagicMock

@patch('musicalgestures._video.cv2.VideoCapture')
def test_video_loading(mock_cv2):
    # Mock OpenCV video capture
    mock_cap = MagicMock()
    mock_cv2.return_value = mock_cap
    
    # Test the functionality
    mv = mg.MgVideo('fake_video.mp4')
    # Assert expected behavior

Release Process

Version Numbering

MGT-python follows semantic versioning (SemVer):

Major (X.0.0): Breaking changes
Minor (0.X.0): New features, backward compatible
Patch (0.0.X): Bug fixes, backward compatible

Release Checklist

Update version in setup.py
Update CHANGELOG.md
Create release tag
Build and upload to PyPI
Update documentation

Getting Help

Communication Channels

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Email: a.r.jensenius@imv.uio.no (maintainer)

Resources

fourMs Lab: https://github.com/fourMs
RITMO Centre: https://www.uio.no/ritmo/english/
Documentation: https://mgt-python.readthedocs.io/

Code of Conduct

Be respectful and inclusive
Focus on constructive feedback
Help others learn and grow
Follow the project's coding standards
Credit others for their contributions

Thank you for contributing to MGT-python! 🎵🎥

FilesExpand file tree

contributing.md

Latest commit

History