# Contributing to bunqueue: Development & PR Guide

Contribute to bunqueue: dev environment setup, coding standards, testing guidelines, and pull request workflow for the Bun job queue.

Canonical: https://bunqueue.dev/contributing/

---

<div class="bq-wrap bq-hero">
  <span class="bq-eyebrow">project · contributing</span>
  <h1 class="bq-hero-h1 bq-bench-h1">Contribute to bunqueue, ship a <em>PR.</em></h1>
  <p class="bq-hero-sub">Dev environment setup, coding standards, testing guidelines and the pull request workflow. Everything you need to land a change, whatever your experience level.</p>
</div>

## Code of Conduct

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

## Getting Started

### Prerequisites

- [Bun](https://bun.sh) v1.4.0+
- Git
- A GitHub account

### Setup

```bash
# 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:

```bash
# 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:

```bash
# 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 [Oxlint](https://oxc.rs/docs/guide/usage/linter/quickstart.html) for
type-aware linting and
[Oxfmt](https://oxc.rs/docs/guide/usage/formatter/quickstart.html) for formatting:

```bash
# Lint
bun run lint

# Format code
bun run format

# Lint + format verification (what CI / the pre-commit hook run)
bun run check:oxc
```

## 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](https://www.conventionalcommits.org/):

```
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 run test:model` for core queue changes, then the authoritative
   `bun run test:sandbox` gate and `bun run check:oxc`
6. Push and create a PR

### PR Template

```markdown
## 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
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

```typescript
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

```typescript
/** 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:

1. Bumps the patch version in `package.json`
2. Updates the changelog (`docs/src/content/docs/changelog.md`)
3. Publishes to npm with `bun publish`

## Getting Help

- [GitHub Discussions](https://github.com/egeominotti/bunqueue/discussions)
- [GitHub Issues](https://github.com/egeominotti/bunqueue/issues)

## Recognition

Contributors are listed in:
- GitHub contributors page
- README.md acknowledgments

Thank you for contributing!

:::tip[Related]
- [Architecture & System Design](/architecture/) - Understand the codebase
- [Security Best Practices](/security/) - Security guidelines
:::