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