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.3.9+
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 (~5000 tests)
bun test

# 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 with coverage
bun test --coverage

Note: bun test preloads test/preload.ts, which sets BUNQUEUE_EMBEDDED=1. 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 Biome (one tool for linting + formatting):

# Lint
bun run lint

# Format code
bun run format

# Lint + format check in one pass (what CI / the pre-commit hook run)
bun run check:biome

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
Run bun run test:model for core queue changes, then the authoritative bun run test:sandbox gate and bun run check:biome
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
- [ ] Linting passes
- [ ] 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 patch version in package.json
Updates the changelog (docs/src/content/docs/changelog.md)
Publishes to npm with bun publish

Getting Help

Recognition

Contributors are listed in:

GitHub contributors page
README.md acknowledgments

Thank you for contributing!