Contributing to Buckaroo

We love contributions! This guide covers development setup, building, testing, and releasing.

Development setup

Prerequisites

• uv for Python dependency management
• pnpm for JavaScript dependency management
• Node.js >= 18
• Python >= 3.11

Python

git clone https://github.com/buckaroo-data/buckaroo.git
cd buckaroo
uv sync --dev --all-extras

JavaScript

cd packages/buckaroo-js-core
pnpm install

Full build (JS + Python wheel)

./scripts/full_build.sh

Git hooks

The repo ships pre-commit / pre-push hooks under .githooks/. Point git at them once per clone:

git config core.hooksPath .githooks

The shims defer to pre-commit to run the checks declared in .pre-commit-config.yaml (lint on commit, full-tree ruff + paddy_format --check on push — same as CI's Python / Lint job). Make sure pre-commit is on your PATH:

uv tool install pre-commit

Tracking the hooks under .githooks/ instead of relying on pre-commit install's generated shims means every clone runs identical hook code, and updates propagate via git pull.

Running tests

Python

uv run pytest tests/unit/ -v
uv run ruff check --fix

JavaScript

cd packages/buckaroo-js-core
pnpm test

Storybook (component development)

cd packages/buckaroo-js-core
pnpm storybook
# open http://localhost:6006

Build a static Storybook site:

cd packages/buckaroo-js-core
pnpm build-storybook

Playwright (UI tests against Storybook)

Install browsers:

cd packages/buckaroo-js-core
pnpm exec playwright install

Run tests:

pnpm test:pw --reporter=line

Useful variants:

pnpm test:pw:headed   # visible browser
pnpm test:pw:ui       # Playwright UI
pnpm test:pw:report   # open HTML report

Adding dependencies

uv add <package>                              # main dependency
uv add --group <group> <package>              # extras group

Release process

1. Update CHANGELOG.md
2. Trigger the Release workflow via GitHub Actions (workflow_dispatch), choosing patch, minor, or major
3. The workflow bumps the version in pyproject.toml, creates the tag, builds, publishes to PyPI, and creates a GitHub release

Reporting issues

We welcome issue reports. Please choose the proper issue template so we get the necessary information.