Skip to content

Move acceptance API docs to docs/ and fix hot failover rollback guidance - #25

Draft
fredzhang-aveva wants to merge 1 commit into
mainfrom
features/acceptance-api-docs
Draft

fredzhang-aveva wants to merge 1 commit into
mainfrom
features/acceptance-api-docs

Conversation

@fredzhang-aveva

Copy link
Copy Markdown
Collaborator

Move acceptance API docs to docs/ and fix hot failover rollback guidance

Work item:

Intent

Documentation-only change in preparation for release notes.

  • Move the awaitable scope (acceptance API) docs from Documentation/ to docs/acceptance-api/, so all framework docs live under docs/. Link ScopedWrites.md from the README "Additional documentation" list so the acceptance API docs are discoverable.
  • Fix the "Hot failover and disk buffers" section of docs/schema-partition-keys.md. It described V3 failover records and an older reader misreading them, but FailoverPersistentOmfMessageQueue always writes V6 records, and earlier releases (verified against v2.1.0) don't recognize V6 and skip them as corrupt. The rollback warning now says the buffer must be drained before rolling back, and cross-references the V5 endpoint-buffer limitation in the README.
  • Replace the ScopedWrites.md link to HotFailoverAcceptance.md, which was removed before the acceptance API merged, with a link to the README "Additional documentation" section.
  • Refer to the product as the Adapter Framework instead of an internal name in SidecarSlicingWalkthrough.md.

Alternatives considered

  • Keep the acceptance API docs in Documentation/. Rejected because the repo would keep two top-level doc folders with no clear split.
  • Restore HotFailoverAcceptance.md. Rejected because the README already covers hot failover behavior for scopes, and a separate page would duplicate it.

Breaking changes

None to code or packages. External links to Documentation/*.md on GitHub will break because the files moved to docs/acceptance-api/.

Not included

The README "Releases" section still lists 2.1.0. Main's build version is 2.1.1, but the release date and release notes URL aren't available yet.

Validation

  • Docs only; no source or test changes. All relative links under docs/ resolve.
  • Unit tests: dotnet test Src/AdapterFramework.sln passes, 3,262 tests, 0 failures.
  • dotnet format Src/AdapterFramework.sln --verify-no-changes and dotnet build -warnaserror fail on main with existing findings in untouched .cs files, such as CHARSET, IMPORTS, CA1848, and CA1852. This PR doesn't change those results.

Pipeline runs

  • GitHub CI (24390):
  • Signal Generator CI (24411):
  • Functional tests / ReleaseBuild (24325):

Move the awaitable scope (acceptance API) docs from Documentation/ to
docs/acceptance-api/ so all framework docs live under docs/, and link
them from the README.

Correct the hot failover section of docs/schema-partition-keys.md to
match the V6 failover buffer format. Every hot-failover record is
written as V6, and earlier releases skip V6 records as corrupt instead
of misreading them, so the buffer must be drained before rolling back.

Replace the ScopedWrites.md link to the removed HotFailoverAcceptance.md
with the README Additional documentation section, and refer to the
product as the Adapter Framework in the sidecar slicing walkthrough.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant