Contributing to SpeakEasy

Thank you for your interest in contributing to SpeakEasy! This document provides guidelines and instructions for contributing to this open-source voice-to-text application.

Code of Conduct
Getting Started
Development Setup
How to Contribute
Coding Standards
Pull Request Process
Development Workflow
Project Structure

Code of Conduct

This project and everyone participating in it is governed by our commitment to:

Be respectful: Treat everyone with respect. Healthy debate is encouraged, but harassment is not tolerated.
Be constructive: Provide constructive feedback and be open to receiving it.
Be inclusive: Welcome newcomers and help them get started.
Focus on what's best: Make decisions that benefit the community and users.

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/speakeasy.git
cd speakeasy

Add upstream remote:

git remote add upstream https://github.com/bitgineer/speakeasy.git

Create a branch for your work:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Development Setup

Prerequisites

Python 3.10 - 3.12
Node.js 18+ (LTS)
FFmpeg in system PATH
UV package manager (pip install uv)
Git

Backend Setup

cd backend
uv venv --python 3.12
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Frontend Setup

cd gui
npm install

Running Tests

Backend:

cd backend
# Install dev dependencies
uv sync --extra dev

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ -v --cov=speakeasy --cov-report=html

# Run specific test file
uv run pytest tests/test_transcriberservice__set_state.py -v

Frontend:

cd gui
npm run lint
npm run typecheck

Testing Guidelines

We have 387 tests covering critical functionality:

Test Organization

P0 - Critical: Core functionality (state machine, transcription, history)
P1 - High: Important features (batch processing, exports)
P2 - Medium: Utilities and edge cases
P3 - Low: Legacy code and helpers

Writing Tests

Each function should have tests covering:
- Happy path / basic functionality
- Error handling and edge cases
- Invalid inputs

Use pytest fixtures for setup/teardown:

@pytest.fixture
async def initialized_service():
    service = HistoryService(db_path=tmp_path / "test.db")
    await service.initialize()
    yield service
    await service.close()

Mock external dependencies appropriately
Test both sync and async methods correctly

See TESTING_PLAN.md for the complete testing roadmap.

Pull Request Process

Update your branch with the latest upstream changes:
```
git fetch upstream
git rebase upstream/main
```

Ensure tests pass:

# Backend
cd backend && uv run pytest tests/ -v

# Frontend
cd gui && npm run lint && npm run typecheck

Frontend:

cd gui
npm test

How to Contribute

Reporting Bugs

Before creating a bug report, please:

Check existing issues to avoid duplicates
Use the latest version to verify the bug still exists
Collect information about the bug

When submitting a bug report, include:

Clear title and description
Steps to reproduce the issue
Expected behavior vs actual behavior
Environment details:
- OS and version
- Python version
- Node.js version
- GPU model (if applicable)
Error messages or logs
Screenshots (if applicable)

Use the Bug Report template when available.

Suggesting Features

Feature requests are welcome! When suggesting a feature:

Check existing issues to avoid duplicates
Describe the use case - what problem does it solve?
Explain the feature in detail
Consider alternatives you've evaluated
Be open to discussion about implementation

Use the Feature Request template when available.

Code Contributions

Finding Issues to Work On

Look for issues labeled good first issue or help wanted
Check the project roadmap
Comment on an issue before starting work to avoid conflicts

Types of Contributions

Bug fixes: Address issues in the codebase
Features: Implement new functionality
Documentation: Improve README, code comments, or guides
Tests: Add test coverage
Performance: Optimize existing code
Models: Add support for new AI models
UI/UX: Improve the user interface

Coding Standards

Python (Backend)

Follow PEP 8 style guide
Use type hints where appropriate
Write docstrings for functions and classes (Google style)
Maximum line length: 100 characters
Use Black for formatting: black backend/
Use isort for imports: isort backend/

Example:

def transcribe_audio(
    audio_path: str,
    model_name: str = "whisper-base",
    language: Optional[str] = None
) -> TranscriptionResult:
    """Transcribe audio file to text.
    
    Args:
        audio_path: Path to the audio file.
        model_name: Name of the model to use.
        language: Optional language code (e.g., 'en', 'es').
        
    Returns:
        TranscriptionResult containing text and metadata.
        
    Raises:
        FileNotFoundError: If audio file doesn't exist.
        ModelError: If model fails to load or process.
    """
    # Implementation

