The docs should explain the reasoning behind tracking version-specific extension install scripts, so extension authors can make an informed choice about which to commit.
Why track them at all
The primary value is update testing: commit an install script for an older version, install it, run ALTER EXTENSION <ext> UPDATE, and verify the update path works. In principle you would only need the very first version committed and could reach every later version via update scripts.
The reason to keep most old versions in practice: you cannot predict when a new major PostgreSQL version will break the ability to install an older extension version (e.g. a catalog column changes type or a SELECT * over a system catalog starts failing). Having the old version install scripts committed lets CI catch that a given extension version no longer installs on a newer PG. So for any non-trivial extension, most old versions should be tracked.
The exception
For a minor version change that does not significantly change the extension (e.g. a small bug fix), it is unlikely to cross a PostgreSQL supported-version boundary, so there is significantly less test-coverage value in committing that versions raw/generated install script. For relatively large extensions, deliberately NOT committing some of these individual version install scripts is worthwhile to reduce git repository size — the install script is regenerated from source at build time regardless.
Ask
Document this tradeoff in pgxntool (README/CLAUDE) alongside the .sql.in/.sql tracking guidance: track version install scripts by default for update-test coverage across PG version boundaries; it is acceptable to omit the generated install script for minor versions that do not meaningfully change the extension, especially in large repos.
Context: came up while deciding whether to commit the generated current-version install script for a small bug-fix release of cat_tools -- https://github.com/Postgres-Extensions/cat_tools
The docs should explain the reasoning behind tracking version-specific extension install scripts, so extension authors can make an informed choice about which to commit.
Why track them at all
The primary value is update testing: commit an install script for an older version, install it, run
ALTER EXTENSION <ext> UPDATE, and verify the update path works. In principle you would only need the very first version committed and could reach every later version via update scripts.The reason to keep most old versions in practice: you cannot predict when a new major PostgreSQL version will break the ability to install an older extension version (e.g. a catalog column changes type or a
SELECT *over a system catalog starts failing). Having the old version install scripts committed lets CI catch that a given extension version no longer installs on a newer PG. So for any non-trivial extension, most old versions should be tracked.The exception
For a minor version change that does not significantly change the extension (e.g. a small bug fix), it is unlikely to cross a PostgreSQL supported-version boundary, so there is significantly less test-coverage value in committing that versions raw/generated install script. For relatively large extensions, deliberately NOT committing some of these individual version install scripts is worthwhile to reduce git repository size — the install script is regenerated from source at build time regardless.
Ask
Document this tradeoff in pgxntool (README/CLAUDE) alongside the .sql.in/.sql tracking guidance: track version install scripts by default for update-test coverage across PG version boundaries; it is acceptable to omit the generated install script for minor versions that do not meaningfully change the extension, especially in large repos.
Context: came up while deciding whether to commit the generated current-version install script for a small bug-fix release of cat_tools -- https://github.com/Postgres-Extensions/cat_tools