Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (82 loc) · 6.23 KB

CONTRIBUTING.md

File metadata and controls

115 lines (82 loc) · 6.23 KB

Contributing to oak-examples

Thanks for your interest in contributing to oak-examples! We welcome contributions of all kinds — from bug fixes and small tweaks to full-featured examples demonstrating new or advanced uses of OAK devices.

What’s in this repository

oak-examples contains a broad collection of demonstrations, tutorials, and application code for running inference, depth measurement, streaming, custom front-ends, integrations, camera control, and more on OAK / DepthAI devices. Generally, each example lives in its own directory, and similar examples are grouped together under higher-level categories (e.g., apps, tutorials, etc.).

The main branch contains examples using DepthAIv3 (and all the new components that come with it), whereas the master branch contains legacy examples built on DepthAIV2.

How to contribute

We follow a standard GitHub workflow: fork the repository, create a new branch for your changes, then submit a pull request. This avoids disrupting stable code and ensures maintainers can review changes before merging.

Setup

  • Clone the repository locally.
    • Consider using the --depth 1 flag to create a lightweight clone, as the full repo is quite large.
      Example: 
      git clone --depth 1 --branch main https://github.com/luxonis/oak-examples.git
  • Create a new branch describing your change. Common branch prefixes:
    • feat/... for new features
    • fix/... for fixes
    • test/... for tests
  • Install development tools, including pre-commit: 
    pip install -r requirements-dev.txt

Making changes

Fixes

If you are fixing an existing example or file, implement the fix, then proceed to the Testing section.

Adding a New Example

When adding a new example, first determine the most appropriate location for it. Try to place it under one of the existing top-level categories unless it introduces a fundamentally new category — in that case, propose the category in your PR.

Guidelines for adding a new example to the main branch:

  • The example’s directory name should be concise yet descriptive. Use kebab-case formatting (e.g., new-example).
  • The example should use DepthAIv3.
  • Use the visualizer (a DepthAIv3 component) for visualization unless that is not feasible, in which case you may fall back to OpenCV or another visualization tool.
  • Each example must include:
    • requirements.txt — listing all required packages.
      • We recommend pinning at least DepthAI (and DepthAI-Nodes if used) to the latest known-working version to avoid breakage from future updates.
    • main.py — the entry point for running the example.
  • Each example must include a GIF or a screenshot demonstrating its behavior.
    • Store all media in the /media folder.
    • Keep media size minimal while still effectively demonstrating the example.
    • Aim to keep the entire folder size below 10 MB.
  • Each example must include a README.md with the following general structure (see default-app README for reference):
    • Overview — brief description of the example; link to models if used.
    • Demo — screenshot(s) or GIF.
    • Usage — supported devices, supported modes, and available flags (flags can be auto-generated by python3 main.py --help if using argparse).
    • Peripheral Mode — installation and usage instructions for peripheral mode (if supported).
    • Standalone Mode — instructions for standalone usage (if supported).
    • You may deviate from this structure when appropriate, but all relevant information must be included.

Once an example is added, also add an entry to the table in the relevant top-level README (e.g., apps README). Fill in the following columns:

  • RVC2 — Whether the example supports RVC2 devices.
  • RVC4 (peripheral) — Whether it supports RVC4 devices in peripheral mode.
  • RVC4 (standalone) — Whether it supports RVC4 devices in standalone mode.
  • DepthAIv2 — Optional link to a DepthAIv2 example the new one is based on.
  • Notes — Optional extra notes (e.g., requires stereo device).

Testing

The repository supports automated runnability tests for examples. This ensures that each example can run for several seconds in a controlled environment with its dependencies installed.

To be picked up by the tests, an example must contain both main.py and requirements.txt in the same directory. When detected, the test pipeline will:

  1. Create a new environment
  2. Install dependencies from requirements.txt
  3. Run python3 main.py with no additional flags

You can read more about running tests locally in tests/README.md.

Some examples may be incompatible with certain versions or modes (e.g., only standalone, only RVC4). These constraints must be listed in tests/constants.py under the dictionary of known failing examples. See the Known Failing Examples (Rule System) section in tests/README.md for editing guidelines.

Making the PR

Before pushing your changes, ensure that:

  • Your changes work in a fresh environment
  • pre-commit passes
  • Tests pass locally

When submitting the PR:

  • Provide a clear and concise description of the change.
    • For bug reports: include steps to reproduce, environment details, error logs, and device information (e.g., OAK-D, OAK-4).
  • Link the related issue if applicable.
  • Make sure the PR is focused, atomic, and well-documented.
  • Respond to review feedback — maintainers may request adjustments before merging.
  • If the PR is not ready for review, mark it as a Draft and list your open questions.

Choose appropriate reviewers:

  • If the PR relates to an issue, assign the main issue participant.
  • If the PR involves Luxonis developers, add your lead or the relevant team member.
  • If unsure, assign klemen1999 (Klemen Skrlj) who will route the review appropriately.

CI/CD Requirements Before Merge

A PR targeting main must satisfy the CI/CD checks:

  • pre-commit must pass
    • If it fails, run pre-commit locally (see the Setup section), commit the fixes, and push again.
  • Tests must pass
    • Add the testable label to the PR to trigger tests for only the examples modified in the PR.