mirror of
https://github.com/Start9Labs/patch-db.git
synced 2026-03-26 10:21:53 +00:00
86b0768bbb
Soundness and performance audit (17 fixes): - See AUDIT.md for full details and @claude comments in code Repo restructure: - Inline json-ptr and json-patch submodules as regular directories - Remove cbor submodule, replace serde_cbor with ciborium - Rename patch-db/ -> core/, patch-db-macro/ -> macro/, patch-db-macro-internals/ -> macro-internals/, patch-db-util/ -> util/ - Purge upstream CI/CD, bench, and release cruft from json-patch - Remove .gitmodules Test fixes: - Fix proptest doesnt_crash (unique file paths, proper close/cleanup) - Add PatchDb::close() for clean teardown Documentation: - Add README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, AUDIT.md - Add TSDocs to TypeScript client exports Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
88 lines
2.2 KiB
Markdown
88 lines
2.2 KiB
Markdown
# Contributing
|
|
|
|
## Prerequisites
|
|
|
|
- **Rust** — stable toolchain (edition 2018+)
|
|
- **Node.js** — v16+ with npm
|
|
|
|
## Building
|
|
|
|
### Rust
|
|
|
|
```bash
|
|
cargo build # Build all crates
|
|
cargo build --features debug # Build with tracing support
|
|
```
|
|
|
|
### TypeScript client
|
|
|
|
```bash
|
|
cd client
|
|
npm install
|
|
npm run build # Compiles to dist/
|
|
npm run check # Type-check without emitting
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Rust
|
|
|
|
```bash
|
|
cargo test # Run all tests
|
|
cargo test -p patch-db # Core crate only
|
|
cargo test -p json-ptr # JSON Pointer crate only
|
|
cargo test -p json-patch # JSON Patch crate only
|
|
```
|
|
|
|
The core crate uses `proptest` for property-based testing.
|
|
|
|
### TypeScript
|
|
|
|
The client uses pre-commit hooks (husky) for linting:
|
|
|
|
```bash
|
|
cd client
|
|
npx prettier --check "**/*.{js,ts,html,md,less,json}"
|
|
npx tslint --project .
|
|
```
|
|
|
|
## CLI utility
|
|
|
|
`patch-db-util` provides commands for inspecting and restoring database files:
|
|
|
|
```bash
|
|
# Dump database state as JSON
|
|
cargo run -p patch-db-util -- dump path/to/my.db
|
|
|
|
# Restore database from JSON on stdin
|
|
echo '{"count": 42}' | cargo run -p patch-db-util -- from-dump path/to/my.db
|
|
```
|
|
|
|
## Code style
|
|
|
|
### Rust
|
|
|
|
- Follow standard `rustfmt` conventions
|
|
- Use `thiserror` for error types
|
|
- Async functions use `tokio`
|
|
|
|
### TypeScript
|
|
|
|
- Prettier for formatting (runs via pre-commit hook)
|
|
- TSLint for linting (runs via pre-commit hook)
|
|
- RxJS conventions: suffix observables with `$`
|
|
|
|
## Making changes
|
|
|
|
1. **Check [ARCHITECTURE.md](ARCHITECTURE.md)** to understand which crate(s) your change touches
|
|
2. **Follow existing patterns** — look at neighboring code before inventing new abstractions
|
|
3. **Cross-layer changes** (Rust types that affect the TS client) require updating both sides to keep the wire format compatible:
|
|
- `Revision` and `Dump` types must match between `core/src/patch.rs` and `client/lib/types.ts`
|
|
- Patch operations (add/remove/replace) must match between `json-patch/` and `client/lib/json-patch-lib.ts`
|
|
4. **Run tests** before submitting
|
|
|
|
## Commit conventions
|
|
|
|
- Use imperative mood in commit messages ("add feature", not "added feature")
|
|
- Keep commits focused — one logical change per commit
|