Postgres-Extensions · jnasbyupgrade · Aug 4, 2026 · Aug 4, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -112,6 +112,15 @@ Rules for what to track in git:
 4. EXCEPTION to rule 2: a version that changes little AND ships no nontrivial update-path machinery MAY omit its generated install script (little test-coverage value; it is regenerated from `sql/cat_tools.sql.in` at build time). Track it whenever the version carries meaningful changes or a nontrivial update script — a complex update warrants the committed install script for update-test coverage and provenance.
 5. Version-specific files MUST NEVER be edited manually — always edit `sql/cat_tools.sql.in`
    and regenerate.
+6. EXCEPTION to rule 2 (and to pgxntool's own "don't `.gitignore` a skipped version, `rm`
+   it once" guidance — `pgxntool/README.asc`, "Don't `.gitignore` a Skipped Version"):
+   `sql/cat_tools--stable.sql.in` (the pseudo-version `default_version` sits at between
+   releases, see RELEASE.md) IS gitignored, not tracked. That guidance is about a version
+   that's normally tracked but occasionally skipped — a one-time, transient leftover file.
+   `stable` is the opposite case: it's *permanently* current between releases, so unlike a
+   skipped version it would be regenerated and re-diffed on every single source edit if
+   tracked, for zero test-coverage value (CI already builds+tests a fresh install from
+   source on every push regardless). See `sql/.gitignore`'s comment and RELEASE.md step 4.
 
 ## CI: PostgreSQL version support
 

diff --git a/HISTORY.asc b/HISTORY.asc
@@ -1,3 +1,6 @@
+STABLE
+------
+
 0.3.0
 -----
 New functions and types for working with routines and partitioned relations.

diff --git a/META.in.json b/META.in.json
@@ -14,7 +14,7 @@
     "name": "cat_tools",
 
     "X_comment": "REQUIRED. Version of the distribution. http://pgxn.org/spec/#version",
-    "version": "0.3.0",
+    "version": "stable",
 
     "X_comment": "REQUIRED. Short description of distribution.",
     "abstract": "Tools for interfacing with the Postgres catalog",
@@ -37,7 +37,7 @@
             "file": "sql/cat_tools.sql",
 
             "X_comment": "REQUIRED. Version the extension is at.",
-            "version": "0.3.0",
+            "version": "stable",
 
             "X_comment": "Optional: \"abstract\": Description of the extension.",
             "abstract": "Tools for interfacing with the catalog",

diff --git a/META.json b/META.json
@@ -14,7 +14,7 @@
     "name": "cat_tools",
 
     "X_comment": "REQUIRED. Version of the distribution. http://pgxn.org/spec/#version",
-    "version": "0.3.0",
+    "version": "stable",
 
     "X_comment": "REQUIRED. Short description of distribution.",
     "abstract": "Tools for interfacing with the Postgres catalog",
@@ -37,7 +37,7 @@
             "file": "sql/cat_tools.sql",
 
             "X_comment": "REQUIRED. Version the extension is at.",
-            "version": "0.3.0",
+            "version": "stable",
 
             "X_comment": "Optional: \"abstract\": Description of the extension.",
             "abstract": "Tools for interfacing with the catalog",

diff --git a/RELEASE.md b/RELEASE.md
@@ -64,6 +64,11 @@ what that version actually shipped.
 > moment this release is merged you **MUST** flip `default_version` back to `stable` on
 > master (step 7). If you forget, the next source edit on master will regenerate — and
 > corrupt — the just-released version's install file.
+>
+> `sql/cat_tools--<version>.sql.in` must ALWAYS be tracked — that's the entire point,
+> keeping a real history of the extension across releases. `stable` is the ONE exception
+> (its `.sql.in` is gitignored, not tracked) for the ONE reason that `stable` itself is
+> never actually released, so there's no history to keep.
 
 - [ ] Bump `default_version` in `cat_tools.control` (bumped by hand).
 - [ ] Bump the version in `META.in.json` — the source of truth is
@@ -118,10 +123,9 @@ what that version actually shipped.
       `STABLE` section in `HISTORY.asc`, and re-seed a fresh
       `sql/cat_tools--<this-release>--stable.sql.in` update script for the next cycle.
       Leaving master stamped at the real version means the next source edit regenerates
-      and corrupts the released version's install file.
-- [ ] `rm` any stale generated `sql/cat_tools--<released-version>.sql.in` /
-      `cat_tools--<released-version>.sql` left in the tree — once `default_version` is
-      `stable`, `make` no longer regenerates them, so they are one-time cleanup.
+      and corrupts the released version's install file. The just-released
+      `sql/cat_tools--<version>.sql.in` stays tracked, permanently — nothing to clean up
+      or remove there; see step 4's note above.
 
 > The persistent `stable` pseudo-version (a permanent version literally named `stable`,
 > with a live `sql/cat_tools--<last-release>--stable.sql.in` update script that every

diff --git a/cat_tools.control b/cat_tools.control
@@ -1,4 +1,4 @@
 comment = 'Tools for intorfacing with the catalog'
-default_version = '0.3.0'
+default_version = 'stable'
 relocatable = false
 schema = 'cat_tools'
diff --git a/sql/.gitignore b/sql/.gitignore
@@ -5,3 +5,7 @@ cat_tools.sql
 cat_tools--*.sql
 # Historical exceptions — no .sql.in source; must be tracked directly.
 !cat_tools--0.1.*.sql
+# The `stable` pseudo-version's .sql.in snapshot is pure derived output (a byte-for-byte
+# copy of cat_tools.sql.in, regenerated on every `make`), unlike a real release's
+# .sql.in -- so, unusually, it's ignored too rather than tracked.
+cat_tools--stable.sql.in
diff --git a/sql/cat_tools--0.3.0--stable.sql.in b/sql/cat_tools--0.3.0--stable.sql.in
-Original file line number
+Diff line change
@@ -1,3 +1,6 @@
+    STABLE
+    ------
 .3.0
     -----
     New functions and types for working with routines and partitioned relations.
@@ Expand Down @@