How to contribute

Whisper is a small repository with a clear surface: it ships pretrained model weights, the inference pipeline that runs them, and a CLI. Contributions are mostly bug fixes, compatibility updates (newer PyTorch / Numpy / Triton), small features in transcribe() (e.g. clip timestamps, carry-initial-prompt, hallucination silence skipping), or model card updates.

There is no CONTRIBUTING.md in this repository, so the conventions here are inferred from the commit history, CI configuration, and pre-commit hooks.

Pickup points

Look for issues and PRs on GitHub Issues and Pull Requests. Realistic places to make changes:

• whisper/transcribe.py — adding CLI flags, output options, segment-loop heuristics. This file moves the most.
• whisper/decoding.py — sampling/beam-search behavior, logit filters, timestamp constraints.
• whisper/utils.py — new ResultWriter subclasses for additional transcript formats.
• whisper/normalizers/ — only when you are reproducing or extending the paper's evaluation. Not on the inference path.
• tests/ — every behavior change should come with a test exercising it (see Testing).

PR mechanics

• Branch from main. The release workflow (.github/workflows/python-publish.yml) publishes to PyPI on commits to main whose message starts with Release vYYYYMMDD, so do not write that exact prefix in normal commits.
• Open a pull request against openai/whisper:main. CI (.github/workflows/test.yml) runs pre-commit plus a 9-cell PyTorch matrix.
• The two most recent commits on the branch (Mar–Apr 2026) pin GitHub Actions and pre-commit hooks to immutable commit hashes — when bumping a hook or action, update the comment that names the human-readable version too.

Definition of done

Before a PR is mergeable, expect the following:

1. Lint clean: pre-commit run --all-files passes (black, isort, flake8, end-of-file fixer, trailing whitespace, mixed line endings, large-file check).
2. Tests pass: at minimum pytest -m 'not requires_cuda' -k 'not test_transcribe or test_transcribe[tiny] or test_transcribe[tiny.en]'. Full transcribe matrix is too large for routine CI.
3. Behavior change is exercised by a test: add to or extend tests/test_*.py with a focused test. See Testing.
4. Backward compatibility: the CLI flags and Python API in whisper/__init__.py are public surface. Don't remove or rename without good reason.
5. No unrelated formatting churn: black will reformat what it touches, but try not to reflow files you are not actually changing.

Where to look next

• Development workflow: branch / commit / PR cycle.
• Testing: how to run tests, what's marked requires_cuda, how the JFK fixture is used.
• Patterns and conventions: coding patterns used across the codebase.
• Tooling: the build/CI/pre-commit setup.