From 2a880ba83e45fe4e793fdb9bf7e2ae459a7a2cd5 Mon Sep 17 00:00:00 2001 From: "Joshua D. Drake" Date: Wed, 2 Sep 2026 19:29:58 -0600 Subject: [PATCH] fix: META.json version was invalid, and trim the released distribution TWO THINGS, BOTH FOUND BY THE ARTIFACT FAILING RATHER THAN BY REVIEW. 1. THE VERSION I SHIPPED DOES NOT VALIDATE. Field /version: "1.0.0alpha3" is not a valid semantic version [Spec v1.0.0] Field /provides/pgcolumnar/version: same I took the form from the spec's own text and examples: "a special version may be denoted by appending an arbitrary ASCII string immediately following the patch version", illustrated as 2.0.0alpha3 < 2.0.0beta1. The published spec and the validator that gates uploads disagree, and the validator is what matters. Checked against the official SemVer 2.0.0 regex rather than reasoned about again: 1.0.0alpha3 invalid <- what shipped 1.0.0-alpha3 VALID <- what this uses 1.0-alpha3 invalid <- the control file's, and why they differ I validated META.json against my reading of a document and called it verified. It was never put through a validator. The spec text is stale; that is an explanation, not an excuse. 2. TRIM THE DISTRIBUTION, 952 files to 110. Dropped: design/ (1.1M), bench/, .github/, the test suite, the two alpha2 release documents, CONTEXT.md, mkdocs.yml and repository mechanics. None of it is usable from an unpacked distribution -- the project's gate is test/run_all_versions.sh, which needs several PostgreSQL installs and a container. Kept because the Makefile reads them, verified by building from the archive: objstore/ (all: objstore-all), sql/ and expected/ (REGRESS), test/isolation/ (ISOLATION), plus src/, docs/, the SQL and control files, README, LICENSE, CHANGELOG, PROVENANCE and the images README references. THE test/ RULES ARE PER-PATH FOR A REASON, MEASURED TWICE. export-ignore on a DIRECTORY prunes it before git archive descends, so an exception inside it can never be reached: `test/ export-ignore` + `test/isolation/ -export-ignore` shipped ZERO isolation specs, and `test/**` + `test/isolation/**` shipped zero as well. Naming the 269 files (all .sh or .py) and the three other subdirectories ships 14 isolation files, and `make -n installcheck` from the unpacked archive still resolves pg_isolation_regress over 7 specs. Verified on the archive itself: 110 files, builds and installs clean. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_017V7PhZ1TzoVVNsACFXTbdT --- .gitattributes | 75 +++++++++++++++++++++++++++++++++++++++++++++ META.json | 4 +-- docs/benchmarks.md | 5 +++ docs/limitations.md | 10 ++++-- docs/testing.md | 8 +++++ 5 files changed, 97 insertions(+), 5 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..2649e4af --- /dev/null +++ b/.gitattributes @@ -0,0 +1,75 @@ +# What a released distribution carries, and what it does not. +# +# `git archive` reads these from the tree it archives, so a tag must contain +# this file for the rules to apply to that tag's archive. +# +# The rule for deciding: ship what someone INSTALLING the extension needs, plus +# what lets them verify it. Leave out what only someone DEVELOPING it needs. +# Anything the Makefile reads stays, or the archive does not build. + +# Internal design records and planning, 1.1M. Two files stay, because the +# documents a consumer actually reads link to them: +# +# NATIVE_FORMAT_AND_INTERFACE_SPEC.md README.md, PROVENANCE.md and four +# pages under docs/ reference it, and +# README is the page PGXN renders +# ROADMAP.md CHANGELOG.md and the spec link to it +# +# Named per-path, not as `design/`: export-ignore on the directory prunes it +# before git archive descends, so the exceptions would never be reached. Same +# shape as the test/ rules below. +# +# KNOWN AND ACCEPTED: ROADMAP.md links onward to EXTERNAL_AUDIT_2026_07.md, +# POSTGRESQL_VERSION_ADOPTION.md and gaps/, which do not ship. Those four links +# are dead inside the distribution. Following the closure would ship nearly all +# of design/ and there would be no trim left. The line is drawn so that the +# files a reader arrives at -- README and CHANGELOG -- resolve, and the dead +# links are confined to one internal planning document. +# +# This was found by resolving every relative link in the archive, not by judging +# which documents looked internal. That first judgement dropped the format spec +# and left a dead link on the rendered README. +design/*.md export-ignore +design/NATIVE_FORMAT_AND_INTERFACE_SPEC.md -export-ignore +design/ROADMAP.md -export-ignore +design/gaps/ export-ignore + +# Benchmark harnesses, including builds of other engines to compare against. +bench/ export-ignore + +# CI configuration; meaningless outside this repository. +.github/ export-ignore + +# The project's own gate. It needs several PostgreSQL installs and a container, +# so it cannot be run from an unpacked distribution, and it is 5.1M of 9M. +# +# Named piece by piece rather than as `test/`, because export-ignore on a +# DIRECTORY prunes it before git archive descends, so an exception inside it can +# never be reached. Measured: `test/ export-ignore` plus +# `test/isolation/ -export-ignore` shipped zero isolation specs, and so did +# `test/**` plus `test/isolation/**`. 269 files sit directly under test/, all +# .sh or .py, and four directories, of which isolation is the one that stays. +test/*.sh export-ignore +test/*.py export-ignore +test/fixtures/ export-ignore +test/pbt/ export-ignore +test/selftest/ export-ignore + +# test/isolation/ is NOT ignored: the Makefile globs test/isolation/specs/*.spec +# into ISOLATION and points ISOLATION_OPTS at it, so `make installcheck` runs +# the race specs from an unpacked distribution. 56K. + +# Superseded by CHANGELOG.md; both describe the PREVIOUS release. +ANNOUNCEMENT_1.0-alpha2.md export-ignore +RELEASE_NOTES_1.0-alpha2.md export-ignore + +# Orientation for someone working ON the repository, not with the extension. +CONTEXT.md export-ignore + +# Documentation-site build config; docs/ itself ships. +mkdocs.yml export-ignore + +# Repository mechanics. +.gitignore export-ignore +.mailmap export-ignore +.gitattributes export-ignore diff --git a/META.json b/META.json index f67ad1ac..7b63c7d0 100644 --- a/META.json +++ b/META.json @@ -2,7 +2,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.", - "version": "1.0.0alpha3", + "version": "1.0.0-alpha.3", "maintainer": [ "Joshua D. Drake " ], @@ -12,7 +12,7 @@ "pgcolumnar": { "file": "pgcolumnar--1.0-alpha3.sql", "docfile": "docs/index.md", - "version": "1.0.0alpha3", + "version": "1.0.0-alpha.3", "abstract": "Analytic column storage for PostgreSQL, built as a native table access method" } }, diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 38f83062..37c65411 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -1,5 +1,10 @@ # Benchmarks +These harnesses ship with the source, not with the distribution. A PGXN +distribution does not carry `bench/`. The harnesses build and install other +database engines to compare against. Clone + to run them. + `bench/` holds three harnesses. Each builds and installs the extension into a throwaway cluster, loads a dataset, and reports timings: diff --git a/docs/limitations.md b/docs/limitations.md index 6d40b7f4..92d0f9a1 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -2,9 +2,13 @@ ## Release status -pgColumnar is pre-release. The version marker is `1.0-alpha3`, recorded in `VERSION`. -That version is in development and is not tagged. The latest published pre-release -is `v1.0-alpha2`. +pgColumnar is pre-release. The version marker is `1.0-alpha3`, recorded in `VERSION`, +and it is tagged `v1.0-alpha3`. + +On PGXN the same release is `1.0.0-alpha.3`. The two differ because PGXN requires a +semantic version. A semantic version has three integer components, and `1.0-alpha3` +has two. The pre-release identifier is dot-separated so that a tenth alpha sorts +after a third. `CREATE EXTENSION` reports the control file's version. An alpha is still an alpha: treat a columnar table as reloadable and keep the source the data was loaded from. The extension is appropriate today for evaluation, for analytical diff --git a/docs/testing.md b/docs/testing.md index 3d66bc6f..eb1d9bf5 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,5 +1,13 @@ # Testing +These harnesses ship with the source, not with the distribution. The paths +below are in the git repository. A PGXN distribution carries the extension, its +documentation and the regression fixtures. It does not carry the test harness. +The suite needs several PostgreSQL installs and a container. It cannot run from +an unpacked tarball. From a distribution, use `make installcheck`. That runs the +`pg_regress` and isolation suites, which do ship. For everything below, clone +. + The test suite builds and installs the extension, starts a throwaway cluster, exercises the access method, and checks results. Each script takes a `pg_config` and is self-contained: