Add post-tag-version-bump to freeze default_version after a release

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`

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>>.