[LeeroyHannigan]

What

• README.md gets a Scope section after Use Cases and a Storage backends section before Quick Start. The Storage backends section defines three tiers and puts each backend in one. Its table gives the topology, upgrade path, API coverage, CI job and known limits of each backend.
• The new docs/versioning.md says what each kind of release can change and what stays compatible within a major version. It also gives the catalog upgrade rules, what the policy does not cover, the support periods and the deprecation steps. The README documentation table links to it.
• The comment in crates/bin/src/main.rs now describes sqlite as a production backend on a single node. The dev-mode comments in main.rs, crates/bin/Cargo.toml and crates/app/Cargo.toml now say that dev-mode compiles only with sqlite, and that a production sqlite build leaves dev-mode off. The text of the dev-mode compile error changes to match, and its condition stays the same.
• docs/manuals/07-upgrade-manual.md splits its backup store paragraph into a list of how CreateBackup and RestoreTableFromBackup work in this release, followed by short paragraphs. The text changes in these points:
  • A later major release refuses CreateBackup without a backup store. Under the new policy, only a major release removes a deprecated item.
  • A store-backed restore whose server stopped, with no recorded progress, starts again from its first data file. It fails as target_not_empty only when the target holds more items than the backup. The text said that a stop inside the first data file on MongoDB, or inside the first batch on Cassandra, leaves target_not_empty.
  • kind = "disabled" silences only the warning about the default root on file-backed SQLite. CreateBackup still logs its deprecation warning on each call.
  • An S3 store needs spool_path on every backend except file-backed SQLite, where it defaults to backup-spool/ beside the database file.
  • A directory above a filesystem root can be writable by group or others only when it carries the sticky bit.
  • A PostgreSQL data database restored from a dump taken before migration 8 has no data table for the target of a running store-backed restore. The reconciler fails that restore and removes its target.
  • One catalog takes one server in 1.0. The text no longer says that a second server's store starts unhealthy. Both servers start healthy until the catalog has backup rows for the root.
  • A catalog re-created with init has an unhealthy store until extenddb backup sync --adopt-store makes the new catalog its owner. On file-backed SQLite with the default root, the store is unconfigured instead. The paragraph links the sections of the Backup and Restore manual for this and for instances that share a catalog.

Each decision in the new text has its own line here, so a reviewer can object to each one separately. The list omits text that only describes current behavior, such as the catalog statuses and their exit codes.

Scope and tiers:

• ExtendDB 1.0 is for local development, CI and self-hosted deployments, with one ExtendDB server for each catalog.
• Stable (PostgreSQL, and SQLite on a single node): for production. The versioning policy applies in full, and the ExtendDB CI is reliably green for the backend.
• SQLite is stable with no production image, so an operator builds it from source.
• Beta (MongoDB): for production within the known limits in the table, and the ExtendDB CI is reliably green for the backend. To remove a known limit, a minor release can change the listed behavior, and its release notes name the change.
• Experimental (Cassandra): for evaluation. The versioning policy does not apply, and a release can change the backend's behavior or configuration with no deprecation period.
• A backend moves up one tier in a minor release. Before that release, the maintainers agree in an issue that the ExtendDB CI has been reliably green for the backend. They also agree that its known limits fit the higher tier. The release notes name the move. A backend moves down a tier only through the deprecation steps.

Releases:

• The 2.0 release upgrades the catalog of any 1.x release.
• A minor release can carry a breaking catalog migration, and its release notes then say so.
• A minor release can raise the minimum Rust version for a build from source.
• A patch release adds no configuration key, no breaking catalog migration and no new backup format version.
• A change that makes ExtendDB answer a request as DynamoDB does ships in a minor release. It ships in a patch release only when it closes a security issue.

Compatibility within a major version:

• An operation, request member or response member that a release implements stays in the later releases.
• The keys of extenddb.toml, their EXTENDDB__ variables and the runtime settings keep their names and meanings.
• A configuration key that a minor release adds has a default that keeps the earlier behavior.
• The subcommands, flags and exit codes of the CLI stay, and the text of messages and log lines can change in any release.
• The management API that extenddb manage calls, and the options and return values of start() in @extenddb/dev, stay compatible.
• The HTTP status code of a /health response and its status field stay compatible.
• A minor release ends support for a database version only after the version's upstream end of life. The minor release before it announces the change.
• A release reads each backup format version that an earlier release wrote, and refuses a later one.
• The policy does not cover the Rust crate APIs (the Storage trait among them) or preview settings such as enable_multipart_keys.
• The policy does not cover the fields of a /metrics response or the experimental backends.

Support:

• The newest minor release gets bug fixes and security fixes.
• A fix for an earlier minor release ships in a patch release of its own, and the latest image tag stays on the newest release.
• The minor release before the newest one gets security fixes for 3 months after the newest one ships.
• After 2.0 ships, the last 1.x minor release gets security fixes for 12 months.
• The 0.1.x releases get no fixes after 1.0 ships.
• Support covers the stable and beta backends. An experimental backend gets fixes in the newest minor release only.

Deprecation:

• The release notes of the minor release that deprecates an item announce it and name what replaces it.
• For an item deprecated from 1.0 on, ExtendDB logs or prints a warning each time a request, a command or the configuration uses it.
• A major release removes a deprecated item, no earlier than 6 months after the release that announced it.
• The deprecation steps also apply when a release removes a stable or beta backend, or moves it to a lower tier.
• A security issue can need a faster change, and its release notes then give the reason.

This change does not edit the following text on main, which disagrees with it:

