# Best Practices for Developing with Colibri: A Complete Guide to Contributing

> Master Colibri development with best practices. Preserve CPU path, use dev branch, and run make check for stable contributions. Your complete guide to collaborating on the JustVugg/colibri repo.

- Repository: [Vincenzo Fornaro/colibri](https://github.com/JustVugg/colibri)
- Tags: best-practices
- Published: 2026-09-12

---

**Always preserve the dependency-free CPU path, develop against the `dev` branch, and run `make check` before submitting PRs to ensure your changes meet the project's stability standards.**

Colibri is a lightweight, dependency-free inference engine written in C with a thin Python wrapper. Whether you are optimizing CUDA kernels or extending the CLI, following the established best practices for developing with Colibri ensures your contributions remain portable and maintainable. This guide covers the essential workflows, testing requirements, and coding standards defined in the repository's [`CONTRIBUTING.md`](https://github.com/JustVugg/colibri/blob/main/CONTRIBUTING.md) and source tree.

## Understand the Architecture: C Engine vs. Python Wrapper

Colibri maintains a strict separation between its high-performance backend and user-facing interface.

- **Engine (C)**: Located in the `c/` directory, this layer handles high-performance model execution with optional CUDA and Vulkan support. The key entry point is `c/coli`, which is invoked via the Python wrapper.
- **Python Wrapper**: Provides the user-friendly `coli` CLI and library import (`import colibri`). Key files include [`colibri/cli.py`](https://github.com/JustVugg/colibri/blob/main/colibri/cli.py) for the console script entry point and [`colibri/__init__.py`](https://github.com/JustVugg/colibri/blob/main/colibri/__init__.py), which exposes the package `__version__`.

This two-layer design ensures that the core engine remains dependency-free while the Python layer handles convenience features.

## Preserve the Dependency-Free CPU Path

The default build must remain **dependency-free** and runnable on any CPU without CUDA, Vulkan, or external Python packages.

If you introduce features requiring extra libraries, isolate that code behind compile-time or runtime flags. This ensures the plain-CPU build remains untouched and stable.

> "Keep changes focused and preserve Colibri's dependency-free default CPU path." — [`CONTRIBUTING.md`](https://github.com/JustVugg/colibri/blob/main/CONTRIBUTING.md)

## Follow the Branch Workflow

The repository uses a two-branch strategy to maintain stability.

- **`main`**: Contains stable code that always passes the token-exact oracle test.
- **`dev`**: The integration branch where all development occurs.

Always open pull requests against `dev`. Reviewed PRs land there first, and only after validation does the maintainer fast-forward `dev` into `main`.

> "Open your PR against `dev`. Reviewed PRs land there first …" — [`CONTRIBUTING.md`](https://github.com/JustVugg/colibri/blob/main/CONTRIBUTING.md)

## Run Automated Checks Before Pushing

Validate your changes using the repository's lightweight test harness.

```bash

# Run the portable CPU build, C unit tests, and Python std-lib tests

make check

```

This command does not download models or require CUDA, making it safe for rapid iteration.

For GPU-specific changes, additionally run:

```bash
make -C c cuda-test CUDA_ARCH=native

```

> "CUDA changes should additionally be checked on a CUDA-capable Linux host." — [`CONTRIBUTING.md`](https://github.com/JustVugg/colibri/blob/main/CONTRIBUTING.md)

## Maintain Reproducible Builds

All builds are driven by the `Makefile` in the repository root. When adding new source files to the C engine, update `c/Makefile` to list them in the appropriate build target.

This guarantees that `make check` produces a clean, warning-free compilation across different environments.

## Extend the CLI Responsibly

The public CLI (`coli`) is a thin wrapper around the engine script. Keep the wrapper minimal by delegating to `c/coli` via `runpy.run_path`:

```python

# colibri/cli.py – entry point for the `coli` console script

import os
import sys
import runpy

def main():
    engine_dir = os.path.join(os.path.dirname(__file__), "..", "c")
    coli_script = os.path.join(engine_dir, "coli")
    sys.path.insert(0, engine_dir)
    sys.argv[0] = coli_script
    runpy.run_path(coli_script, run_name="__main__")

```

This pattern ensures that `pip install colibri-engine` creates a working `coli` command without requiring users to modify their `PATH`.

## Adhere to Code Style and Linting

The repository enforces strict formatting standards for both languages.

- **C Code**: Follow the `.clang-format` file and run `clang-tidy` via `make check`.
- **Python Code**: Adhere to PEP-8 standards validated by `flake8`.

Running `make check` before committing catches style violations early and prevents CI failures.

## Benchmark Responsibly

Performance changes require reproducible evidence. Include a benchmark report detailing:

- Commit hash and hardware specifications
- Exact command line used
- Warm-up policy and run count
- Median throughput results

Place this documentation in [`docs/benchmarks.md`](https://github.com/JustVugg/colibri/blob/main/docs/benchmarks.md) or a new markdown file under `docs/`.

> "Benchmark reports should include the commit, exact commands, hardware and storage details, warm-up policy, run count, and median throughput." — [`CONTRIBUTING.md`](https://github.com/JustVugg/colibri/blob/main/CONTRIBUTING.md)

## Summary

Following these best practices for developing with Colibri maintains the codebase's portability and performance:

- **Guard optional dependencies** behind flags to preserve the default CPU path.
- **Develop on `dev`** and target it for all pull requests.
- **Run `make check`** locally before pushing; add GPU tests for CUDA/Vulkan changes.
- **Update `c/Makefile`** when adding source files to ensure reproducible builds.
- **Keep the Python wrapper thin** by delegating to `c/coli` via `runpy`.
- **Follow linting rules** enforced by `clang-tidy` and `flake8`.
- **Document benchmarks** with full hardware and methodology details in `docs/`.

## Frequently Asked Questions

### Should I develop on the main or dev branch?

Always develop on the `dev` branch. The `main` branch contains stable, production-ready code that has passed all validation tests. Open your pull requests against `dev`, where maintainers review and integrate changes before promoting them to `main`.

### How do I test CUDA changes without breaking the CPU build?

Isolate CUDA-specific code behind compile-time flags or runtime checks. Run `make check` to verify the CPU build remains intact, then execute `make -C c cuda-test CUDA_ARCH=native` on a CUDA-capable machine to validate GPU functionality. This ensures the dependency-free default path stays functional for all users.

### What should I include in a performance benchmark report?

Include the exact commit hash, hardware specifications (CPU, GPU, storage), the precise command line executed, your warm-up policy, the number of runs performed, and the median throughput. Place this report in [`docs/benchmarks.md`](https://github.com/JustVugg/colibri/blob/main/docs/benchmarks.md) so other developers can reproduce your results.

### How do I add a new command-line option to the Colibri CLI?

Add new flags to [`colibri/cli.py`](https://github.com/JustVugg/colibri/blob/main/colibri/cli.py) using `argparse`, then forward unknown arguments to the C engine via `runpy.run_path`. Set environment variables for flags the engine needs to read directly. Keep the wrapper minimal and delegate actual processing to `c/coli` rather than implementing logic in Python.