Contributing

Contributing

Guide for contributing to Subtide development.

---

Getting Started

Prerequisites

• Node.js 18+
• Python 3.9+
• FFmpeg
• Git

Clone Repository

git clone https://github.com/rennerdo30/subtide.git
cd subtide

---

Development Setup

Backend

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

# 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

graph TD
    Root[subtide/]

    Root --> Backend[backend/<br/><i>Python Flask server</i>]
    Root --> Extension[extension/<br/><i>Chrome Extension</i>]
    Root --> Docs[docs/<br/><i>Documentation</i>]
    Root --> GitHub[.github/<br/><i>CI/CD workflows</i>]

    Backend --> AppPy[app.py<br/><i>Entry point</i>]
    Backend --> ConfigPy[config.py<br/><i>Configuration</i>]
    Backend --> Routes[routes/<br/><i>API endpoints</i>]
    Backend --> Services[services/<br/><i>Business logic</i>]
    Backend --> Utils[utils/<br/><i>Utilities</i>]
    Backend --> Tests[tests/<br/><i>Test suite</i>]

    Extension --> Manifest[manifest.json]
    Extension --> Src[src/]
    Extension --> Locales[_locales/<br/><i>Translations</i>]

    Src --> Background[background/<br/><i>Service worker</i>]
    Src --> Content[content/<br/><i>Content scripts</i>]
    Src --> Popup[popup/<br/><i>Extension popup</i>]
    Src --> Lib[lib/<br/><i>Shared utilities</i>]

    style Root fill:#f97316,stroke:#ea580c,color:#fff
    style Backend fill:#22d3ee,stroke:#0891b2,color:#000
    style Extension fill:#22d3ee,stroke:#0891b2,color:#000
    style Docs fill:#94a3b8,stroke:#64748b,color:#000
    style GitHub fill:#94a3b8,stroke:#64748b,color:#000

---

Running Tests

Backend Tests

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

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

---

Code Style

Python (Backend)

• Follow PEP 8
• Use type hints where practical
• Maximum line length: 100 characters

JavaScript (Extension)

• Use ES6+ features
• No external dependencies (vanilla JS)
• Use JSDoc comments for complex functions

---

Making Changes

1. Create a Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

• Write code
• Add tests
• Update documentation if needed

3. Run Tests

cd backend
pytest

4. Commit

git add .
git commit -m "Add feature: description"

5. Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

---

Pull Request Guidelines

Before Submitting

• All tests pass
• Code follows style guidelines
• Documentation updated (if applicable)
• Commit messages are clear

PR Description

Include:

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

---

Reporting Issues

Bug Reports

Include:

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

Feature Requests

Include:

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

---

Architecture Decisions

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

• Flask: Simple, well-documented
• Gunicorn: Production-ready server
• Multiple Whisper backends: Support different hardware

---

Areas for Contribution

Good First Issues

• Documentation improvements
• Bug fixes
• Test coverage
• Localization (new languages)

Larger Projects

• Safari extension support
• Additional video platforms
• Performance optimizations
• UI/UX improvements

---

Community

• GitHub Issues - Bug reports, feature requests
• GitHub Discussions - Questions, ideas

---

License

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