GA tag plan for Wheels 4.0.0 #2131

Background

Wheels 3.0.0 never got a clean v3.0.0 tag — only v3.0.0+N build-marker tags (+33 through +50). This makes it hard for docs and release notes to reference "3.0 final" unambiguously (the 4.0 feature audit had to use v3.0.0+33 as a proxy baseline).

For 4.0 GA, creating a clean v4.0.0 tag avoids repeating this problem.

Pre-GA checklist

• Pick the final commit on develop that will become 4.0.0 GA. Lock CI to green on it across the full engine × DB matrix.
• Update box.json version from 4.0.0-SNAPSHOT to 4.0.0. Commit as chore(config): bump version to 4.0.0 for GA.
• Rename [Unreleased] in CHANGELOG.md to [4.0.0] - YYYY-MM-DD (use actual GA date). Commit.
• Create annotated tag at the chosen commit: git tag -a v4.0.0 -m "Wheels 4.0.0". No +N suffix — this is the canonical marker.
• Push tag: git push origin v4.0.0.
• Create GitHub Release tied to v4.0.0. Body = the CHANGELOG [4.0.0] section (copy-paste), plus prominent link to Upgrading to Wheels 4.0.
• Bump develop to 4.1.0-SNAPSHOT in box.json after tagging. Commit as chore(config): bump version to 4.1.0-SNAPSHOT.

Workflow guard

• Review the snapshot-tag-creating workflow to ensure it does not create v4.0.0-SNAPSHOT+N after v4.0.0 is tagged (such a tag would conceptually be behind the GA tag and confuses downstream tooling).

  grep -l "SNAPSHOT" .github/workflows/

  Likely culprits: snapshot.yml, release workflows. Add a guard condition to skip when a non-SNAPSHOT version tag is present on HEAD.

Post-GA smoke tests

• gh release view v4.0.0 — confirm the Release is published and discoverable.
• gh pr list --milestone 4.0 — any PRs labeled for 4.0 should be closed.
• Update the "Recently Closed Gaps" header in docs/wheels-vs-frameworks.md from "April 2026" to "Wheels 4.0 (YYYY-MM-DD)".
• Announcement in #announcements (Slack / Discord / wheels.dev blog). See the blog post skeletons task for drafted themes.
• ForgeBox / CommandBox package registry — confirm 4.0.0 is published and resolvable via box install wheels@4.0.0.

Context / related work

These artifacts are the source material for the GA release and should be referenced when writing the Release body:

• 4.0 feature audit — 185-PR inventory grouped by subsystem (docs(release): add Wheels 4.0 feature audit #2123)
• 3.0 → 4.0 comparison — row-by-row breakdown of what changed (docs: add Wheels 3.0 → 4.0 ground-made-up comparison #2125)
• CHANGELOG [Unreleased] section — full Keep-a-Changelog layout ready to rename to [4.0.0] (docs(release): expand Unreleased section with full 4.0 changelog #2124)
• Upgrade guide — 10 Breaking items with detection, fix, and opt-out (docs: add Wheels 4.0 upgrade guide #2130)

🤖 Generated with Claude Code