Skip to content

Developer & Contributing Guide

Thank you for contributing to OpenJarvis CLI! This guide covers setting up your development environment, running tests, linting, and building standalone binaries.

1. Development Setup

OpenJarvis CLI uses Python 3.13+ and uv for fast, reproducible dependency management:

# Clone the repository
git clone https://github.com/bhanuponguru/openjarvis-cli.git
cd openjarvis-cli

# Install dependencies and development groups
uv sync --group dev --group docs --group build

2. Running the Test Suite

All tests execute on standard CPUs in seconds without any external model requirements:

# Run all unit tests
uv run pytest -q

# Run with verbose output
uv run pytest -v

3. Linting & Type Checking

Before submitting a PR, verify linting and type safety:

# Run Ruff linting
uv run ruff check .

# Auto-fix import sorting and common issues
uv run ruff check --fix .

# Static type checking
uv run mypy

4. Building Standalone Binaries (PyInstaller)

OpenJarvis CLI can be compiled into a self-contained executable that runs on machines without Python installed:

# On Linux / macOS:
bash scripts/build-binary.sh

# On Windows:
scripts\build-binary.bat

The compiled standalone binary will be placed in dist/openjarvis.

5. Version Management & Releases

OpenJarvis CLI implements Git-tag and commit-based dynamic versioning powered by hatch-vcs. The version is calculated automatically from Git metadata without needing manually edited version strings:

  • Official Releases: Pushing an annotated Git tag (e.g. v0.2.0) sets the exact version to 0.2.0.
  • Development Builds: Commits ahead of the latest tag automatically generate PEP 440 dev versions (e.g. 0.2.0.dev1) representing the exact commit distance.
  • Build Hook: hatch-vcs automatically generates src/openjarvis/_version.py during uv build and uv sync, embedding the exact calculated version into packages.

Automated Release Tagging

Use the bumper script to calculate the next SemVer tag, create the annotated Git tag, and build distribution wheels:

# Calculate next patch release tag (e.g. from v0.2.0), tag, and build
python scripts/bump-version.py patch

# Calculate next minor release tag (e.g. from v0.2.0), tag, and build
python scripts/bump-version.py minor

# Calculate next major release tag (e.g. from v0.2.0), tag, and build
python scripts/bump-version.py major

# Or set an explicit release tag:
python scripts/bump-version.py 0.2.0

Packaging & Distribution Builds

# 1. Clean build of sdist and wheel
uv build

# 2. Push git tag to GitHub
git push origin v0.2.0

6. Pre-Commit Verification (Mandatory)

Before committing code or opening a PR, ensure all three mandatory checks pass with zero errors:

uv run ruff check .
uv run mypy
uv run pytest -q