Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ We suggest following the workflow below for proposing and contributing improveme
1. For large changes, refactorings, new features, or changes to API specifications, wire protocol, backend
storage traits, authentication or authorization, schema or CLI commands, please submit an
[RFC](docs/rfcs/README.md) as a pull request and link it to the GitHub issue. Allow time for the RFC to
be reviewed, discussed and voted on.
be reviewed, discussed and voted on. If your change is a new storage backend, it must also satisfy the
[Backend Acceptance Criteria](docs/rfcs/0003-backend-acceptance-criteria.md).
1. Create a fork of the [ExtendDB 'main' branch](https://github.com/ExtendDB/extenddb/tree/main).
1. Clone your fork into your development environment.
1. Make, build, test and self-review your changes on a feature branch on your fork.
Expand Down Expand Up @@ -82,6 +83,21 @@ maintainer will tell you which path fits.
Some areas are protected by [`.github/CODEOWNERS`](.github/CODEOWNERS) — PRs
touching them require approval from the listed owners.

## Contributing a storage backend

If you are adding a new storage backend, read these two documents before you
write code:

- [RFC-0002: Backend Plugin Policy](docs/rfcs/0002-backend-plugin-policy.md) is
the *process*: mono-repo structure, trait-based conformance, and the
acceptance and maintenance workflow.
- [Backend Acceptance Criteria](docs/rfcs/0003-backend-acceptance-criteria.md)
is the *substance*: the concrete DynamoDB-behavioral invariants and
implementation standards your backend must satisfy (item identity, secondary
indexes, transactions, isolation, streams, condition expressions, query and
scan, multi-tenancy, error fidelity, and operational correctness), plus the
conformance stress tests reviewers will run.

## License

By contributing, you agree that your contributions will be licensed under the
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,9 @@ ExtendDB uses two lightweight processes for tracking decisions:
new feature or subsystem. Substantial changes go through an RFC before
implementation.

Adding a storage backend? Start with [RFC-0002: Backend Plugin Policy](docs/rfcs/0002-backend-plugin-policy.md)
and the [Backend Acceptance Criteria](docs/rfcs/0003-backend-acceptance-criteria.md).

Code in protected paths is reviewed via [`.github/CODEOWNERS`](.github/CODEOWNERS).

## License
Expand Down
4 changes: 4 additions & 0 deletions docs/design/04-component-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ backend selection based on configuration.
**Current status**: PostgreSQL is the only supported backend. The trait architecture and plugin infrastructure provide
the foundation for future backend implementations.

Backends accepted into the ExtendDB repository must satisfy the [Backend Acceptance Criteria](../rfcs/0003-backend-acceptance-criteria.md)
(the DynamoDB-behavioral invariants for the storage layer) and the process defined in
[RFC-0002](../rfcs/0002-backend-plugin-policy.md).

## 2. Storage Trait Hierarchy

The storage abstraction is split into focused traits following the Interface Segregation Principle. This allows
Expand Down
3 changes: 2 additions & 1 deletion docs/rfcs/0002-backend-plugin-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Backends released under the ExtendDB organization must adhere to a trait-based c

3. **All-or-nothing per trait.** The trait is the finest-grained unit of conformance. Backends cannot claim partial support for a trait (example: "Streams partially works but records are incomplete" is not allowed). Either the trait is fully implemented and conformant, or it is not implemented.

4. **Maintain semantic correctness.** Where a backend implements an operation, it must match DynamoDB behavior including error responses, pagination, isolation guarantees, atomicity guarantees, and consistency models.
4. **Maintain semantic correctness.** Where a backend implements an operation, it must match DynamoDB behavior including error responses, pagination, isolation guarantees, atomicity guarantees, and consistency models. The concrete, per-operation invariants that define this behavioral match are enumerated in [Backend Acceptance Criteria](0003-backend-acceptance-criteria.md).

5. **Clear documentation.** Backends must document in their README which optional traits they implement and which they do not. Conformance test results (per-trait pass rates) must be published and tracked in CI.

Expand Down Expand Up @@ -224,6 +224,7 @@ External contributors may propose new backends or maintain existing ones. The pr
3. **Implementation.** Contributor develops the backend in `crates/storage-{backend}/` following the `Storage` trait contract. The contributor owns their backend directory but ExtendDB maintainers retain override authority for repository-wide concerns.

4. **Acceptance criteria:**
- All applicable [Backend Acceptance Criteria](0003-backend-acceptance-criteria.md) invariants are satisfied.
- Conformance tests pass for all required traits and for any implemented, optional traits.
- Documentation includes setup guide, architecture notes, troubleshooting
- Integration tests run successfully in CI (contributor may need to provide sandbox credentials for cloud-based backends via GitHub Secrets)
Expand Down
Loading
Loading