Skip to content

docs(architecture): match the docs to the code - #136

Merged
mrcsin merged 2 commits into
masterfrom
docs-code-sync
Oct 16, 2026
Merged

mrcsin merged 2 commits into
masterfrom
docs-code-sync

Conversation

@mrcsin

@mrcsin mrcsin commented Oct 16, 2026

Copy link
Copy Markdown
Member

Problem

An audit of docs/architecture/* and AGENTS.md against the code found about 70 places where the docs said something the code does not do. Some of them could mislead an operator or a developer:

  • bench.md called the converge drop "unconditional"; Converge.RequireBenchDatabase refuses any database without the semiplot_ prefix and semiplot_provisioned itself.
  • Three docs and three code comments called any row in tpdefault a fault; only rows with t >= current_date are one, and no client code reads tpdefault.
  • Docs described reads that do not exist: the effective statement_timeout after a failure, the messages table, and a bad-quality sample being dropped.
  • AGENTS.md called CA1416 a warning; TreatWarningsAsErrors makes it an error on both CI legs.

What changed

  • Claims with no code behind them removed or restated as the code behaves: statement_timeout, messages, bad quality (drawn as an ordinary point; no such code appeared in either measured archive), tpdefault, the converge guard.
  • Counts, member names and lists brought to the code: ArchiveFailureMapper.Map arms, ArchiveFault kinds, TrendChartView subscriptions, the main window's view-side requests, container registrations, settings validation order, test class lists, brush consumers, the two two-minute container bounds, the export path's day reads and conversions.
  • The decisions log in trend-interaction.md gains three as-built notes (realtime double, the q = 32 break, the archive layers).
  • ui-text.md gains owner sections for the MessagePanel*, Navigation*, Legend* and About* keys.
  • README.md lists postgres-topology.md; sources.md drops three never-cited markers and cites [FORUM:1454].
  • History phrasing removed from the living docs; the decision records and the decisions log keep theirs.
  • Comment-only edits in PartitionScript.cs, SeededArchiveTests.cs, PartitionScriptTests.cs and AppHost.cs.

Left open, because the code does not settle them: which row a repeated extreme keeps in a coarse layer (sources.md and scada-archive.md describe two vendor builds), and the vendor claim in the LayerThinner comment.

Verification

  • Every finding was rechecked against this branch's base before the edit.
  • Every *.md#anchor reference in the docs, AGENTS.md and the code resolves to a heading; every sources.md marker is cited.
  • terse clean on the four .cs files.

Audit of docs/architecture and AGENTS.md against the code: stale counts and member names, claims no code backs (statement_timeout read, messages read, bad-quality drop), the tpdefault rule, the converge database guard, owner sections for four key families, and history phrasing in living docs.
@mrcsin
mrcsin merged commit 4f7ec88 into master Oct 16, 2026
2 checks passed
@mrcsin
mrcsin deleted the docs-code-sync branch October 16, 2026 15:04
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