Skip to main content
Thanks for contributing to bun-scikit! We welcome contributions from the community and appreciate your help in making this project better.

​
Development Setup

1

Install Bun

Install Bun >=1.3.9:
curl -fsSL https://bun.sh/install | bash
2

Install Dependencies

Install project dependencies:
bun install
3

Install Python Dependencies (Optional)

For Python comparison benchmarks, install Python dependencies:
python -m pip install -r bench/python/requirements.txt

​
Project Commands

# Run all tests
bun run test

# Run typecheck
bun run typecheck

# Generate API docs
bun run docs:api:generate

# Check API docs coverage
bun run docs:coverage:check

# Heart benchmark (human-readable)
bun run bench

# Heart classification benchmark
bun run bench:heart:classification

# Heart tree benchmark
bun run bench:heart:tree

# Generate CI benchmark snapshot locally
bun run bench:snapshot

​
Pull Request Guidelines

Scope

Keep changes scoped to one objective. Focus on a single feature, bug fix, or improvement per PR.

Testing

Include tests for behavioral changes. Ensure all tests pass before submitting.

Documentation

Update docs when public APIs or workflows change. Keep documentation in sync with code.

Changelog

Add changelog entries under ## [Unreleased] in CHANGELOG.md for notable changes.

​
Pre-PR Checklist

Run these commands locally before opening a pull request:
bun run test

​
Commit Guidelines

Commit Message Format

Use clear, imperative commit messages with conventional prefixes:
  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • test: - Test additions or modifications
  • ci: - CI/CD changes
  • chore: - Maintenance tasks
  • perf: - Performance improvements
  • refactor: - Code refactoring

​
Examples

feat: add KMeans clustering estimator
fix: correct StandardScaler variance calculation
docs: update LinearRegression API reference
test: add integration tests for RandomForest
ci: add parity check workflow
perf: optimize Zig tree split kernel

​
Benchmark Policy

Important: Benchmark table content in README.md is generated from bench/results/heart-ci-latest.json. Do not hand-edit the benchmark section in README.md.
1

Run Benchmarks

Execute benchmarks to generate snapshot data:
bun run bench:snapshot
2

Sync README

Regenerate the README benchmark section from the snapshot file:
bun run bench:sync-readme
3

Verify Changes

Check that benchmark content is in sync:
bun run bench:readme:check

​
Code Style

TypeScript

  • Use TypeScript for all new code
  • Enable strict type checking
  • Avoid any types where possible
  • Document public APIs with JSDoc comments

Formatting

  • Follow existing code style
  • Use 2 spaces for indentation
  • Use meaningful variable names
  • Keep functions focused and small

​
Testing Guidelines

Write unit tests for:
  • New estimators and transformers
  • Metrics and utilities
  • Edge cases and error handling
  • Parameter validation
Write integration tests for:
  • End-to-end workflows
  • Pipeline compositions
  • Cross-validation scenarios
  • Real dataset examples
For scikit-learn compatible APIs:
  • Add fixtures to test/fixtures/sklearn-snapshots.json
  • Run scripts/generate-sklearn-fixtures.py to generate reference outputs
  • Ensure parity checks pass with bun run parity:check

​
Getting Help

GitHub Discussions

Ask questions and discuss ideas with the community

GitHub Issues

Report bugs or request features

Documentation

Read the full documentation

Support

View support and community resources
First time contributing? Look for issues labeled good first issue or help wanted to get started!

Build docs developers (and LLMs) love

Get started for freeTalk to us