77 lines
1.8 KiB
Markdown
77 lines
1.8 KiB
Markdown
|
# 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
|