Versioning & Tagging

🏷️ Versioning & Tagging Guide

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

📐 Semantic Versioning

This pipeline follows Semantic Versioning (SemVer) with the format: v<MAJOR>.<MINOR>.<PATCH>[-rc.<N>]

• MAJOR: Incompatible API or project changes
• MINOR: Backwards-compatible functionality additions
• PATCH: Backwards-compatible bug fixes
• -rc.N: A pre-release release candidate version (e.g., v1.2.3-rc.1)

Release candidates use a -rc.N suffix and are automatically incremented unless explicitly specified.
Final releases must match the format vX.Y.Z exactly and be tagged accordingly.

---

🔖 Version Resolver Overview

The Version Resolver determines the correct version string for each CI/CD run based on: ✅ The build type (preview, release_candidate, release)
✅ The Git context (tag push, branch, pull request, or manual trigger)
✅ Any manual version override provided

It guarantees:

• Consistent and predictable version formats
• Automatic handling of tag creation and release checks
• Protection against accidental overwrites or duplicate releases

---

📋 How It Works

Build Type	Version Format Example	Tagging Behavior
preview	main, manual-main, PR-0001, commit-abc123	No tag created
release_candidate	v1.2.3-rc.1 (auto-increment) or provided v1.2.3-rc.N	Creates tag if missing
release	v1.2.3 (from tag or input)	Creates tag if missing

---

🛠️ Inputs

When triggering the workflow, provide:

• buildType:

  • preview → non-tag, branch or PR-based builds
  • release_candidate → builds for -rc.N versions
  • release → final release builds

• version (optional):

  • For release: must be vX.Y.Z
  • For release_candidate: can be vX.Y.Z (auto RC) or vX.Y.Z-rc.N (explicit RC)
  • For preview: can override with any identifier

---

⚙️ Pipeline Behavior

✅ Determine Version
Uses the composite action .github/actions/determine-version
to calculate the correct version string based on Git ref, event type, and inputs.

✅ Check for Existing Release
For non-tag builds, uses .github/actions/check-release-exists
to avoid overwriting existing GitHub Releases.

✅ Create Tag if Needed
For release and release_candidate builds,
uses .github/actions/check-tag-exists and .github/actions/create-tag
to ensure the correct tag exists.

✅ Summarize Results
Writes a structured summary directly into the GitHub Actions run summary (GITHUB_STEP_SUMMARY)
with details like:

• Build type
• Trigger event
• Final resolved version
• Tag/release status

---

🔐 Safeguards

Situation	System Behavior
Duplicate Git tag (on push)	Accepted — Git prevents true duplicates
Duplicate GitHub Release (non-tag builds)	Fails early to avoid overwrite
Invalid manual version input	Fails with clear error
Missing required version (release builds)	Fails with prompt to provide or push a tag

---

💡 Usage Examples

• Manual workflow dispatch:

  • buildType: release + version: v1.2.3
  • buildType: release_candidate + version: v1.2.3 (auto-rc) or v1.2.3-rc.4 (explicit RC)

• Tag push trigger:

  • Push v1.2.3 → pipeline picks up release build
  • Push v1.2.3-rc.1 → pipeline picks up RC build

• Pull request or branch build:

  • PR → PR-0001
  • Branch → main or manual-main

---

📂 Key Files & Actions

Component	Purpose
.github/actions/resolve-build-version	Resolve correct version string
.github/actions/check-release-exists	Check if GitHub Release already exists
.github/actions/check-tag-exists	Check if Git tag exists
.github/actions/create-tag	Create new tag if missing
.github/scripts/generate-version-for-rc.sh	Auto-increment RC suffixes (e.g., -rc.1)

---

✅ With this system, you get clean, automated, and safe versioning
for all your Unity CI/CD builds, without manual intervention or risky overrides.