Contributing to bunqueue: Development & PR Guide

project · contributing

Contribute to bunqueue, ship a PR.

Dev environment setup, coding standards, testing guidelines and the pull request workflow. Everything you need to land a change, whatever your experience level.

Code of Conduct

Be respectful and inclusive. We welcome contributors of all backgrounds and experience levels.

Getting Started

Prerequisites

Bun v1.4.0+
Git
A GitHub account

Setup

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/bunqueue.git
cd bunqueue
bun install

Running Tests

There are three suites. All three must pass before any change lands:

# Unit tests (four isolated file workers)
bun test --parallel=4

# TCP integration tests (~50 suites, spawns a real server)
bun scripts/tcp/run-all-tests.ts

# Embedded integration tests (~35 suites)
bun scripts/embedded/run-all-tests.ts

Other useful invocations:

# Run a specific test file
bun test test/queueManager.test.ts

# Run the generated real-broker state model
bun run test:model

# Reproduce or deepen a model campaign
BUNQUEUE_MODEL_RUNS=500 BUNQUEUE_MODEL_COMMANDS=150 \
BUNQUEUE_MODEL_SEED=-1959189325 bun run test:model

# Run the full unit suite with coverage
bun test --parallel=4 --coverage

Note: bun test preloads test/preload.ts, which sets BUNQUEUE_EMBEDDED=1. The full unit command uses four isolated worker processes; tests inside an individual file remain serial. Tests that need real TCP behavior must opt out with an explicit embedded: false and spawn a server.

Changes to queue lifecycle, persistence/recovery, scheduling, dependencies, deduplication, leases, limits, TTL, counters, or indexes must run bun run test:model during iteration. The model uses real TCP, SQLite, and SIGKILL; failures include a seed and minimized command history. Preserve every confirmed engine divergence as a deterministic test/repro-model-*.test.ts before fixing it. The model run is required in addition to the final isolated bun run test:sandbox gate.

Code Style

We use Bun’s built-in tools only: bun check for type checking and bun fmt for formatting, configured in the [fmt] section of bunfig.toml. They are the only type-check and format tools for JavaScript and TypeScript, in this repository and in every SDK: ESLint, Prettier, Biome, oxlint, oxfmt and tsc --noEmit are not used, and there is no JavaScript linter. SDKs in other languages keep their own toolchain (gofmt, go vet, cargo fmt, cargo clippy, mix format, php -l).

# Type check. It first rebuilds what the test tree imports (the SDK build,
# the package build, the docs dependencies), so it never reads a stale build.
bun run typecheck

# Format code
bun run format

# Format verification (what CI / the pre-commit hook run, with typecheck)
bun run format:check

Making Changes

Branch Naming

feat/description - New features
fix/description - Bug fixes
docs/description - Documentation
refactor/description - Code refactoring
test/description - Test additions

Commit Messages

Follow Conventional Commits:

feat: add stall detection for workers
fix: resolve memory leak in event listeners
docs: update API reference
refactor: simplify batch operations
test: add DLQ filtering tests

Pull Request Process

Create a feature branch
Make your changes
Add/update tests
Update documentation: the internal reference under docs/ (docs/README.md, docs/architecture.md, docs/data-model.md, docs/features/*.md) in the same change as the code, and the changelog (docs/src/content/docs/changelog.md) in every commit
Run bun run test:model for core queue changes, then the authoritative bun run test:sandbox gate (plus bun run test:sandbox:sdk after any change under sdk/), bun run typecheck and bun run format:check
Push and create a PR

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation

## Testing
How was this tested?

## Checklist
- [ ] Tests pass
- [ ] `bun run typecheck` and `bun run format:check` pass
- [ ] Documentation updated

Project Structure

src/
├── cli/             # CLI commands
├── client/          # Embedded client SDK
├── domain/          # Core business logic
├── application/     # Use cases
├── infrastructure/  # External services
└── shared/          # Utilities

Key Files

src/domain/queue/shard.ts - Queue sharding logic
src/application/queueManager.ts - Central coordinator
src/client/queue/queue.ts - Client Queue class
src/client/worker/worker.ts - Client Worker class

Architecture Guidelines

File Size

Max 300 lines per file
Split if larger

Lock Order

jobIndex
completedJobs
shards[N]
processingShards[N]

Memory Management

Use bounded collections
Clean up event listeners
Release resources in shutdown

Testing Guidelines

Test Structure

describe('Feature', () => {
  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });

  it('should do something', () => {
    // Test
  });
});

What to Test

Happy path
Edge cases
Error handling
Concurrent operations
Generated state transitions and crash/recovery invariants for core queue changes

Documentation

Code Comments

/** Brief description */
function simpleFunction() {}

/**
 * Longer description for complex functions
 * @param input - Description
 * @returns Description
 */
function complexFunction(input: string): Result {}

README Updates

Update README.md for:

New features
Changed APIs
New environment variables

Release Process

Releases are handled by the maintainer. Every release:

Bumps the version in package.json
Updates the changelog (docs/src/content/docs/changelog.md)
Publishes to npm from GitHub Actions through npm trusted publishing, with a provenance attestation; packages are never published from a local machine

Getting Help

Recognition

Contributors are listed in:

GitHub contributors page
The “Thanks to N contributors!” section of each release blog post

Thank you for contributing!