docs: alpha4 release notes, and the three version claims that drifted - #1099
Conversation
Audit of the user-facing documentation before the 1.0-alpha4 tag. Five findings,
all fixed here.
RELEASE NOTES. alpha2 and alpha3 each have a RELEASE_NOTES_*.md and alpha4 had
none. Written from what a user can see rather than from the changelog: the
upgrade script, the GUC defaults, and the feat/fix commits touching src/. The
[Unreleased] section runs to 4,229 lines and is almost entirely harness work, so
counting its entries would have produced the wrong highlights.
THE LATEST-RELEASE CLAIM DRIFTED A WHOLE CYCLE. README.md, docs/roadmap.md and
docs/installation.md all said the latest published pre-release was v1.0-alpha2
while v1.0-alpha3 was tagged. CHANGELOG.md was the only one right.
docs/installation.md was the worst of the three and shows why the existing gate
missed them. It never writes the phrase "recorded in `VERSION`", so it sat
outside that check entirely, and it also carried a stale heading, a stale tree
version, and an upgrade chain that stopped at 1.0-alpha2.
A GATE FOR THE SECOND CLAIM. docs_style.sh now checks that every document naming
the latest published pre-release names the same one. This is agreement rather
than comparison, and the comment says so: no tracked file records the newest tag,
and reading `git tag` fails in a tree copied without .git, which this harness runs
from. It catches one document drifting from the others, which is what happened.
It cannot catch all of them being stale together, and the release procedure now
carries that step instead.
THE HEADLINE FEATURE WAS FILED UNDER Fixed. Hilbert clustering sat under
### Fixed. Moved to ### Added, verified positional: the sorted multiset of lines
is identical before and after, so nothing was lost or reworded.
ALPHA5 HAS NO SCOPE LEFT. Both its planned items shipped in alpha4. Verified
rather than assumed, each absent from v1.0-alpha3 and present in main:
9f7dcd8 perf: prune scattered IN lists by element (#752)
ae623cb feat: add serial join runtime range filter (#752)
cbd0c2e feat: add serial join runtime Bloom filter (#752)
60ddc10 feat: turn join runtime filter on by default (#752)
Recorded in the plan. docs/roadmap.md still publishes "join acceleration" as
alpha5's theme, which is now a promise about delivered work, and re-theming it is
the owner's call rather than an edit to make during an audit.
A RELEASE CHECKLIST. design/RELEASE_PLAN_1.0.md never mentioned release notes,
which is why the step was skipped rather than deferred. It now carries the
documentation steps and the tag steps, including capturing the fixture FROM THE
TAG (#901).
Verification:
docs_style.sh 25 checks, PASSED
plain_language_check.py ok on docs/*.md, README.md and the new notes
test_docs_cover_the_corpus.py 98 checks, 38 passed
docs_style.sh is registered but uncovered by the ledger, has no pytest twin and
is in neither COMPLETE nor INCOMPLETE, so its two new checks carry no ledger or
parity obligation.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK
`## [Unreleased]` becomes `## [1.0-alpha4] - 2026-09-17`, which is the step the alpha3 release did in its own release-notes PR (`9628414`, #886) rather than after the tag. Following that precedent so the tag points at a tree whose changelog already names the release. The paragraph above the heading still says the version is "in development and not yet tagged". That is what `v1.0-alpha2` and `v1.0-alpha3` both shipped, so it is left alone here rather than changed during a tag. It is worth settling at cycle-open: a tagged tree that says it is untagged is a sentence a reader can falsify by having downloaded it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK
…d for
`docs/roadmap.md` published "join acceleration" as alpha5's theme after alpha4
shipped it, so the public schedule promised work already delivered.
The themes shift by one. No date moves and no scope is invented:
1.0-alpha4 layout, skipping, and join acceleration was "skipping and layout"
1.0-alpha5 encoding: adaptive cascade selection was "join acceleration"
1.0-alpha6 Parquet partition inference was both encoding and Parquet
1.0-beta1 feature freeze unchanged
Alpha6 held two items and now holds one, because adaptive cascade encoding
selection moves up into the slot alpha5 vacated. Alpha6 is still the last alpha.
Alpha4's row also gains the two corrections an audit should make: its date is the
date the tag is cut, 2026-09-17, rather than the 2026-09-15 target, and alpha3's
row reads 2026-09-02 to match its tag rather than its 2026-09-01 target.
design/RELEASE_PLAN_1.0.md is updated to match, with the encoding item moved
between its two sections rather than restated.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK
|
Reviewed against the tree rather than the description. The audit is sound and I would land it — but the second thing you asked about is bigger than you flagged, and it is a one-line class of fix you have spent two days removing from this repo. What I verifiedThe new agreement arm works as shipped: All four documents now agree, and Your alpha5 finding reproduces exactly. The four commits are all
The thing I would change before taggingYou flagged the CHANGELOG's "in development and not yet tagged". The same defect is in four documents, not one, and it is the more visible half: All four are true right now and all four become false the instant the tag exists — including the sentence in README, which is the first thing anyone reads. The timing asymmetry is what decides it for me. The tag is cut from this merge commit, so whatever it says is what that tag says for the rest of its life. Writing
Writing Precedent is the argument against, and I do not think it survives: alpha2 and alpha3 shipped this same falsehood, which means the project has published it three times, and #1043 / #1088 were both this class — a document telling a reader something the tree falsifies. Following the precedent here ships a fourth. Your instinct that it belongs at cycle-open is right about the On the roadmap, I land between your two optionsYou framed it as re-theme (a scope decision, not yours) or leave it. There is a third: Striking a claim that is now false is an audit edit; choosing what replaces it is the scope decision. You can do the first without the second — say the scope is unset and why — and leave the theme to the owner. Publishing a roadmap that promises work already delivered is the same defect as the four sentences above, and One small thing in the new armIf Not blockingThe Fixed → Added move for Hilbert is right, and verifying it positionally with a sorted-multiset comparison is the correct proof for a move. Agreed on holding #1098 out of the tag. It is test-only, and the restore path is the part I would want reviewed slowly rather than at tag speed. |
…ences outlive
Four documents said `v1.0-alpha3` was the latest published pre-release. True at
the moment of writing, and false for the entire life of the `v1.0-alpha4` tag that
is cut from this commit.
CHANGELOG.md:10 README.md:27 docs/roadmap.md:16 docs/installation.md:156
The timing is what decides it. The tag is cut FROM this tree, so whatever these
say is what the tag says permanently. Naming alpha4 is wrong for the minutes
between this commit and the tag. Naming alpha3 is wrong for as long as the tag
exists, and README is the first thing a reader opens.
`v1.0-alpha2` and `v1.0-alpha3` both shipped the older form, so the project has
published this three times. That is a reason to stop rather than a reason to
continue: commandprompt#1043 and commandprompt#1088 were both this same class, a document telling a reader
something the tree falsifies, and removing that class is most of two days' work.
Raised by @OffgridwithJD reviewing commandprompt#1099. The half they left alone is the half
about `default_version` being in development, which changes at cycle-open rather
than at the tag. Those read as one sentence and are two claims with two clocks,
so the sentences are now split.
THE CHECK COULD NOT SEE ITS OWN REFERENCE DOCUMENT. `docs_style.sh` matched the
claim in one word order only. Three documents write "latest published pre-release
is `vX`" and CHANGELOG.md writes "`vX` is the latest published pre-release", so
the rule parsed the three copies and skipped the original. It compared the copies
to each other and exempted the one they are copied from.
Both orders are read now, and a file that states the claim in a form the rule
cannot parse is NAMED rather than skipped. Proved by mutation, both directions:
README disagrees FAIL got [DISAGREE:v1.0-alpha3,v1.0-alpha9]
CHANGELOG unparseable FAIL got [CHANGELOG.md]
The agreement check also compared "" against "" and passed when the extraction
came back empty. That is commandprompt#1096's defect exactly, where the premise caught it and
the headline still reported PASS. It carries a distinct sentinel now. Raised by
@OffgridwithJD.
That rule then caught this change: splitting the sentence put the claim across two
lines, and grep is line-based, so two documents became unreadable to it. Rewrapped.
Verification:
docs_style.sh 25 checks, PASSED
plain_language_check.py 0 failures across docs/, README, release notes
test_docs_cover_the_corpus.py 98 checks, 38 passed
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK
2 participants
Audit of the user-facing documentation before the 1.0-alpha4 tag. Five findings,
all fixed here.
RELEASE NOTES. alpha2 and alpha3 each have a RELEASE_NOTES_*.md and alpha4 had
none. Written from what a user can see rather than from the changelog: the
upgrade script, the GUC defaults, and the feat/fix commits touching src/. The
[Unreleased] section runs to 4,229 lines and is almost entirely harness work, so
counting its entries would have produced the wrong highlights.
THE LATEST-RELEASE CLAIM DRIFTED A WHOLE CYCLE. README.md, docs/roadmap.md and
docs/installation.md all said the latest published pre-release was v1.0-alpha2
while v1.0-alpha3 was tagged. CHANGELOG.md was the only one right.
docs/installation.md was the worst of the three and shows why the existing gate
missed them. It never writes the phrase "recorded in
VERSION", so it satoutside that check entirely, and it also carried a stale heading, a stale tree
version, and an upgrade chain that stopped at 1.0-alpha2.
A GATE FOR THE SECOND CLAIM. docs_style.sh now checks that every document naming
the latest published pre-release names the same one. This is agreement rather
than comparison, and the comment says so: no tracked file records the newest tag,
and reading
git tagfails in a tree copied without .git, which this harness runsfrom. It catches one document drifting from the others, which is what happened.
It cannot catch all of them being stale together, and the release procedure now
carries that step instead.
THE HEADLINE FEATURE WAS FILED UNDER Fixed. Hilbert clustering sat under
Fixed. Moved to ### Added, verified positional: the sorted multiset of lines
is identical before and after, so nothing was lost or reworded.
ALPHA5 HAS NO SCOPE LEFT. Both its planned items shipped in alpha4. Verified
rather than assumed, each absent from v1.0-alpha3 and present in main:
Recorded in the plan. docs/roadmap.md still publishes "join acceleration" as
alpha5's theme, which is now a promise about delivered work, and re-theming it is
the owner's call rather than an edit to make during an audit.
A RELEASE CHECKLIST. design/RELEASE_PLAN_1.0.md never mentioned release notes,
which is why the step was skipped rather than deferred. It now carries the
documentation steps and the tag steps, including capturing the fixture FROM THE
TAG (#901).
Verification:
docs_style.sh is registered but uncovered by the ledger, has no pytest twin and
is in neither COMPLETE nor INCOMPLETE, so its two new checks carry no ledger or
parity obligation.
🤖 Generated with Claude Code
https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK