CONTRIBUTING.md

CONTRIBUTING.md

🛠️ Development Setup

This project uses uv for fast, reliable Python package management.

Prerequisites

• Python 3.11 or higher
• Git

Quick Start

1. Clone the repository

   git clone https://github.com/amithjkamath/template-matching.git
   cd template-matching
   

2. Run setup

   ./setup.sh
   

   Or if you prefer using Make:

   make setup
   

3. Run the app locally

   ./run_local.sh
   # or
   make run
   

Manual Setup

If you prefer to set things up manually:

1. Install uv (if not already installed)

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Install dependencies

   uv sync --no-build-isolation
   

3. Run the app

   uv run --no-build-isolation streamlit run app.py
   

Alternative Simple Method

If you encounter build-related issues, you can use a simpler approach:

# Install dependencies
uv pip install -r requirements.txt

# Run the app
uv run streamlit run app.py

📋 Available Commands

Using Shell Scripts

• ./setup.sh - Initial setup (install uv and dependencies)
• ./run_local.sh - Run the app locally
• ./deploy.sh - Deploy to HuggingFace Spaces

Using Makefile

• make help - Show all available commands
• make setup - Initial setup
• make install - Install/update dependencies
• make run - Run the app locally
• make deploy - Deploy to HuggingFace
• make clean - Clean up cache and temporary files
• make format - Format code (requires black)
• make lint - Run linting checks (requires ruff)
• make update - Update all dependencies
• make info - Show project information

🧪 Testing Locally

Before deploying, always test your changes locally:

1. Run the app: ./run_local.sh
2. Open your browser to http://localhost:8501
3. Test all interactive features
4. Check console for any errors

🚀 Deployment Process

The app is deployed to HuggingFace Spaces. To deploy:

1. Ensure all changes are committed

   git status
   git add .
   git commit -m "Your commit message"
   

2. Deploy

   ./deploy.sh
   # or
   make deploy
   

The script will:

• Check for uncommitted changes
• Push to the remote repository
• HuggingFace Spaces will automatically rebuild

📦 Dependency Management

Adding a new dependency

1. Add to pyproject.toml

   dependencies = [
       "new-package>=1.0.0",
       ...
   ]
   

2. Update requirements.txt (for HuggingFace Spaces)

   new-package>=1.0.0
   

3. Sync dependencies

   uv sync --no-build-isolation
   # or
   make install
   

Updating dependencies

uv sync --upgrade --no-build-isolation
# or
make update

🎨 Code Style

• Follow PEP 8 guidelines
• Use meaningful variable names
• Add docstrings to functions
• Keep functions focused and small

Formatting (optional)

Install formatting tools:

uv add --dev black ruff

Format code:

make format

Lint code:

make lint

📝 Making Changes

1. Create a new branch for your feature

   git checkout -b feature/your-feature-name
   

2. Make your changes

3. Test locally

   make run
   

4. Commit your changes

   git add .
   git commit -m "Description of changes"
   

5. Push and create a pull request (if working with others)

   git push origin feature/your-feature-name
   

6. Or merge to main and deploy

   git checkout main
   git merge feature/your-feature-name
   make deploy
   

🐛 Troubleshooting

Module not found error

If you see ModuleNotFoundError:

uv sync --no-build-isolation  # or make install
# Alternative:
uv pip install -r requirements.txt

Build backend errors

The project is configured to skip build steps. If you still encounter hatchling/build errors:

./run_simple.sh
# or use pip directly:
uv pip install -r requirements.txt
uv run streamlit run app.py

Port already in use

If port 8501 is already in use:

uv run --no-build-isolation streamlit run app.py --server.port 8502

uv not found

Make sure uv is in your PATH. After installation, restart your terminal or run:

source ~/.cargo/env

📚 Project Structure

template-matching/
├── app.py                 # Main Streamlit application
├── requirements.txt       # Dependencies for HuggingFace Spaces
├── pyproject.toml        # Python project configuration (uv)
├── Dockerfile            # Docker configuration for HF Spaces
├── packages.txt          # System packages for HF Spaces
├── README.md             # User-facing documentation
├── CONTRIBUTING.md       # This file - developer documentation
├── LICENSE               # MIT License
├── setup.sh              # Setup script
├── run_local.sh          # Local run script
├── deploy.sh             # Deployment script
├── Makefile             # Make commands for convenience
└── .gitignore           # Git ignore patterns

🤝 Contributing Guidelines

1. Keep the educational focus in mind
2. Maintain interactive and engaging features
3. Test thoroughly before deploying
4. Update documentation for any new features
5. Keep dependencies minimal and up-to-date

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.