[DMS-1194] Document DMS v1.0 Change Queries deferred features for v8.0 release notes

[samuellugo-ship-it]

What

Captures the reviewed DMS v1.0 / Ed-Fi API v8.0 "What's New" release-note text for the Change Queries deferred features as an in-repo handoff artifact, appended to the existing DMS-1194 design note. Documentation only — no runtime, API, ProblemDetails, OpenAPI, authorization, database, or test changes.

Why

DMS v1.0 ships Change Queries but intentionally defers snapshot/read-replica isolation, a way to disable the feature, and custom view-based ReadChanges authorization. Operators, Ed-Fi API Publisher users, and implementers must not assume ODS parity in these areas. The v8.0 release notes need to call these out explicitly. Source of truth: reference/design/backend-redesign/design-docs/change-queries.md ("Snapshot support is deferred" and "Out of scope").

Where the release notes actually live (reviewer: read this first)

This DMS repository has no release-notes/changelog file and no docs-site generator config. The canonical Ed-Fi "What's New" release notes are published from a separate repository:

• Published page: https://docs.ed-fi.org/reference/ed-fi-api/whats-new/whats-new-in-this-release/
• Source repo (Docusaurus): ed-fi-alliance-oss/ed-fi-alliance-oss.github.io
• Versioned path pattern: odsApi_versioned_docs/version-<X>/whats-new/whats-new-in-this-release.md (v8.0 is the "Upcoming" version)

Because of that, this PR does not (and cannot) apply the text to the live release notes — that is a follow-up PR in ed-fi-alliance-oss.github.io, performed by the docs team. This PR captures the reviewed, copy-paste-ready text in version control under the DMS-1194 design note so it is not lost and can be lifted verbatim into the v8.0 page.

What to review

1. The proposed release-note prose (the blockquote in the new "Proposed v8.0 release-note text" section) — accurate, complete, and appropriate for a public "What's New" page?
2. Faithfulness to change-queries.md:
   • Snapshot deferral / silent-ignore of Use-Snapshot, no Warning header, no snapshot ProblemDetails (lines 1907–1913)
   • API Publisher --ignoreIsolation=true operator guidance (line 1913)
   • No disable option; Feature Disabled ProblemDetails deferred (lines 1108–1112, 1976–1990)
   • Custom view-based ReadChanges unsupported; v8.1 target (lines 1108–1111, 1548)
3. No-internal-links policy: the public text intentionally omits design-doc and Jira links; follow-ups (DMS-1190 / DMS-1191 / DMS-1193, all targeted for v8.1) are recorded only in the in-repo "Destination & handoff notes" section, not in the published prose.

Wording guardrails honored (please sanity-check): Change Queries are not described as disabled/unavailable; Use-Snapshot is silent-ignore, not an error; no Feature Disabled ProblemDetails in v1.0; custom-view auth / snapshots / disable are not promised for v8.0.

Proposed release-note text (also in the diff)

Change Queries — deferred features in DMS v1.0

Change Queries are available in DMS v1.0 (Ed-Fi API v8.0), including the /deletes, /keyChanges, and /availableChangeVersions endpoints and the minChangeVersion/maxChangeVersion filters on live resource and descriptor GET-many endpoints. Several ODS capabilities are deferred in this release; do not assume full ODS parity in the following areas:

• Snapshot / read-replica isolation is not supported. The Use-Snapshot request header is not part of the DMS v1.0 Change Queries contract. DMS v1.0 silently ignores Use-Snapshot on /deletes, /keyChanges, /availableChangeVersions, and live resource/descriptor GET-many requests: the request is processed against current data without snapshot isolation, no Warning header is returned, and no snapshot-specific error is emitted.
• Ed-Fi API Publisher guidance. The Ed-Fi API Publisher sends Use-Snapshot: true by default when its source API major version is 7 or higher. Because DMS v1.0 silently ignores the header, reads from a DMS v1.0 source are not snapshot-isolated — concurrent writes against the source may be visible mid-publish and can produce inconsistent published data. When publishing from a DMS v1.0 source, run the Publisher with --ignoreIsolation=true to explicitly acknowledge that source isolation is unavailable (or accept the risk of inconsistent reads).
• No option to disable Change Queries. Change Queries are always on in DMS v1.0. DMS v1.0 does not provide the ODS-style ApiSettings:Features:ChangeQueries disable setting, and the corresponding Feature Disabled response is not part of the v1.0 contract.
• Custom view-based ReadChanges authorization is not supported. Custom view-based authorization strategies are not supported for the /deletes and /keyChanges Change Query endpoints in DMS v1.0. Other Change Query authorization strategies are supported, but Change Query authorization should not be assumed to be at full ODS parity.

Snapshot/read-replica support, a runtime option to disable Change Queries, and custom view-based ReadChanges authorization are planned for a later release (targeted for Ed-Fi API v8.1).

Changes

• Append two sections to reference/design/backend-redesign/epics/10-update-tracking-change-queries/32-document-v1-release-note-deferrals.md, leaving the original story content intact:
  • "Proposed v8.0 release-note text" — the publishable prose above
  • "Destination & handoff notes" — external destination repo/path/URL, the no-internal-links policy, and the v8.1 follow-ups (DMS-1190 / DMS-1191 / DMS-1193)
• Add a trailing newline to the file for .editorconfig insert_final_newline compliance.

Verification

• No repo-local docs validation exists (no mkdocs/docusaurus/markdownlint/prettier/remark config in this repo) — nothing to build or link-check locally.
• git diff --check clean; single file changed, additions only.

Out of scope

Applying the text to ed-fi-alliance-oss.github.io; any DMS runtime/API/ProblemDetails/OpenAPI/auth/DB/test behavior; implementing snapshot support, a disable flag, or custom view-based ReadChanges authorization (the v8.1 spikes DMS-1190 / DMS-1191 / DMS-1193).

Jira: https://edfi.atlassian.net/browse/DMS-1194

🤖 Generated with Claude Code