Skip to content

Fix three stale documentation references #39

Description

@HectorIFC

Context

A repo-wide sweep for statements the code no longer supports turned up three, all small and all misleading to a reader trying to understand what exists:

  1. lib/malachi/cluster/dsrsm.ex:16-18 says that sharding a topic's ranges by range id across vnodes and vnode split are "deferred to a later increment". Vnode split ships: lib/malachi/cluster/vnode_split.ex, split_coordinator.ex and mix malachi.reshard all exist and are tested. Only the range-id sharding half of that sentence is still true.
  2. docs/guides/clustering-and-resharding.md:176-178 says the ring-durability gap "is tracked as follow-up in Architecture". docs/ARCHITECTURE.md contains no such entry: the pointer is dangling. (The gap itself is tracked in its own issue now.)
  3. zero_copy_plan.txt:32 references NORTHGUARD_PORT.md, a roadmap file that was removed from the tree; its history lives only in commits.

None of these change behaviour, and none of them are worth a separate slice on their own, but together they are the difference between docs a reader can trust and docs a reader has to verify against the code.

Plan

  1. Rewrite the dsrsm.ex moduledoc sentence so it defers only range-id sharding, and mention that vnode split shipped, with the module that implements it.
  2. Point the clustering guide at whatever actually tracks ring durability (the issue), or add the follow-up entry to docs/ARCHITECTURE.md and keep the pointer.
  3. Fix or drop the NORTHGUARD_PORT.md reference in zero_copy_plan.txt.
  4. While in there, re-run the sweep for the same class of defect: statements of the form "not yet", "deferred", "roadmap", "planned" that the code has since overtaken.

Risks and open questions

  • None material. The only trap is fixing the words without checking the claim, which is how these three got stale in the first place: each fix should be verified against the code it describes.

Verification

  • grep for the corrected phrases returns nothing stale.
  • Full suite and mix credo --strict unchanged (documentation-only change, no behaviour).

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Projects

Status
Backlog

Relationships

None yet

Development

No branches or pull requests

Issue actions