Skip to content

docs: state the tagged state, because the tag is what these four sentences outlive - #1100

Merged
jdatcmd merged 2 commits into
mainfrom
docs/alpha4-tag-state
Sep 17, 2026
Merged

jdatcmd merged 2 commits into
mainfrom
docs/alpha4-tag-state

Conversation

@jdatcmd

@jdatcmd jdatcmd commented Sep 17, 2026

Copy link
Copy Markdown
Collaborator

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: #1043 and #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 #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 #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

🤖 Generated with Claude Code

https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK

jdatcmd and others added 2 commits September 17, 2026 13:13
…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: #1043 and #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 #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 #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
`META.json` is what PGXN publishes, so its description outlives the tag the same
way the version claims do. It listed the capability set as of alpha3 and named
neither feature this release adds.

    skipping           zone maps and bloom filters
                    -> zone maps, bloom filters and star-schema join runtime filters
    layout             (absent)
                    -> Z-order and Hilbert clustering

`abstract` is left alone. It says what the extension IS rather than what it does,
and that has not changed.

Only the description key differs, verified by parsing both revisions and comparing
keys rather than by reading the diff: 13 top-level keys before and after, one key
changed.

    docs_style.sh          25 checks, PASSED, including the five META arms
    test_pgxn_metadata.py  12 checks, 4 passed

NOT VALIDATED AGAINST PGXN ITSELF. No validator is installed here, and this
repository has shipped a META.json the PGXN validator rejected before, checked
against a careful reading of a spec whose own examples are invalid. This change
only edits the value of a free-text key that every local check still passes, so
the risk is low, but the check that matters is the validator and it did not run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK
@jdatcmd
jdatcmd merged commit 0d3100d into main Sep 17, 2026
14 checks passed
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