Record why temporal.sh was asserting nothing, and where else that bites

design/POSTGRESQL_VERSION_ADOPTION.md

@@ -19,7 +19,7 @@ date it was written. A note without one has not been checked.
 | --- | --- |
 | 1. Read stream and AIO | **shipped**, `pgcolumnar.enable_read_stream` (gap 29) |
 | 2. Virtual generated columns | **done**, read and storage both, `test/generated_columns.sh` |
-| 3. Temporal constraints | **done**, `test/temporal.sh` |
+| 3. Temporal constraints | **done** on 18 and 19, `test/temporal.sh`. Needs contrib `btree_gist`; without it the suite fails rather than passing quietly (#447, #448) |
 | 4. btree skip scan | open, no measurement |
 | 5. REPACK | **investigated and the conclusion was wrong**, see below (#399) |
 | 6. Statistics injection | open, no measurement |

docs/testing.md

@@ -136,6 +136,47 @@ All suites pass on PostgreSQL 15 through 19. PostgreSQL 19 is validated against
 19beta2; revalidation against the final PostgreSQL 19 release is pending that
 release.
 
+**A suite has three outcomes, and two of them are not failures.** Read which one
+you got before deciding whether something is wrong.
+
+| outcome | exit | when |
+| --- | :-: | --- |
+| `PASSED` | 0 | the suite ran its checks and they held |
+| `SKIPPED (ran no checks)` | 2 | the feature under test does not exist on this major |
+| `FAILED` | 1 | a check failed, **or** a tool the suite measures with is missing |
+
+The matrix prints `suites that ran: n of m (skipped: k)` for each major, and names
+the skipped suites. A skip counts in `k`, not in `n`.
+
+**A missing dependency fails rather than skips, and that is deliberate.** The box
+cannot gate that suite. Reporting a pass would claim coverage nobody has. Two
+dependencies come from outside this repository:
+
+| suite | needs | where it comes from |
+| --- | --- | --- |
+| the Arrow and Parquet suites | `pyarrow` | `pip install pyarrow`, as the user the suites run as |
+| `temporal.sh` | `btree_gist` | PostgreSQL **contrib**. A PGDG package ships it; a source build configured without contrib does not |
+
+Build and install `contrib/btree_gist` against each source tree when the matrix
+runs against source builds. To run knowingly without a dependency, waive it:
+
+```sh
+PGC_ALLOW_MISSING_BTREE_GIST=1 test/temporal.sh /path/to/pg_config
+PGC_ALLOW_MISSING=1            test/run_all_versions.sh
+```
+
+A waived suite reports `SKIPPED` and exits 2, so the coverage loss stays visible
+in the skipped count rather than becoming a pass.
+
+Measured on PostgreSQL 18, one suite, four configurations:
+
+| configuration | exit | verdict |
+| --- | :-: | --- |
+| `btree_gist` present | 0 | `PASSED`, 5 checks |
+| `btree_gist` absent | 1 | `FAILED` |
+| `btree_gist` absent, waived | 2 | `SKIPPED` |
+| PostgreSQL 17, feature absent | 2 | `SKIPPED (ran no checks)` |
+
 ## Cross-major upgrade
 
 `pg_upgrade` is the path that a user takes to a new major. It is also the point

test/temporal.sh

@@ -11,6 +11,19 @@
 # same result set. WITHOUT OVERLAPS needs a GiST index over the scalar key part,
 # so btree_gist must be available; the suite skips with a note if it is not.
 #
+# btree_gist is CONTRIB. A PGDG package ships it with postgresql-N, so CI has it. A
+# source build configured without contrib does not, and this suite then asserts nothing.
+# It reported PASSED while doing so until #447, and the local five-major matrix was
+# claiming temporal coverage on every major while running it on one.
+#
+# Since #448 a missing btree_gist FAILS rather than skips, because the box cannot gate
+# this suite and a pass would claim coverage nobody has. Build and install
+# contrib/btree_gist against each source tree, or set PGC_ALLOW_MISSING_BTREE_GIST=1 to
+# run knowingly without it, which reports SKIPPED and keeps the loss visible.
+#
+# A skip on 15, 16 and 17 is different and is correct: WITHOUT OVERLAPS does not exist
+# there, so there is nothing to gate.
+#
 # Usage:  test/temporal.sh [PG_CONFIG]
 #
 # Written fresh for pgColumnar; it does not reuse any upstream test file.