From ca3cab340baadae4a91bab4546068eb5e95aba15 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 16 Jun 2026 13:30:15 -0700
Subject: [PATCH] fix(release): annotate version tag + correct release push
 instructions (#1517)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- set-version: create the release tag with `git tag -a -m` instead of a
  lightweight `git tag`, which fails ("no tag message?") when a contributor has
  tag.forceSignAnnotated / required-annotation set globally — it silently broke
  the v0.6.107 tag step.
- CONTRIBUTING: replace `git push origin main --tags` (pushes every local tag →
  whole push rejected on any pre-existing collision) with pushing the specific
  tag, and document the monotonicity guard (stale higher tag blocks tagging).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md        | 7 ++++++-
 scripts/set-version.ts | 8 +++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2a4b200c4..307c3cc2b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -140,11 +140,16 @@ All packages use **fixed versioning** — every release bumps all packages to th
 
 ```bash
 bun run release:prepare 0.2.0        # drafts changelog if needed, then creates the release commit/tag after review
-git push origin main --tags           # triggers the publish workflow
+git push origin main                  # push the release commit
+git push origin v0.2.0                # push the tag → triggers the publish workflow
 ```
 
+> Push the **specific tag**, not `git push --tags` — the latter pushes every local tag and the whole push is rejected if any one already exists on the remote.
+
 The `release:prepare` script drafts missing release notes on the first run and stops for manual review. After the generated TODO summary is rewritten, rerun the same command; it delegates to `set-version`, which creates a `chore: release v<version>` commit and a `v<version>` git tag. Pushing the tag triggers CI to publish all packages to npm and create a GitHub Release.
 
+`set-version` also refuses to tag if a **higher** semver tag already exists (a stale higher tag would hijack tag-sorting installers like `npx skills`). Delete the stray tag (`git tag -d <tag> && git push origin :refs/tags/<tag>`) or, only if intentional, pass `--skip-monotonicity-check`.
+
 ### Pre-releases (alpha / beta / rc)
 
 Use a pre-release suffix to publish to a named npm dist-tag instead of `latest`:
diff --git a/scripts/set-version.ts b/scripts/set-version.ts
index eae35d79f..0241626a6 100644
--- a/scripts/set-version.ts
+++ b/scripts/set-version.ts
@@ -130,7 +130,13 @@ function createReleaseCommitAndTag(version: string, skipMonotonicityCheck: boole
     cwd: ROOT,
     stdio: "inherit",
   });
-  execFileSync("git", ["tag", `v${version}`], { cwd: ROOT, stdio: "inherit" });
+  // Annotated tag (-a -m): works regardless of a contributor's git config; a
+  // lightweight `git tag` fails ("no tag message?") when tag.forceSignAnnotated
+  // or similar is set globally.
+  execFileSync("git", ["tag", "-a", `v${version}`, "-m", `v${version}`], {
+    cwd: ROOT,
+    stdio: "inherit",
+  });
   console.log(`\nCreated commit and tag v${version}`);
 }