• docs/manuals/07-upgrade-manual.md says that MongoDB deployments track their own catalog version. Its first section says that a migration ledger versions all four catalogs.
• docs/adr/0023-catalog-migrations.md counts five v1.0 migrations. The migration registry lists nine.
• docs/cassandra-setup.md describes more than one ExtendDB instance on one Cassandra cluster.
• docs/manuals/11-deployment-guide.md says that more than one ExtendDB instance can share one backend catalog.
• docs/getting-started.md names its SQLite section "SQLite backend (developer mode)" and describes SQLite as a backend for local development and CI.
• docs/rfcs/0002-backend-plugin-policy.md says that all crates follow semantic versioning. The new policy does not cover the crate APIs.
• The TLS section of README.md says that TLS is mandatory. The new text says that dev mode uses plain HTTP.
• The Running in Containers section of README.md lists the Cassandra image among the production images. The new text says that the experimental tier is not for production.
• Other texts on main repeat backup statements that this change replaces in the upgrade manual. Issue backup: correct the target_not_empty rule, the store root ancestor rule and a remove-target pointer #942 lists them.

Known issues:

• The stable tier keeps PostgreSQL 14 as the minimum, as the README states it today. CI tests PostgreSQL 16 only, and PostgreSQL 14 reaches its upstream end of life on 2026-11-12. Issue docs: the PostgreSQL minimum says 14, and CI tests 16 only #898 decides between a CI job on 14 and a higher minimum in every file that states it.

Why

Issue #662 asks for three texts before 1.0: a scope statement, backend tiers in the README, and a versioning, compatibility, support and deprecation policy. An operator who chooses a backend reads the README first, so the scope and the tiers go there. The policy has six sections, so it gets a file of its own.

Closes #662

Testing done

• cargo test --locked -p extenddb-storage-postgres --test doc_version_literals passes. The test fails when a three-part version after the word ExtendDB in README.md or docs/ is not the compiled version.
• cargo fmt --all -- --check passes.
• Each link that this change adds resolves, anchors included.

Checklist

• I have read CONTRIBUTING.md
• All tests pass (cargo test --workspace)
• Code is formatted (cargo fmt --check)
• Clippy is clean (cargo clippy -- -W clippy::pedantic)
• I have added or updated tests for new functionality
• I have updated documentation if behavior changed
• Breaking changes are noted below (if any)
• If this changes the wire protocol, Storage trait, auth model, on-disk
  format, or public CLI surface, an RFC has been accepted or is linked
  below. Otherwise, an ADR captures the decision (link below).

ADR / RFC: n/a

---

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache License 2.0 and I agree to the Developer Certificate of
Origin (DCO). See CONTRIBUTING.md for details.

[jcshepherd]

Here and elsewhere it might help to clarify this with "SigV4 authentication" versus just "SigV4".

[LeeroyHannigan]

Changed in 093786c. The dev-mode comments in both Cargo.toml files now say "SigV4 authentication still enforced". The same short form is in the dev-mode banner, the dev-mode log warning, Dockerfile.dev and docker-compose.dev.yml, which this PR does not touch. #931 lists them.

[jcshepherd]

This paragraph could use some luv, especially if we expect humans to read it. It's a wall of text, has run-on sentences (at least one is paragraph-long in itself), contains a fair amount of implementation detail which may not help someone just trying to figure out the commands to run and what they do, and extraneous AI detail as in "a root that can no longer be opened is a startup error naming it" (just stop at "error").

[LeeroyHannigan]

Split in 0365f0c, then corrected in 7f937f0 and 1463d68. The paragraph is now a list of how CreateBackup and RestoreTableFromBackup work in this release, followed by short paragraphs. The cut detail covers progress rows, batch sizes and the identity checks. Two statements carried over from main were wrong, and 7f937f0 corrects both:

• A restore with no recorded progress starts again from its first data file. It fails as target_not_empty only when the target holds more items than the backup. The text said a stop inside the first data file on MongoDB, or the first batch on Cassandra, leaves target_not_empty.
• kind = "disabled" does not silence the deprecation warning on each CreateBackup. It silences the warning about the default root on file-backed SQLite.

The paragraph on several servers now says what the README says: one server per catalog in 1.0. It no longer says that a second server's store starts unhealthy. Both servers start healthy until the catalog has backup rows for the root. The sentence about a root that can no longer be opened stops at "a startup error".

[jcshepherd]

I'm reluctant to introduce tiers unless we have a process/policy for how a backend moves from one tier to another. I also thought that last week we'd converged on "a backend is production (or stable) if the ExtendDB CI is reliably green for it".

[LeeroyHannigan]

The three tiers are the ones #662 asks for, so I kept them. 9d136d2 and 4e44a88 add the rule for moving between them, built on that definition. Both tiers for production, stable and beta, now say that the ExtendDB CI is reliably green for the backend. A backend moves up one tier in a minor release. Before that, the maintainers agree in an issue that its CI has been reliably green and that its known limits fit the higher tier. It moves down only through the deprecation steps of the versioning policy.

[LeeroyHannigan]

Merged main in 2ec6290. #855 rewrote the same backup store paragraph of the upgrade manual. The resolution keeps the split and the corrections of this PR, and takes the two links to the Backup and Restore manual from #855.

8493d41 also changes these points in that paragraph:

• A directory above a filesystem root can be writable by group or others when it carries the sticky bit, as the check in crates/backup-store/src/fs.rs allows.
• A PostgreSQL data database restored from a dump taken before migration 8 has no data table for the target of a running store-backed restore. The reconciler fails that restore and removes its target.
• The admin guide describes backup remove-target in its [backup.store] section. The old pointer named a backup section, which does not exist.
• A catalog re-created with init has an unhealthy store until extenddb backup sync --adopt-store runs. On file-backed SQLite with the default root, the store is unconfigured instead.

#942 lists the texts on main that repeat the statements this PR corrects.