Versioning & Tagging

🏷️ Versioning & Tagging Guide

This page explains how the CI/CD pipelines handle versioning, Git tagging,
and release existence checks for preview, release candidate, and release builds.

---

🔖 Version Resolver

The Version Resolver workflow automatically determines the correct version string based on:

✅ Build type → preview, release_candidate, or release
✅ Git context → tag push, branch, pull request, or manual dispatch
✅ Manual version input → when provided and valid

It guarantees:

• No accidental overwrites
• Consistent version formats
• Smart handling of tag pushes vs. manual triggers

---

📖 Versioning Rules

Build Type	Source Logic	Resolved Example
release	Tag push (refs/tags/vX.Y.Z) or manual input (vX.Y.Z)	v1.2.3
release_candidate	Tag push (refs/tags/vX.Y.Z-rc.N), manual input, or auto-generate next -rc.N	v1.2.3-rc.1
preview	Branch name, PR number, manual override, or commit SHA	main, manual-main, PR-0001, commit-abc123

✅ Manual override

• If version input is provided and matches the expected format, it’s used directly.
• For RC builds, you can pass the full RC string (e.g., v1.2.3-rc.4) or a base (v1.2.3) to generate the next RC.

✅ RC auto-generation

• Uses .github/scripts/versioning/version-generator-for-rc.sh
  to increment the next available -rc.N suffix.

✅ Tag push handling

• On release or release_candidate tag pushes,
  the workflow trusts the tag and skips checking if a release exists (since Git won’t allow duplicate tags without a force push).

✅ Release existence check

• For non-tag-triggered builds, the workflow checks if the version already exists in GitHub releases
  and fails early to prevent overwrite.

---

🛡️ Error Safeguards

Scenario	Behavior
Pushed tag (vX.Y.Z or vX.Y.Z-rc.N)	Accepts the tag, skips duplicate check (Git ensures uniqueness)
Manual release input without tag	Requires valid vX.Y.Z format
Manual release_candidate input	Accepts either full vX.Y.Z-rc.N or base vX.Y.Z (auto-increment)
Duplicate version detected (non-tag)	Fails early to block overwrite

---

🏗️ Tagging Flow

Build Type	Tag Created?
preview	No tagging performed
release_candidate	Tag like v1.2.3-rc.1 created if missing
release	Tag like v1.2.3 created if missing

• Uses .github/scripts/tagging/check-tag-exists.sh and .github/scripts/tagging/create-tag.sh
  to check and create tags when needed.

---

📋 Workflow Summary

At the end of the pipeline, you get:

✅ Build type & trigger
✅ Resolved version string
✅ Whether the GitHub tag/release already existed
✅ Warnings or failures on collisions

You can view this summary directly in the GitHub Actions run summary.

---

💡 Practical Notes

• Manual dispatch:

  • You can trigger workflow_dispatch with:
    • buildType: release + version: v1.2.3
    • buildType: release_candidate + version: v1.2.3 (auto RC) or v1.2.3-rc.4 (exact RC)

• Tag pushes:

  • Git tags like v1.2.3 or v1.2.3-rc.1 skip release existence checks (since Git itself blocks duplicates).
  • If force-pushing tags, be aware: the system assumes you know what you’re doing.

• RC versioning script:

  • Located at .github/scripts/versioning/version-generator-for-rc.sh,
    this script scans existing tags and generates the next available -rc.N.

---