docs: restyle ADR prose to Elements of Style - #2532
Open
zancas wants to merge 9 commits into
Open
Conversation
…ion ADR to 0018 ADR 0009 asserted that allow_v6_transactions vanished before any release carried it, leaving the wallet file format unchanged. ADR 0015 (PR #2529, merged to dev) supersedes that ruling: landing in dev ships the format, so version 42 names two on-disk layouts and the reader disambiguates them. The corrected sentence defers the format detail to ADR 0015. Because dev owns number 0015 for the wallet-format ADR, the branch-local migration ADR takes the next free number, 0018. The citations in ADR 0016 and in the quick_immediate_migration doc comment follow it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The concurrent mobile batch commit (f48b15c) introduced the part-anchors ADR as 0018 while the migration ADR was being renumbered to the same value. The part-anchors ADR keeps 0018, since the pushed branch already cites it by that number throughout migrate.rs and the migration store; the branch-local migration ADR takes 0019, and the citations in ADR 0016 and the quick_immediate_migration doc comment follow it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The citation in ADR 0016 and the doc-comment path in quick_immediate_migration still named 0018 after the renumber; both now point at 0019-immediate-migration-is-send-shaped.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Rewrite the prose portions of all fourteen ADRs in the style of Strunk and White's The Elements of Style. The pass activates passive voice, splits every semicolon into separate sentences, repairs sentence fragments, and removes needless words. Lists, headings, and every recorded fact, identifier, date, commit hash, and issue number are preserved, so no decision changes. Three titles change to satisfy the punctuation rules; the filenames, and therefore all links, do not. Add a "Durable documents" subsection to AGENTS.md so the standard persists: ADRs, CONTEXT.md, docs/, commit messages, and PR bodies follow The Elements of Style, the existing punctuation and construction rules keep force, and the vocabulary list yields to established domain terms. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A 2026-07-25 audit found two claims in ADR 0002 that no longer match reality. The Considered Options paragraph rejected re-homing the activation types into zcash_local_net partly because its dependencies included the zebra stack, but the current pin (rev 537f84d3d) has shed every zebra crate; the paragraph now dates that rationale and states the categorical argument that survives it. The Consequences section claimed release CI in zingolib, zingo-cli, zingo-mobile, and zingo-pc gains a feature-unification tripwire, but the audit found it implemented in none of the four projects; the bullet now states the requirement and cites issue #2533, which tracks the work and closes when the guard lands. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The paragraph recording the first observed warm run used "barriers" as a
verb ("replay barriers on Indexer convergence"), which a reader could
not parse. The three design fixes are now enumerated in plain sentences,
and the third states directly that the replay waits for the Indexer to
converge to the replayed tip before any wallet syncs. No fact changes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The state-directory paragraph cited bare 100s and a 150 for the finalization boundary. It now names the authorities: zebra's MAX_BLOCK_REORG_HEIGHT and its workspace mirror pepper_sync::sync::MAX_REORG_ALLOWANCE, with the 100 dated to when the record was written. A closing note records the 2026-07-25 finding that the zebra 6.0.0 tag raises MAX_BLOCK_REORG_HEIGHT to 1000, which widens the non-finalized window, strengthens the case against state-directory caches, and leaves the workspace mirror awaiting reconciliation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ADR 0006 now cites issue #2535, which enumerates the benefits of the withdrawn pure proposal mechanism so the trade can be repriced when a breaking-change window opens. The record's expiry claims are also corrected against the code. An Indexerless calculate_stored_proposal lifts the stored target to the last height of the wallet's consensus-branch epoch before building (retarget_for_offline_signing in zingolib/src/lightclient/send.rs), while a connected calculation keeps the ordinary DEFAULT_TX_EXPIRY_DELTA of forty blocks past the target. The "roughly forty blocks regardless of where it is held" durability argument is therefore dated to the time of the decision, and the churn argument now carries the rejection. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
zancas
force-pushed
the
docs/adr-strunk-white
branch
from
July 26, 2026 15:56
d06677d to
2ca4b83
Compare
(cherry picked from commit 2653ed0)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR restyles the prose of all fourteen ADRs to Strunk and White's The Elements of Style and persists that standard in AGENTS.md, so future durable documents are written to it.
The rewrite touches style only. Passive rejections become active ("was rejected" becomes "we rejected"), all fifty semicolons split into separate sentences, sentence fragments gain their subjects, "X, not Y" flips become "rather than", and needless words go. Every list, heading, fact, identifier, date, commit hash, and issue number is preserved, so no recorded decision changes. Three titles change to satisfy the punctuation rules (0006, 0008, 0009); the filenames, and therefore all links, are unchanged, and nothing outside
docs/adr/quotes the old titles.AGENTS.md gains a "Durable documents" subsection under
### Prose. It binds ADRs, CONTEXT.md, docs/, commit messages, and PR bodies to The Elements of Style, keeps the section's existing punctuation and construction rules in force, and exempts established domain terms (a CONTEXT.md entry, an API name, "send-shaped") from the vocabulary list.🤖 Generated with Claude Code