JavaScript/TypeScript (Frontend)

Use ESLint configuration provided
Use Prettier for formatting
Follow React best practices
Use functional components with hooks
Add JSDoc comments for complex functions

Example:

interface TranscriptionPanelProps {
  transcription: string;
  onCopy: () => void;
  isProcessing: boolean;
}

/**
 * Displays transcription results with copy functionality.
 */
export const TranscriptionPanel: React.FC<TranscriptionPanelProps> = ({
  transcription,
  onCopy,
  isProcessing
}) => {
  // Component implementation
};

General Guidelines

Keep functions small and focused on a single responsibility
Use meaningful variable names
Add comments for complex logic, but prefer self-documenting code
Write tests for new features and bug fixes
Update documentation when adding or changing features
Don't break existing functionality - maintain backwards compatibility

Pull Request Process

Update your branch with the latest upstream changes:
```
git fetch upstream
git rebase upstream/main
```

Ensure tests pass:

# Backend
cd backend && pytest

# Frontend
cd gui && npm test

Format your code:

# Backend
black backend/
isort backend/

# Frontend
cd gui && npm run lint

Commit your changes with clear messages:
```
git add .
git commit -m "feat: add support for Voxtral model

- Integrate Mistral Voxtral for complex dictation
- Add model selection UI
- Update documentation

Closes #123"
```
Commit message format:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes (formatting)
- refactor: Code refactoring
- test: Adding or updating tests
- chore: Maintenance tasks

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub:
- Use a clear title describing the change
- Fill out the PR template completely
- Link related issues with Closes #123 or Fixes #123
- Request review from maintainers
Address review feedback:
- Be responsive to comments
- Make requested changes in new commits
- Re-request review when ready

Development Workflow

Branch Naming

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation updates
refactor/description - Code refactoring
test/description - Test additions/updates
chore/description - Maintenance tasks

Before Submitting

Checklist:

Project Structure

speakeasy/
├── backend/              # Python FastAPI backend
│   ├── app/             # Application code
│   ├── models/          # AI model integrations
│   ├── tests/           # Test suite
│   └── pyproject.toml   # Python dependencies
├── gui/                 # Electron + React frontend
│   ├── src/             # Source code
│   ├── public/          # Static assets
│   └── package.json     # Node dependencies
├── docs/                # Documentation and images
├── scripts/             # Build and utility scripts
├── CONTRIBUTING.md      # This file
└── README.md           # Project overview

Getting Help

Discussions: Use GitHub Discussions for questions
Issues: For bugs and feature requests

Recognition

Contributors will be:

Listed in the project's contributors section
Mentioned in release notes for significant contributions
Given credit in documentation where appropriate

Thank you for contributing to SpeakEasy!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to SpeakEasy

Table of Contents

Code of Conduct

Getting Started

Development Setup

Prerequisites

Backend Setup

Frontend Setup

Running Tests

Testing Guidelines

Test Organization

Writing Tests

Pull Request Process

How to Contribute

Reporting Bugs

Suggesting Features

Code Contributions

Finding Issues to Work On

Types of Contributions

Coding Standards

Python (Backend)

JavaScript/TypeScript (Frontend)

General Guidelines

Pull Request Process

Development Workflow

Branch Naming

Before Submitting

Project Structure

Getting Help

Recognition

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to SpeakEasy

Table of Contents

Code of Conduct

Getting Started

Development Setup

Prerequisites

Backend Setup

Frontend Setup

Running Tests

Testing Guidelines

Test Organization

Writing Tests

Pull Request Process

How to Contribute

Reporting Bugs

Suggesting Features

Code Contributions

Finding Issues to Work On

Types of Contributions

Coding Standards

Python (Backend)

JavaScript/TypeScript (Frontend)

General Guidelines

Pull Request Process

Development Workflow

Branch Naming

Before Submitting

Project Structure

Getting Help

Recognition