From f7ddc6929c221a96e1d2d78708d8033c5314f1a8 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 16 Sep 2026 16:11:05 +0000
Subject: [PATCH] docs: floating @v0 Action tag process and publish retag (#71)

Document exact vs floating pins, note that @v0 can receive breaking 0.x
changes, and automate moving the v0 tag to each v0.x.y release commit in
publish.yml after PyPI publish.

Co-authored-by: Abhinaysai Kamineni  <askmy-stack@users.noreply.github.com>
---
 .github/workflows/publish.yml | 27 +++++++++++++++++++++++-
 docs/github-action.md         | 39 ++++++++++++++++++++++++++++++-----
 2 files changed, 60 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index a4d08a5..1103203 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
+  contents: write
   id-token: write
 
 jobs:
@@ -24,3 +24,28 @@ jobs:
         run: python -m build
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Move floating major tag v0 → this release commit (v0.x.y only).
+  # Exact pins (@v0.4.0) remain preferred; @v0 is convenience and may break.
+  retag-v0:
+    if: >
+      github.event_name == 'release' &&
+      startsWith(github.event.release.tag_name, 'v0.')
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.release.tag_name }}
+      - name: Force-update floating v0 tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -f v0 "$RELEASE_TAG"
+          git push origin refs/tags/v0 --force
diff --git a/docs/github-action.md b/docs/github-action.md
index 21a2fe7..5bf2731 100644
--- a/docs/github-action.md
+++ b/docs/github-action.md
@@ -12,12 +12,31 @@ askmy-stack/tool-semantics/.github/actions/compare
 ## Versioning the Action
 
 Pin the composite Action to a **release tag** (or commit SHA) so consumer CI stays
-reproducible. Tags follow the package version (`v0.4.0`, …). A floating major pin
-such as `@v0` is fine once a `v0` moving tag exists; prefer an exact tag for
-production workflows.
+reproducible. Tags follow the package version (`v0.4.0`, …).
 
-`@main` tracks the tip of the default branch and **may break** without notice —
-use it only for local experiments.
+| Pin | Stability | When to use |
+| --- | --- | --- |
+| `@v0.4.0` (exact) | Fixed | **Preferred** for production workflows |
+| `@v0` (floating major) | Moves on each `v0.x.y` release | Convenience; still receives breaking 0.x changes |
+| `@main` | Tip of default branch | Local experiments only — **may break** without notice |
+
+### Maintaining the floating `@v0` tag
+
+On every `v0.x.y` GitHub Release, move the lightweight `v0` tag to the same
+commit as the exact version tag (force-update). The `Publish to PyPI` workflow
+does this automatically after a successful release publish when the tag name
+matches `v0.*`.
+
+Maintainer one-liner (if you need to repair the tag outside CI):
+
+```bash
+git fetch origin tag v0.4.0
+git tag -f v0 v0.4.0
+git push origin refs/tags/v0 --force
+```
+
+`@v0` can still receive **breaking 0.x** changes — prefer `@v0.4.0` (or newer
+exact tags) when reproducibility matters.
 
 After each GitHub Release, the tagged tree includes this composite Action, so
 `uses: askmy-stack/tool-semantics/.github/actions/compare@vX.Y.Z` resolves from
@@ -45,6 +64,7 @@ jobs:
         run: |
           pip install "tool-semantics==0.4.0"
           tool-semantics capture manifests/candidate.json -o .tool-semantics/candidate.json
+      # Preferred: exact release pin
       - uses: askmy-stack/tool-semantics/.github/actions/compare@v0.4.0
         with:
           baseline: .tool-semantics/baselines/github.json
@@ -54,6 +74,15 @@ jobs:
           upload-artifacts: "true"
 ```
 
+Convenience pin (receives breaking 0.x updates):
+
+```yaml
+      - uses: askmy-stack/tool-semantics/.github/actions/compare@v0
+        with:
+          baseline: .tool-semantics/baselines/github.json
+          candidate: .tool-semantics/candidate.json
+```
+
 ## Inputs
 
 | Input | Required | Default | Description |