docs: state the tagged state, because the tag is what these four sentences outlive - #1100
Merged
Merged
Conversation
…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
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
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.
Four documents said
v1.0-alpha3was the latest published pre-release. True atthe moment of writing, and false for the entire life of the
v1.0-alpha4tag thatis cut from this commit.
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-alpha2andv1.0-alpha3both shipped the older form, so the project haspublished 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_versionbeing in development, which changes at cycle-open ratherthan 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.shmatched theclaim in one word order only. Three documents write "latest published pre-release
is
vX" and CHANGELOG.md writes "vXis the latest published pre-release", sothe 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:
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:
🤖 Generated with Claude Code
https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK