From c0c4ed6ce4aa347854db11bb04d030647ccc5c00 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Mon, 10 Aug 2026 17:06:52 -0500
Subject: [PATCH] Add RELEASE.md: this repo's pgxntool vendors branch-based
 tag/dist

This repo's vendored pgxntool predates git-tag-based releases: `make tag`
literally runs `git branch $(PGXNVERSION)` + push, not `git tag`. The
shared ../ai/RELEASE.md process (from Postgres-Extensions/ai#8) explicitly
anticipates this as a possible gotcha but assumes tags by default, so it
would be actively misleading here without this note. Verified 0.1, 0.1.0,
0.1.1, 0.2.0 are real historical release branches (ancestors of master),
not stale forks, and that git tag -l is empty.
---
 RELEASE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 RELEASE.md

diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..ac73276
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,51 @@
+# RELEASE.md
+
+This repo follows the shared release process in
+[`../ai/RELEASE.md`](https://github.com/Postgres-Extensions/ai/blob/main/RELEASE.md)
+(pending: that doc is currently on branch `release-process-doc`, not yet
+merged — see [ai#8](https://github.com/Postgres-Extensions/ai/pull/8))
+**except for one thing: this repo's vendored `pgxntool` predates the switch
+to git-tag-based releases.**
+
+## `make tag`/`make dist` create a git *branch*, not a tag
+
+The shared doc's own "Notes / gotchas" section anticipates this exact case:
+
+> `make tag`/`make dist` create a *real* git tag, despite older
+> `pgxntool/README.asc` wording describing the result as a "branch" — check
+> the vendored version's actual behavior if a repo's docs still say
+> "branch."
+
+In this repo, the vendored copy's behavior really does match the old
+wording — it's not just stale docs. `pgxntool/base.mk`'s `tag` target runs:
+
+```make
+tag:
+	git branch $(PGXNVERSION)
+	git push --set-upstream origin $(PGXNVERSION)
+```
+
+There is no `git tag` anywhere in this repo's history (`git tag -l` is
+empty). Every past release is a **branch** instead: `0.1`, `0.1.0`, `0.1.1`,
+`0.2.0` (all verified ancestors of `master` — real historical release
+points, not stale forks). `make dist` archives that branch ref the same way
+the shared doc describes archiving a tag, so distribution `.zip` creation
+itself works the same; only the ref type differs.
+
+Practical consequences when following `../ai/RELEASE.md` here:
+
+- **Step 1 (safety check)** and **step 6 (tag and distribute)**: everywhere
+  the shared doc says "the tag" or "`git tag -l`", read "the release
+  branch" / `git branch -r` instead. There is no tag to compare against.
+- **Idempotency differs.** The shared doc notes `make tag` is idempotent if
+  the tag already points at HEAD. That doesn't hold here: `git branch
+  $(PGXNVERSION)` refuses to create a branch that already exists at all
+  (even if it happens to point at the same commit), so re-running `make
+  tag` for an unchanged version still errors. `make forcetag` (`rmtag` +
+  `tag`) is the only way to redo it, same as the shared doc's guidance for
+  moving a tag.
+- `rmtag` deletes the local and remote **branch**, not a tag.
+
+If this ever gets re-vendored from a current pgxntool release, `make tag`
+will start creating real tags and this file can go away (delete
+`RELEASE.md` and rely on `../ai/RELEASE.md` alone once confirmed).