Skip to content
bunqueue

Contributing

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

Code of Conduct

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

Getting Started

Prerequisites

  • Bun v1.0+
  • Git
  • A GitHub account

Setup

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

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

We use ESLint and Prettier:

Terminal window
# Check linting
bun run lint


# Format code
bun run format

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

  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

## 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.ts - Client Queue class
  • src/client/worker.ts - Client Worker class

Architecture Guidelines

File Size

  • Max 300 lines per file
  • Split if larger

Lock Order

  1. jobIndex
  2. completedJobs
  3. shards[N]
  4. 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

  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

Recognition

Contributors are listed in:

  • GitHub contributors page
  • README.md acknowledgments

Thank you for contributing! 🎉