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 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.

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 all three test suites (bun test, bun scripts/tcp/run-all-tests.ts, bun scripts/embedded/run-all-tests.ts) 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

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!