# Contributing to Shade

Thanks for considering a contribution. Shade is a security-critical library, so the bar for changes is high but the process is straightforward.

## Development setup

```bash
git clone https://github.com/Sterister/Shade
cd Shade
bun install
bun test --recursive
```

All tests should pass before you submit a change.

## Running with PostgreSQL

The PostgreSQL backend tests are skipped by default. To run them:

```bash
docker run -d --name shade-test-pg -e POSTGRES_PASSWORD=test -p 5999:5432 postgres:16-alpine
SHADE_TEST_PG_URL=postgres://postgres:test@localhost:5999/postgres bun test --recursive
```

## Running benchmarks

```bash
bun run bench/run.ts
```

Results are written to `bench/results.md`.

## Code style

- TypeScript strict mode
- No `any` except at storage boundaries
- TSDoc on all public APIs
- Tests for every new feature
- Constant-time comparisons for any operation involving secret data

## Security disclosure

For security vulnerabilities, see [SECURITY.md](./SECURITY.md). Please do NOT open public issues for security bugs.

## Commit conventions

Use clear, descriptive commit messages. Conventional Commits style is encouraged but not required:

```
feat(core): add identity rotation
fix(server): handle empty prekey replenishment
docs: update threat model
```

## Pull requests

1. Fork the repo
2. Create a feature branch
3. Make your changes with tests
4. Run `bun test --recursive` and ensure all pass
5. Open a PR with a clear description

## What gets accepted

- Bug fixes (always welcome)
- New tests for existing functionality
- Documentation improvements
- New storage backends
- Performance improvements that don't compromise security

## What needs discussion first

- Changes to the wire format (breaking)
- Changes to cryptographic primitives
- Removing existing API surface
- Changes to error codes