Skip to content
bunqueue

Contributing to bunqueue: Development & PR Guide

Thank you for your interest in contributing to bunqueue! This guide will help you get started.

Code of Conduct

Section titled “Code of Conduct”

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

Getting Started

Section titled “Getting Started”

Prerequisites

Section titled “Prerequisites”
  • Bun v1.0+
  • Git
  • A GitHub account

Setup

Section titled “Setup”
Terminal window
# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/bunqueue.git
cd bunqueue
bun install

Running Tests

Section titled “Running Tests”
Terminal window
# Run all tests
bun test


# Run specific test file
bun test test/queue.test.ts


# Run with coverage
bun test --coverage

Code Style

Section titled “Code Style”

We use ESLint and Prettier:

Terminal window
# Check linting
bun run lint


# Format code
bun run format

Making Changes

Section titled “Making Changes”

Branch Naming

Section titled “Branch Naming”
  • feat/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation
  • refactor/description - Code refactoring
  • test/description - Test additions

Commit Messages

Section titled “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

Section titled “Pull Request Process”
  1. Create a feature branch
  2. Make your changes
  3. Add/update tests
  4. Update documentation
  5. Run bun test and bun run lint
  6. Push and create a PR

PR Template

Section titled “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

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

Key Files

Section titled “Key Files”
  • src/domain/queue/shard.ts - Queue sharding logic
  • src/application/queueManager.ts - Central coordinator
  • src/client/queue.ts - Client Queue class
  • src/client/worker.ts - Client Worker class

Architecture Guidelines

Section titled “Architecture Guidelines”

File Size

Section titled “File Size”
  • Max 300 lines per file
  • Split if larger

Lock Order

Section titled “Lock Order”
  1. jobIndex
  2. completedJobs
  3. shards[N]
  4. processingShards[N]

Memory Management

Section titled “Memory Management”
  • Use bounded collections
  • Clean up event listeners
  • Release resources in shutdown

Testing Guidelines

Section titled “Testing Guidelines”

Test Structure

Section titled “Test Structure”
describe('Feature', () => {
  beforeEach(() => {
    // Setup
  });


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


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

What to Test

Section titled “What to Test”
  • Happy path
  • Edge cases
  • Error handling
  • Concurrent operations

Documentation

Section titled “Documentation”

Code Comments

Section titled “Code Comments”
/** Brief description */
function simpleFunction() {}


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

README Updates

Section titled “README Updates”

Update README.md for:

  • New features
  • Changed APIs
  • New environment variables

Release Process

Section titled “Release Process”
  1. Update version in package.json
  2. Update CHANGELOG.md
  3. Create PR titled release: v1.x.x
  4. After merge, tag and publish

Getting Help

Section titled “Getting Help”

Recognition

Section titled “Recognition”

Contributors are listed in:

  • GitHub contributors page
  • README.md acknowledgments

Thank you for contributing!