From adc7f6c42cdd496c1c01bd3d49bd1c9f7da9630d Mon Sep 17 00:00:00 2001
From: Prashansa Kulshrestha <prashkulshrestha@gmail.com>
Date: Thu, 24 Sep 2026 11:12:47 +0530
Subject: [PATCH] docs: document the v3 tag publish flow (#455)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- The Publish section still said to "Rebase \`v3\` branch on \`main\`",
but \`v3\` is a moving tag, not a branch — that instruction has been
stale since the v3.0.0 release moved the action to the tag-based
versioning convention.
- Documents the actual publish flow: create a \`vX.Y.Z\` release, wait
for its E2E run to pass, then move the \`v3\` tag with \`git tag -f\` +
\`git push --force\`.
- Adds a note that \`v1\`/\`v2\` predate this convention and remain real
branches, so contributors aren't confused by the difference.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3a7afd4..8fc308e 100644
--- a/README.md
+++ b/README.md
@@ -173,13 +173,30 @@ need to perform a few setup steps before you can work on the action.
 
 ## Publish
 
-1. Create a new GitHub release
-2. Rebase `v3` branch on `main`
+1. Create a new GitHub release tagged `v3.X.Y`, targeting the commit on `main`
+   you want to publish:
+
+   ```bash
+   gh release create v3.X.Y --target <merge-commit-sha> --title v3.X.Y --notes "..."
+   ```
+
+2. Wait for the tag's E2E workflow run to pass
+3. Move the `v3` major-version tag to that same commit:
+
+   ```bash
+   git fetch --force origin main --tags
+   git tag -f v3 <merge-commit-sha>
+   git push --force origin refs/tags/v3
+   ```
 
 Your action is now published! :rocket:
 
-See the
-[versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
+> [!NOTE]
+>
+> `v3` is a moving tag, not a branch — it always points at the latest
+> `v3.x.y` release, per the
+> [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md).
+> `v1` and `v2` predate this convention and remain real branches.
 
 ## Validate