diff --git a/HISTORY.asc b/HISTORY.asc index bdd5121..b9bed1c 100644 --- a/HISTORY.asc +++ b/HISTORY.asc @@ -1,3 +1,22 @@ +STABLE +------ +== Add `make post-tag-version-bump` to freeze a just-released version +Committing versioned SQL files (`sql/{ext}--{version}.sql`) means ongoing +development after a release can silently regenerate and overwrite the file +that was just released, since `make` always regenerates whatever file +matches the current `default_version`. New target `post-tag-version-bump` +bumps each extension's `default_version` to a placeholder alias (`stable` +by default), so a subsequent `make` freezes the released file instead of +overwriting it. Deliberately a separate, explicit step rather than wired +into `tag`/`dist` -- both of those run routinely outside of an actual +release, and `dist` is documented to leave the repository clean, so +auto-bumping on every such run would break that guarantee. Controlled via +`PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP` (default `yes`) and +`PGXNTOOL_POST_TAG_VERSION` (default `stable`); `_.gitignore` now ignores +`sql/*--stable.sql` to match. + +Issues fixed in this release: #20 + 2.3.0 ----- == Rename `PGTLE_VERSION` to `PGXNTOOL_PGTLE_VERSION` diff --git a/README.asc b/README.asc index 45c4b59..883582e 100644 --- a/README.asc +++ b/README.asc @@ -262,6 +262,13 @@ If a tag for the current version already exists and points at your current commi WARNING: You will be very unhappy if you forget to update the .control file for your extension! There is an https://github.com/Postgres-Extensions/pgxntool/issues/1[open issue] to improve this. +[[_post_tag_version_bump]] +=== post-tag-version-bump + +Committing versioned SQL files (see <<_committing_version_files>>) means ongoing development after a release can silently regenerate and overwrite the file that was just released, since `make` always regenerates whatever file matches the current `default_version`. `make post-tag-version-bump` bumps each extension's `default_version` to a placeholder alias -- `stable` by default -- so a subsequent `make` instead regenerates `sql/{ext}--stable.sql`, keeping the released file frozen. + +This is a deliberate, separate step -- *not* wired into `tag` or `dist`. Both of those run routinely outside of an actual release (this project's own test suite calls `make dist` freely, and `dist` is documented to leave your repository clean), so tying a tracked `.control` file mutation to every such run would both break that guarantee and risk bumping `default_version` on a version nobody actually meant to release yet. Run `make post-tag-version-bump` yourself as an explicit step in your own release process, right after the tag you're actually releasing has been created and pushed. See `PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP` and `PGXNTOOL_POST_TAG_VERSION` below to control or disable this. + === dist `make dist` will create a .zip file for your current version that you can upload to PGXN. It first runs `tag` (creating/pushing the version's git tag as described above if needed), then uses `git archive` at that tag to build the .zip file, so the archive always matches the exact tagged commit. The file is named after the PGXN name and version (the top-level "name" and "version" attributes in META.json, generated from `META.in.json`). The .zip file is placed in the *parent* directory so as not to clutter up your git repo. @@ -678,6 +685,14 @@ Default: `origin`. The git remote used by `tag`, `rmtag`, `forcetag`, and `dist` make dist PGXN_REMOTE=upstream ---- +=== PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP * + +Default: `yes`. Set to `no` to make `make post-tag-version-bump` a no-op instead of bumping `default_version` -- useful if a shared release script always calls it but a specific project wants to opt out without editing that script. See <<_post_tag_version_bump>>. + +=== PGXNTOOL_POST_TAG_VERSION + +Default: `stable`. The placeholder value `make post-tag-version-bump` sets `default_version` to. Not valid semver, but PostgreSQL doesn't require semver for extension versions. If you override this, also update the `sql/*--stable.sql` line in your `.gitignore` to match. + === ASCIIDOC Default: auto-detected, the first of `asciidoctor` or `asciidoc` found on `PATH`. Path to the Asciidoc processor used to build `.html` files from `$(ASCIIDOC_EXTS)` source files. Override if the processor you want isn't first on `PATH`, or isn't on `PATH` at all. See <<_document_handling>>. diff --git a/README.html b/README.html index ba71c2a..2c828af 100644 --- a/README.html +++ b/README.html @@ -455,15 +455,16 @@

PGXNtool

  • 4.5. testdeps
  • 4.6. results
  • 4.7. tag
    • -
  • 4.8. dist
    • -
  • 4.9. pgxntool-sync
    • -
  • 4.10. pgxntool-version
    • -
  • 4.11. list
    • -
  • 4.12. print-%
    • -
  • 4.13. distclean
    • -
  • 4.14. pgtle
    • -
  • 4.15. check-pgtle
    • -
  • 4.16. run-pgtle
    • +
  • 4.8. post-tag-version-bump
    • +
  • 4.9. dist
    • +
  • 4.10. pgxntool-sync
    • +
  • 4.11. pgxntool-version
    • +
  • 4.12. list
    • +
  • 4.13. print-%
    • +
  • 4.14. distclean
    • +
  • 4.15. pgtle
    • +
  • 4.16. check-pgtle
    • +
  • 4.17. run-pgtle
  • 5. Version-Specific SQL Files @@ -499,18 +500,20 @@

    PGXNtool

  • 8. Configuration Variables
  • 9. Copyright
    • @@ -635,6 +638,18 @@

    Note +test exits non-zero (after printing regression.diffs) if any test fails. Previously it always exited 0 regardless of test results, silently masking failures from CI and other automation that relies on the exit code. + + + + +
    + + + + @@ -1036,7 +1051,16 @@

    4.
    -

    4.8. dist

    +

    4.8. post-tag-version-bump

    +
    +

    Committing versioned SQL files (see Committing Version Files) means ongoing development after a release can silently regenerate and overwrite the file that was just released, since make always regenerates whatever file matches the current default_version. make post-tag-version-bump bumps each extension’s default_version to a placeholder alias — stable by default — so a subsequent make instead regenerates sql/{ext}--stable.sql, keeping the released file frozen.

    +
    +
    +

    This is a deliberate, separate step — not wired into tag or dist. Both of those run routinely outside of an actual release (this project’s own test suite calls make dist freely, and dist is documented to leave your repository clean), so tying a tracked .control file mutation to every such run would both break that guarantee and risk bumping default_version on a version nobody actually meant to release yet. Run make post-tag-version-bump yourself as an explicit step in your own release process, right after the tag you’re actually releasing has been created and pushed. See PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP and PGXNTOOL_POST_TAG_VERSION below to control or disable this.

    +
    +
    +
    +

    4.9. dist

    make dist will create a .zip file for your current version that you can upload to PGXN. It first runs tag (creating/pushing the version’s git tag as described above if needed), then uses git archive at that tag to build the .zip file, so the archive always matches the exact tagged commit. The file is named after the PGXN name and version (the top-level "name" and "version" attributes in META.json, generated from META.in.json). The .zip file is placed in the parent directory so as not to clutter up your git repo.

    @@ -1069,9 +1093,9 @@

    -

    4.9. pgxntool-sync

    +

    4.10. pgxntool-sync

    -

    This rule will pull down the latest released version of PGXNtool via git subtree pull and then reconcile the files setup.sh copied into your project (.gitignore, test/deps.sql) with a 3-way merge.

    +

    This rule will pull down the latest released version of PGXNtool via git subtree pull and then reconcile the files setup.sh copied into your project (.gitignore, test/deps.sql) with a 3-way merge (it also verifies the test/pgxntool symlink, recreating it if missing).

    +
    Note
    +    		 While you can still run make installcheck or any other valid PGXS make target directly, it’s recommended to use make test when using pgxntool. The test target ensures proper test isolation and correct dependency installation.
    @@ -1135,7 +1159,7 @@

    -

    4.10. pgxntool-version

    +

    4.11. pgxntool-version

    make pgxntool-version prints the version of the embedded pgxntool copy, read from the first line of pgxntool/HISTORY.asc. That line is "STABLE" instead of a version number if this copy was synced from an unreleased commit rather than a tagged release.

    @@ -1153,19 +1177,19 @@

    -

    4.11. list

    +

    4.12. list

    make list prints every make target defined in your project — including ones provided by PGXS and pgxntool, not just ones you wrote — one per line. Useful for discovering what’s available without reading through the Makefile.

    -

    4.12. print-%

    +

    4.13. print-%

    make print-VARNAME prints the current value (and origin) of any make variable, e.g. make print-PGXNVERSION. Useful for debugging why a variable isn’t set to what you expect.

    -

    4.13. distclean

    +

    4.14. distclean

    make distclean removes generated configuration files (META.json — generated from META.in.json — plus meta.mk and control.mk) that survive a normal make clean.

    @@ -1191,7 +1215,7 @@

    -

    4.14. pgtle

    +

    4.15. pgtle

    Generates pg_tle (Trusted Language Extensions) registration SQL files for deploying extensions in managed environments like AWS RDS/Aurora. See [_pg_tle_Support] for complete documentation.

    @@ -1208,7 +1232,7 @@

    -

    4.15. check-pgtle

    +

    4.16. check-pgtle

    Checks if pg_tle is installed and reports the version. This target: - Reports the version from pg_extension if CREATE EXTENSION pg_tle has been run in the database @@ -1224,7 +1248,7 @@

    -

    4.16. run-pgtle

    +

    4.17. run-pgtle

    Registers all extensions with pg_tle by executing the generated pg_tle registration SQL files in a PostgreSQL database. This target: - Requires pg_tle to be installed in the target database. This isn’t a make-level dependency on check-pgtle — pgtle.sh checks it itself when it runs, and will tell you to run make check-pgtle if pg_tle isn’t there @@ -1881,73 +1905,85 @@

    -

    8.2. ASCIIDOC

    +

    8.2. PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP *

    +
    +

    Default: yes. Set to no to make make post-tag-version-bump a no-op instead of bumping default_version — useful if a shared release script always calls it but a specific project wants to opt out without editing that script. See post-tag-version-bump.

    +
    +
    +
    +

    8.3. PGXNTOOL_POST_TAG_VERSION

    +
    +

    Default: stable. The placeholder value make post-tag-version-bump sets default_version to. Not valid semver, but PostgreSQL doesn’t require semver for extension versions. If you override this, also update the sql/*--stable.sql line in your .gitignore to match.

    +
    +
    +
    +

    8.4. ASCIIDOC

    Default: auto-detected, the first of asciidoctor or asciidoc found on PATH. Path to the Asciidoc processor used to build .html files from $(ASCIIDOC_EXTS) source files. Override if the processor you want isn’t first on PATH, or isn’t on PATH at all. See Document Handling.

    -

    8.3. PGXNTOOL_PGTLE_VERSION

    +

    8.5. PGXNTOOL_PGTLE_VERSION

    Default: unset (generates every known pg_tle version range). Set on the command line to limit make pgtle to the single version range this value falls into. Not named PGTLE_VERSION: make auto-imports same-named environment variables, and that name collided silently with CI jobs that set a PGTLE_VERSION env var for an unrelated purpose (which pg_tle to test against). See pgtle.

    -

    8.4. PG_CONFIG

    +

    8.6. PG_CONFIG

    Default: pg_config. Path to the pg_config binary used to detect the PostgreSQL version and locate PGXS. Override when the right pg_config isn’t the one on PATH, such as when testing against a specific PostgreSQL install.

    -

    8.5. TESTDIR

    +

    8.7. TESTDIR

    Default: test. Root directory for test input files: $(TESTDIR)/sql/, $(TESTDIR)/expected/, $(TESTDIR)/build/, $(TESTDIR)/install/. Overriding this on its own is unusual; it mainly exists so TESTOUT has a sensible default.

    -

    8.6. TESTOUT

    +

    8.8. TESTOUT

    Default: $(TESTDIR). Directory pg_regress writes actual test output to — $(TESTOUT)/results/, $(TESTOUT)/regression.diffs, etc. — via --outputdir in REGRESS_OPTS. Kept separate from TESTDIR so generated output can be pointed somewhere other than the directory holding your checked-in sql/expected files, if you want that separation.

    -

    8.7. PGXNTOOL_VERIFY_RESULTS_MODE

    +

    8.9. PGXNTOOL_VERIFY_RESULTS_MODE

    Default: pgtap. Controls how the verify-results safeguard decides whether tests are failing.

    -

    8.7.1. pgtap

    +

    8.9.1. pgtap

    Scans test/results/*.out for pgTap not ok lines and plan mismatches, falling back to checking for regression.diffs too. Use this mode when your test suite uses pgTap.

    -

    8.7.2. diffs

    +

    8.9.2. diffs

    Checks only for regression.diffs, matching classic pg_regress behavior. Use this mode when your tests use plain SQL expected-output comparison only.

    -

    8.8. PGXNTOOL_ENABLE_TEST_BUILD *

    +

    8.10. PGXNTOOL_ENABLE_TEST_BUILD *

    Default: auto-detected — yes if test/build/*.sql files exist, no otherwise. Enables or disables the test-build pre-flight SQL check. Set explicitly to yes if you want an error when test/build/ unexpectedly has no SQL files (catches accidental deletion of its contents), or to no to disable the check even when files are present.

    -

    8.9. PGXNTOOL_ENABLE_TEST_INSTALL *

    +

    8.11. PGXNTOOL_ENABLE_TEST_INSTALL *

    Default: auto-detected — yes if test/install/*.sql files exist, no otherwise. Enables or disables the test/install schedule-based setup feature. Same explicit-override semantics as PGXNTOOL_ENABLE_TEST_BUILD.

    -

    8.10. PGXNTOOL_ENABLE_VERIFY_RESULTS *

    +

    8.12. PGXNTOOL_ENABLE_VERIFY_RESULTS *

    Default: yes. Enables or disables the verify-results safeguard that blocks make results when tests are failing. Setting it to empty on the command line (make PGXNTOOL_ENABLE_VERIFY_RESULTS= results) also disables it.

    -

    8.11. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *

    +

    8.13. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *

    Default: yes. Enables or disables the check-stale-expected safeguard, which fails make test if test/expected/ (or test/build/expected/) contains a .out file with no corresponding .sql file — catching a stale file left behind after a test was renamed or removed. Set to no to make the check a complete no-op (it’s dropped from TEST_DEPS entirely).

    @@ -1956,13 +1992,13 @@

    -

    8.12. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *

    +

    8.14. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *

    Default: yes. Sub-check of check-stale-expected, independent of PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED: fails (with a distinct error message and exit code from the orphaned-.out check) if test/expected/ (or test/build/expected/) contains any file that isn’t *.out. Set to no to disable just this sub-check while leaving the orphaned-.out check active.

    -

    8.13. PGXNTOOL_NO_PGXS_INCLUDE

    +

    8.15. PGXNTOOL_NO_PGXS_INCLUDE

    Default: unset (PGXS is included normally). Skips including PGXS ($(PGXS)) entirely. This is only for advanced scenarios where you need to manage the PGXS include yourself; most projects should never set this.

    @@ -1983,7 +2019,7 @@

    diff --git a/_.gitignore b/_.gitignore index 1873c2c..09c88f8 100644 --- a/_.gitignore +++ b/_.gitignore @@ -19,6 +19,10 @@ control.mk # built targets # Note: Version-specific files (sql/*--*.sql) are now tracked in git and should be committed +# Post-tag placeholder version's generated SQL file (see PGXNTOOL_POST_TAG_VERSION +# in README.asc's "tag" section). Update this line if you override that variable. +sql/*--stable.sql + # Test artifacts results/ regression.diffs diff --git a/base.mk b/base.mk index 00dab50..989a52c 100644 --- a/base.mk +++ b/base.mk @@ -579,6 +579,66 @@ tag: fi git push $(PGXN_REMOTE) $(PGXNVERSION) +# ------------------------------------------------------------------------------ +# post-tag-version-bump: freeze a just-released version, move to a placeholder +# ------------------------------------------------------------------------------ +# Purpose: control.mk.sh always regenerates the *current* version's SQL file +# (the one named after default_version) from the base sql/{ext}.sql on +# every `make`. Once a version has actually been released, further +# edits to sql/{ext}.sql would silently regenerate and overwrite that +# release's versioned SQL file the next time `make` runs. Moving +# default_version to a placeholder freezes it, without having to pick +# an arbitrary next semver number. +# +# Deliberately NOT wired into `tag`/`dist`: both of those are routinely +# invoked outside of an actual release (e.g. by this project's own test +# suite, or a CI job packaging a build for inspection), and `dist` in +# particular is documented and tested to leave the repository clean -- +# unconditionally dirtying a tracked .control file on every such run would +# both break that guarantee and risk bumping default_version on a version +# nobody actually meant to release yet. Invoke this target yourself as an +# explicit step in your own release process, right after the tag you're +# actually releasing has been created and pushed. +# +# Variable: PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP +# - Can be set manually in Makefile or command line +# - Allowed values: "yes" or "no" (case-insensitive) +# - Default: "yes" +# - Set to "no" to make this target a no-op -- useful if a shared release +# script always calls it but a specific project wants to opt out +# without editing that script +# +# Variable: PGXNTOOL_POST_TAG_VERSION +# - The placeholder value default_version is bumped to +# - Default: "stable" -- not valid semver, but PostgreSQL doesn't require +# semver for extension versions +# +# Variable: _POST_TAG_VERSION_BUMP_SCRIPT (internal shim, not user-facing) +# - Path to the script this target invokes to perform the bump +# - Default: $(PGXNTOOL_DIR)/bump-default-version.sh +# +ifdef PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP + # override needed so command-line values (make VAR=YES) are normalized, not silently ignored. + # := needed for immediate evaluation of the function call (avoids infinite recursion with =). + override PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP := $(call pgxntool_validate_yesno,$(PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP),PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP) +else + PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP = yes +endif + +PGXNTOOL_POST_TAG_VERSION ?= stable +_POST_TAG_VERSION_BUMP_SCRIPT ?= $(PGXNTOOL_DIR)/bump-default-version.sh + +ifeq ($(PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP),yes) +.PHONY: post-tag-version-bump +post-tag-version-bump: + @test -z "$$(git status --porcelain)" || (echo 'Untracked changes! Commit or stash before bumping default_version.'; echo; git status; exit 1) + $(_POST_TAG_VERSION_BUMP_SCRIPT) $(PGXNTOOL_POST_TAG_VERSION) $(PGXNTOOL_CONTROL_FILES) +else +.PHONY: post-tag-version-bump +post-tag-version-bump: + @echo "PGXNTOOL_ENABLE_POST_TAG_VERSION_BUMP=no: post-tag-version-bump is disabled, doing nothing" +endif + .PHONY: forcetag forcetag: rmtag tag diff --git a/bump-default-version.sh b/bump-default-version.sh new file mode 100755 index 0000000..7bc6298 --- /dev/null +++ b/bump-default-version.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +# +# bump-default-version.sh - Set default_version in one or more .control files +# +# Usage: bump-default-version.sh [ ...] +# +# Rewrites each control file's default_version line to , preserving +# everything else on that line (e.g. a trailing comment) and leaving the rest of +# the file untouched. +# +# Invoked by `make tag` (see base.mk) right after a new release tag is created, +# to move default_version to a placeholder alias (PGXNTOOL_POST_TAG_VERSION, +# default "stable") so ongoing development doesn't silently regenerate and +# overwrite the just-tagged version's versioned SQL file. Can also be run by +# hand for the same purpose. + +set -o errexit -o errtrace -o pipefail +trap 'echo "Error on line ${LINENO}"' ERR + +BASEDIR=$(dirname "${BASH_SOURCE[0]}") +source "$BASEDIR/lib.sh" + +if [ $# -lt 2 ]; then + die 1 "Usage: $0 [ ...]" +fi + +new_version="$1" +shift + +for control_file in "$@"; do + [ -f "$control_file" ] || die 2 "Control file '$control_file' not found" + + # Same one-line-only requirement control.mk.sh enforces when reading + # default_version -- keeps writing and reading in agreement about what a + # valid control file looks like. + count=$(grep -cE "^[[:space:]]*default_version[[:space:]]*=" "$control_file") || count=0 + if [ "$count" -ne 1 ]; then + die 2 "Expected exactly one default_version line in '$control_file', found $count" + fi + + # Capture the assignment prefix (indentation + "default_version = ") and + # everything after the closing quote (e.g. a trailing comment) untouched; + # only the quoted value itself is replaced, and always re-quoted with single + # quotes regardless of the original quote style. + tmp_file=$(mktemp "${control_file}.XXXXXX") + sed -E "s/^([[:space:]]*default_version[[:space:]]*=[[:space:]]*)(['\"])[^'\"]*\\2/\\1'${new_version}'/" \ + "$control_file" > "$tmp_file" + mv "$tmp_file" "$control_file" + echo "Set default_version = '${new_version}' in $control_file" +done