How to contribute

Found a bug? Have a feature to suggest? Want to contribute code? Read this first.

Bug reporting

  1. Make sure your bug is not already fixed — update to the current master branch.

  2. Search existing issues (including closed ones) for the same problem. If it is new, open an issue on GitHub.

  3. Give us the information we need to reproduce it: your OS, Python version, how you ran the flow (locally with LocalProcessEngine or on Kubernetes), your NATS server version, and — if GPU-related — your CUDA/driver versions and GPU model.

  4. Provide a minimal, runnable script that reproduces the issue. It should not require downloading external data — use IntProducer or randomly generated arrays where possible. A small flow that fails is far easier to diagnose than a full application.

The more information you provide, the faster we can help.

Requesting a feature

Open a GitHub issue with a clear explanation of the feature and why it is broadly useful, and code snippets demonstrating the API you have in mind. If it targets a narrow use case, consider an add-on in videoflow-contrib instead.

Development setup

Videoflow uses uv for packaging and environments:

git clone https://github.com/videoflow/videoflow.git
cd videoflow
uv sync              # creates .venv with all dependencies, including dev tools

The test suite needs a running NATS JetStream server:

docker compose up -d          # or: nats-server -js
uv run pytest tests/

Pull requests

Improvements and bug fixes go to the master branch. A good PR:

  1. Adds proper docstrings to any new function or class, and keeps touched code’s docstrings up to date. Docstrings use sections for Arguments, Returns and Raises where applicable.

  2. Includes tests. Pure logic (serialization, compilation, manifest generation) is covered by unit tests; end-to-end behavior is covered by integration tests that run small flows against a local NATS server.

  3. Passes the full suite locally: uv run pytest tests/.

  4. Uses clear, descriptive commit messages.

  5. Updates the documentation, including runnable snippets for new features.

Adding examples

Even without touching the core, if you have a concise, powerful Videoflow application, consider adding it to the examples folder. Each example should expose a build_flow() factory so it can be both run locally and deployed with videoflow deploy.