fix(ci): tag-major prepends v so floating tag matches docs

.github/workflows/tag-major.yml

@@ -2,9 +2,16 @@ name: tag-major
 
 # Maintains the floating `v0` major tag so users can pin `uses:
 # modern-python/semvertag@v0` and ride minor bumps. Skipped on
-# prereleases so an `v0.5.0-rc1` does not drag `v0` ahead of the latest
-# stable. When v1.0.0 ships, this same job creates `v1` automatically
+# prereleases so a `0.5.0-rc1` does not drag `v0` ahead of the latest
+# stable. When 1.0.0 ships, this same job creates `v1` automatically
 # from the tag name's leading segment.
+#
+# This project's release tags are bare semver (e.g. `0.4.0`, no `v`),
+# but the floating action tag is `v`-prefixed (`v0`) to match the GHA
+# convention for `uses: org/repo@vN`. The shell below strips any
+# leading `v` from RELEASE_TAG and unconditionally prepends one to the
+# major segment so the workflow works for both bare and v-prefixed
+# release tag styles.
 
 on:
   release:
@@ -27,8 +34,9 @@ jobs:
           RELEASE_TAG: ${{ github.event.release.tag_name }}
         run: |
           set -euo pipefail
-          # RELEASE_TAG = 'v0.4.0' → major = 'v0'
-          major="${RELEASE_TAG%%.*}"
+          # RELEASE_TAG = '0.4.0' (this project) or 'v0.4.0' (defensive) → major = 'v0'
+          raw="${RELEASE_TAG#v}"
+          major="v${raw%%.*}"
           git config user.name  'github-actions[bot]'
           git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
           git tag -fa "$major" "$RELEASE_TAG" -m "Update $major to $RELEASE_TAG"

planning/releases/0.4.0.md

@@ -27,25 +27,37 @@ Before tagging:
 - Confirm `branding.icon` is one of the Feather icon names GitHub accepts and `branding.color` is one of `white | yellow | blue | green | orange | red | purple | gray-dark`. (We ship `icon: tag`, `color: blue` — both valid.)
 - Confirm CI is green on main, including the new `action-smoke` job.
 
-### Step 2: Cut the v0.4.0 release
+### Step 2: Cut the 0.4.0 GitHub release
 
-Follow the project's existing release flow: tag, push, create a GitHub release. `publish.yml` fires on release creation and pushes to PyPI via `just publish` (which uses `uv version $GITHUB_REF_NAME` to inject the version at build time).
+This project's release tag convention is bare semver (`0.4.0`, no `v` prefix) — the same as 0.3.x and earlier. The `0.4.0` tag is created automatically by the dogfood workflow on PR merge, so it already exists when you reach this step.
+
+Create the GitHub release pointing at the existing tag:
+
+```sh
+gh release create 0.4.0 \
+  --title '0.4.0 — composite GitHub Action' \
+  --notes-file planning/releases/0.4.0.md
+```
+
+(Or use the GitHub web UI: Releases → "Draft a new release" → choose existing tag `0.4.0`.)
+
+`publish.yml` fires on release creation and pushes 0.4.0 to PyPI via `just publish` (which uses `uv version $GITHUB_REF_NAME` to inject the bare semver tag name as the package version).
 
 ### Step 3: Bootstrap the floating `v0` tag (one-time)
 
-The `tag-major.yml` workflow handles the floating tag on every release from v0.4.1 forward. For v0.4.0 specifically — the first release after the workflow landed — the floating tag does not yet exist and must be bootstrapped manually:
+Releases use bare semver tags (`0.4.0`) but the floating action tag is `v`-prefixed (`v0`) so consumers can write the conventional `uses: modern-python/semvertag@v0`. `tag-major.yml` handles the `v`-prefix bump automatically on every release from 0.4.1 forward. For 0.4.0 specifically — the first release after the workflow landed — the floating tag does not yet exist and must be bootstrapped manually:
 
 ```sh
 git fetch --tags
-git tag -fa v0 v0.4.0 -m 'Update v0 to v0.4.0'
+git tag -fa v0 0.4.0 -m 'Update v0 to 0.4.0'
 git push -f origin v0
 ```
 
 After this, `uses: modern-python/semvertag@v0` resolves successfully for consumers.
 
 ### Step 4: Publish to Marketplace (manual UI step)
 
-1. Navigate to https://github.com/modern-python/semvertag/releases/tag/v0.4.0.
+1. Navigate to https://github.com/modern-python/semvertag/releases/tag/0.4.0.
 2. Click **Edit release**.
 3. Check **Publish this Action to the GitHub Marketplace**.
 4. Accept the Marketplace Terms of Service if prompted (one-time for the repo).