Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
185 lines (134 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

185 lines (134 loc) · 4.59 KB

Contributing to VLog

Thank you for your interest in contributing to VLog! This document provides guidelines and instructions for contributing.

Branching Strategy

VLog uses a two-branch development model:

Branch Purpose
dev Active development (default branch)
main Stable releases only

Workflow

  1. Feature development: Create branches from dev, submit PRs to dev
  2. Quick feedback: PRs to dev run a fast test suite (skips slow integration tests)
  3. Releases: Periodically, dev is merged to main after full test suite passes
  4. Hotfixes: Critical fixes can go directly to main if needed

Which branch should I target?

  • Most contributions: Target dev (the default)
  • Documentation-only changes: Either dev or main is fine
  • Critical security fixes: Discuss with maintainers first

Getting Started

Development Setup

  1. Clone the repository

    git clone https://github.com/filthyrake/vlog.git
cd vlog

  2. Create a virtual environment

    python3 -m venv venv
source venv/bin/activate

  3. Install in development mode

    pip install -e ".[dev]"

  4. Initialize the database

    python api/database.py

  5. Start development servers

    ./start.sh

Running Tests

Tests require VLOG_TEST_MODE=1 to avoid NAS directory creation:

# Run all tests
VLOG_TEST_MODE=1 pytest

# Run with coverage
VLOG_TEST_MODE=1 pytest --cov=api --cov=worker --cov=cli

# Run specific test file
VLOG_TEST_MODE=1 pytest tests/test_public_api.py

# Run tests matching pattern
VLOG_TEST_MODE=1 pytest -k "test_upload"

Code Style

We use Ruff for linting and formatting:

# Check for issues
VLOG_TEST_MODE=1 ruff check api/ worker/ cli/ tests/ config.py

# Auto-format code
ruff format api/ worker/ cli/ tests/ config.py

How to Contribute

Reporting Bugs

  1. Check existing issues to avoid duplicates
  2. Use the bug report template when creating a new issue
  3. Include:
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (OS, Python version, etc.)
    • Relevant logs

Suggesting Features

  1. Check existing issues and discussions first
  2. Use the feature request template
  3. Describe the use case and why it would be valuable

Submitting Pull Requests

  1. Fork and branch from dev

    git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

  2. Make your changes

    • Follow existing code style
    • Add tests for new functionality
    • Update documentation as needed

  3. Test your changes

    # Run quick tests (same as CI for dev branch)
VLOG_TEST_MODE=1 pytest \
  --ignore=tests/test_workflows.py \
  --ignore=tests/test_worker_integration.py \
  --ignore=tests/test_transcoder_integration.py \
  --ignore=tests/test_e2e_upload.py \
  --ignore=tests/test_transcoder.py

# Run linting
VLOG_TEST_MODE=1 ruff check api/ worker/ cli/ tests/ config.py

# Optional: Run full test suite
VLOG_TEST_MODE=1 pytest

  4. Commit with clear messages

    git commit -m "Add feature: brief description"

  5. Push and create PR targeting dev

    • PRs automatically target dev (the default branch)
    • Reference any related issues
    • Describe what your PR does and why

Pull Request Guidelines

  • Keep PRs focused on a single change
  • Ensure all tests pass
  • Ensure linting passes
  • Update documentation for user-facing changes
  • Add tests for new features or bug fixes

Code Guidelines

Python Version

This project uses Python 3.9+. Use Optional[T] instead of T | None union syntax for compatibility.

Project Structure

  • api/ - FastAPI backend (public, admin, worker APIs)
  • worker/ - Background transcoding workers
  • cli/ - Command-line interface
  • web/ - Frontend (Alpine.js + Tailwind CSS)
  • tests/ - pytest test suite
  • docs/ - Documentation

Key Patterns

  • Async/await: All database operations are async
  • Pydantic models: Request/response validation in api/schemas.py
  • SQLAlchemy: Database operations in api/database.py
  • Environment config: All settings configurable via VLOG_* env vars

Getting Help

License

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