From 6bd60ded33c7a6bb8afcb475bfa25ef2dd3d37ae Mon Sep 17 00:00:00 2001 From: "Joshua D. Drake" Date: Thu, 17 Sep 2026 13:13:28 -0600 Subject: [PATCH 1/2] docs: state the tagged state, because the tag is what these four sentences 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) Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK --- CHANGELOG.md | 4 ++-- README.md | 4 ++-- docs/installation.md | 4 ++-- docs/roadmap.md | 4 ++-- test/docs_style.sh | 33 +++++++++++++++++++++++++++------ 5 files changed, 35 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e2ec9be1..fa90354a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,8 @@ pre-release; the version marker is `1.0-alpha4`, recorded in `VERSION`. New tabl are written in the native on-disk format, PGCN v1. For the forward-looking plan see [design/ROADMAP.md](design/ROADMAP.md); for full history see the git log. -The extension's `default_version` is `1.0-alpha4`, which is in development and not -yet tagged; `v1.0-alpha3` is the latest published pre-release. Upgrade scripts from +The extension's `default_version` is `1.0-alpha4`. +`v1.0-alpha4` is the latest published pre-release. Upgrade scripts from every previously shipped version ship with it (`1.0-dev`, which the v1.0-alpha tag installed, `1.0-alpha`, `1.0-alpha2`, and `1.0-alpha3`), so a single `ALTER EXTENSION pgcolumnar UPDATE` reaches `1.0-alpha4` from any of them. Older diff --git a/README.md b/README.md index ffcb3f8d..6003867d 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,8 @@ append-mostly data. pgColumnar builds from one source tree on PostgreSQL 15 through 18, with 19 validated against 19beta2, and is licensed under the [MIT License](LICENSE). It is [pre-release](docs/limitations.md#release-status); the version marker -is `1.0-alpha4`, recorded in `VERSION`. That version is in development and not -tagged; the latest published pre-release is `v1.0-alpha3`. A table `USING pgcolumnar` is stored in the +is `1.0-alpha4`, recorded in `VERSION`. +The latest published pre-release is `v1.0-alpha4`. A table `USING pgcolumnar` is stored in the native on-disk format, PGCN v1. ## Documentation diff --git a/docs/installation.md b/docs/installation.md index c31ec6e4..9c6e7d5f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -152,8 +152,8 @@ columnar table with it. ### Upgrading to 1.0-alpha4 -`1.0-alpha4`, recorded in `VERSION`, is what this source tree installs. It is in -development and not tagged; the latest published pre-release is `v1.0-alpha3`. +`1.0-alpha4`, recorded in `VERSION`, is what this source tree installs. The +latest published pre-release is `v1.0-alpha4`. `ALTER EXTENSION pgcolumnar UPDATE` (step 3 above) reaches it from every previously published version: `1.0-dev`, which the `v1.0-alpha` tag installed, `1.0-alpha`, `1.0-alpha2`, and `1.0-alpha3`. PostgreSQL applies the shipped diff --git a/docs/roadmap.md b/docs/roadmap.md index 75ea14f9..d3aeff7b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -12,8 +12,8 @@ Issues are the authority on anything being worked now. ## Status pgColumnar is [pre-release](limitations.md#release-status). The version marker is -`1.0-alpha4`, recorded in `VERSION`. That version is in development and not tagged; the -latest published pre-release is `v1.0-alpha3`. A table `USING pgcolumnar` is stored in the +`1.0-alpha4`, recorded in `VERSION`. The +latest published pre-release is `v1.0-alpha4`. A table `USING pgcolumnar` is stored in the native on-disk format, PGCN v1. ## Releases to 1.0 diff --git a/test/docs_style.sh b/test/docs_style.sh index 692e6712..4902a2fe 100755 --- a/test/docs_style.sh +++ b/test/docs_style.sh @@ -263,15 +263,36 @@ _pubdocs="$(grep -rln 'latest published pre-release' \ check "premise: at least one document names the latest published pre-release" \ "$([ -n "$_pubdocs" ] && echo yes || echo no)" "yes" +# BOTH WORD ORDERS, because the four documents do not agree on one. Three write +# "latest published pre-release is `vX`" and CHANGELOG.md writes "`vX` is the +# latest published pre-release". A pattern for one order silently parses three +# files and skips the fourth, which is the REFERENCE document, so the check would +# have compared the copies to each other and exempted the original. +# +# The per-file count is what makes that visible: a file that mentions the claim +# and yields no version is a file this rule cannot see, and it is named rather +# than skipped. # shellcheck disable=SC2086 -_pubvers="$(grep -rhoE 'latest published pre-release is `v[^`]*`' $_pubdocs 2>/dev/null \ - | grep -oE '`v[^`]*`' | tr -d '`' | sort -u)" -check "premise: the claim was parsed, not merely present" \ - "$([ -n "$_pubvers" ] && echo yes || echo no)" "yes" +_pubvers="$( { grep -rhoE 'latest published pre-release is `v[^`]*`' $_pubdocs 2>/dev/null + grep -rhoE '`v[^`]*` is the latest published pre-release' $_pubdocs 2>/dev/null + } | grep -oE '`v[^`]*`' | tr -d '`' | sort -u)" +_pubunparsed="" +for _d in $_pubdocs; do + grep -qE 'latest published pre-release is `v[^`]*`|`v[^`]*` is the latest published pre-release' \ + "$_d" || _pubunparsed="$_pubunparsed $(basename "$_d")" +done +check "every document making the claim states it in a form this rule can read" \ + "$(printf '%s' "$_pubunparsed" | sed 's/^ //')" "" + +# A DISTINCT SENTINEL, not "". An empty extraction would otherwise compare "" to +# "" and report PASS having read nothing, which is #1096's defect exactly: the +# premise caught it there and the headline still said PASS. check "every document names the same latest published pre-release" \ - "$([ "$(printf '%s\n' "$_pubvers" | grep -c .)" = 1 ] && echo "" \ - || printf '%s' "$_pubvers" | tr '\n' ' ' | sed 's/ $//')" "" + "$([ "$(printf '%s\n' "$_pubvers" | grep -c .)" = 1 ] \ + && printf '%s' "$_pubvers" \ + || printf 'DISAGREE:%s' "$(printf '%s' "$_pubvers" | tr '\n' ',' | sed 's/,$//')")" \ + "$(printf '%s\n' "$_pubvers" | head -1)" # ---- and META.json, which NOTHING read at all ------------------------------ # From 5370968df8ca80e4d25b85a3cbcf15acc7390207 Mon Sep 17 00:00:00 2001 From: "Joshua D. Drake" Date: Thu, 17 Sep 2026 13:26:42 -0600 Subject: [PATCH 2/2] docs: META.json's description predates two alpha4 features `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) Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK --- META.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/META.json b/META.json index 6c9d10ba..99c48541 100644 --- a/META.json +++ b/META.json @@ -1,7 +1,7 @@ { "name": "pgcolumnar", "abstract": "Analytic column storage for PostgreSQL, built as a native table access method", - "description": "pgColumnar is a columnar storage table access method for PostgreSQL, written as a clean-room, MIT-licensed implementation. It reads and writes its own native format, PGCN v1, and supports chunk-group skipping from zone maps and bloom filters, vectorized aggregation, projections, retention, online compaction and reclustering, parallel bulk ingest and export, Apache Arrow and Parquet import and export, Apache Iceberg, and object storage.", + "description": "pgColumnar is a columnar storage table access method for PostgreSQL, written as a clean-room, MIT-licensed implementation. It reads and writes its own native format, PGCN v1, and supports chunk-group skipping from zone maps, bloom filters and star-schema join runtime filters, vectorized aggregation, projections, Z-order and Hilbert clustering, retention, online compaction and reclustering, parallel bulk ingest and export, Apache Arrow and Parquet import and export, Apache Iceberg, and object storage.", "version": "1.0.0-alpha.4", "maintainer": [ "Joshua D. Drake "