Contributing to Movie Recommendation System

Thank you for your interest in contributing! This document provides guidelines for contributing to this project.

🚀 Getting Started

Development Setup

Fork and clone the repository

git clone https://github.com/YOUR_USERNAME/movie-recommendation-system.git
cd movie-recommendation-system

Create a virtual environment

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

Install dependencies

pip install numpy pandas scipy scikit-learn scikit-surprise requests
pip install pytest pytest-cov black flake8 mypy

Verify the setup
```
PYTHONPATH=src pytest tests/ -v
```

📝 How to Contribute

Reporting Bugs

Check if the issue already exists
Use the bug report template
Include Python version, OS, and error messages
Provide minimal reproduction steps

Suggesting Features

Open an issue with the feature request template
Explain the use case and expected behavior
Be open to discussion about implementation

Submitting Code

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes following our code style
Add tests for new functionality
Run the test suite
```
PYTHONPATH=src pytest tests/ -v
```
Format your code
```
black src/ tests/
flake8 src/ tests/
```

Commit with a descriptive message

git commit -m "feat: add new diversity metric"

Push and create a Pull Request

📋 Code Style

Formatter: Black with 100 character line length
Linter: Flake8
Type hints: Use type annotations for function signatures
Docstrings: Google style docstrings for all public functions

Example

def recommend(
    self,
    user_id: int,
    n: int = 10,
    exclude_seen: bool = True,
) -> List[Tuple[int, float]]:
    """
    Get top-N recommendations for a user.
    
    Args:
        user_id: User identifier
        n: Number of recommendations to return
        exclude_seen: Whether to exclude already-rated items
        
    Returns:
        List of (item_id, score) tuples sorted by score descending
    """
    ...

🧪 Testing

Write tests for all new functionality
Maintain test coverage above 80%
Use descriptive test names
Follow the existing test structure

# Run all tests
PYTHONPATH=src pytest tests/ -v

# Run with coverage
PYTHONPATH=src pytest tests/ --cov=src/movie_recommender

# Run specific test
PYTHONPATH=src pytest tests/test_models.py::TestHybridRecommender -v

📁 Project Structure

When adding new features, follow the existing structure:

src/movie_recommender/models/ - New recommendation algorithms
src/movie_recommender/evaluation/ - New metrics
src/movie_recommender/data/ - New data loaders
tests/ - Corresponding test files

🎯 Areas for Contribution

New Algorithms: Graph-based models, deep learning approaches
Fairness Features: Bias detection and mitigation
Performance: Scalability improvements
Documentation: Tutorials, examples
Testing: Edge cases, integration tests

📬 Contact

Open an issue for questions
Tag maintainers in PRs for review

Thank you for contributing! 🎬

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History