Skip to content
Subtide

Contributing

Contributing

Section titled “Contributing”

Guide for contributing to Subtide development.

Getting Started

Section titled “Getting Started”

Prerequisites

Section titled “Prerequisites”
  • Node.js 18+
  • Python 3.9+
  • FFmpeg
  • Git

Clone Repository

Section titled “Clone Repository”
Terminal window
git clone https://github.com/rennerdo30/subtide.git
cd subtide

Development Setup

Section titled “Development Setup”

Backend

Section titled “Backend”
Terminal window
cd backend


# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate


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


# Run development server
./run.sh

Extension

Section titled “Extension”
Terminal window
# No build step required - extension uses vanilla JS


# Load in Chrome:
# 1. Go to chrome://extensions
# 2. Enable Developer mode
# 3. Load unpacked → select 'extension' folder

Project Structure

Section titled “Project Structure”
subtide/
├── backend/                 # Python Flask server
│   ├── app.py               # Entry point
│   ├── config.py            # Configuration
│   ├── routes/              # API endpoints
│   ├── services/            # Business logic
│   ├── utils/               # Utilities
│   └── tests/               # Test suite
│
├── extension/               # Chrome Extension
│   ├── manifest.json        # Extension manifest
│   ├── src/
│   │   ├── background/      # Service worker
│   │   ├── content/         # Content scripts
│   │   ├── popup/           # Extension popup
│   │   └── lib/             # Shared utilities
│   └── _locales/            # Translations
│
├── docs/                    # Documentation (MkDocs)
└── .github/                 # CI/CD workflows

Running Tests

Section titled “Running Tests”

Backend Tests

Section titled “Backend Tests”
Terminal window
cd backend


# Run all tests
pytest


# With coverage
pytest --cov=. --cov-report=term-missing


# Specific test file
pytest tests/test_translation.py


# Verbose output
pytest -v

Test Coverage Goal

Section titled “Test Coverage Goal”

We aim for close to 100% test coverage. All new features and bug fixes should include tests.

Code Style

Section titled “Code Style”

Python (Backend)

Section titled “Python (Backend)”
  • Follow PEP 8
  • Use type hints where practical
  • Maximum line length: 100 characters

JavaScript (Extension)

Section titled “JavaScript (Extension)”
  • Use ES6+ features
  • No external dependencies (vanilla JS)
  • Use JSDoc comments for complex functions

Making Changes

Section titled “Making Changes”

1. Create a Branch

Section titled “1. Create a Branch”
Terminal window
git checkout -b feature/your-feature-name

2. Make Your Changes

Section titled “2. Make Your Changes”
  • Write code
  • Add tests
  • Update documentation if needed

3. Run Tests

Section titled “3. Run Tests”
Terminal window
cd backend
pytest

4. Commit

Section titled “4. Commit”
Terminal window
git add .
git commit -m "Add feature: description"

5. Push and Create PR

Section titled “5. Push and Create PR”
Terminal window
git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Pull Request Guidelines

Section titled “Pull Request Guidelines”

Before Submitting

Section titled “Before Submitting”
  • All tests pass
  • Code follows style guidelines
  • Documentation updated (if applicable)
  • Commit messages are clear

PR Description

Section titled “PR Description”

Include:

  • What the PR does
  • Why the change is needed
  • How to test it
  • Screenshots (for UI changes)

Reporting Issues

Section titled “Reporting Issues”

Bug Reports

Section titled “Bug Reports”

Include:

  • Browser and version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages
  • Screenshots if applicable

Feature Requests

Section titled “Feature Requests”

Include:

  • Clear description of the feature
  • Use case / why it’s needed
  • Any implementation ideas

Architecture Decisions

Section titled “Architecture Decisions”

Extension

Section titled “Extension”
  • Manifest V3: Required for modern Chrome extensions
  • Vanilla JS: No build step, easier debugging
  • Content Scripts: Separate scripts per platform (YouTube, Twitch, generic)

Backend

Section titled “Backend”
  • Flask: Simple, well-documented
  • Gunicorn: Production-ready server
  • Multiple Whisper backends: Support different hardware

Areas for Contribution

Section titled “Areas for Contribution”

Good First Issues

Section titled “Good First Issues”
  • Documentation improvements
  • Bug fixes
  • Test coverage
  • Localization (new languages)

Larger Projects

Section titled “Larger Projects”
  • Safari extension support
  • Additional video platforms
  • Performance optimizations
  • UI/UX improvements

Community

Section titled “Community”

License

Section titled “License”

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