Version Strategy update for releases #557

Summary

Our release tags use a calendar format (e.g. v2026.4.1). The Windows release workflow currently passes that tag value into MAUI’s ApplicationDisplayVersion, which fails validation in Microsoft.Maui.Resizetizer (requires strict 3-part SemVer-like version), causing the Windows release job to fail.

We want to keep calendar tags, but switch both Windows and Android workflows to a consistent version strategy that:

• keeps tags as vYYYY.M.D
• generates a Resizetizer-safe SemVer 3-part display version for the app (“About” screen + upgrade detection)
• generates a valid platform package version for Windows (MSIX/Appx) and Android (versionCode)

Failing run reference:

• https://github.com/TransactionProcessing/TransactionMobile/actions/runs/24884007685/job/72859352731

Target versioning strategy

Given tag: vYYYY.M.D (also allow vYYYY.MM.DD)

Derive:

1. ApplicationDisplayVersion (SemVer, 3-part)
   <YY>.<M>.<DOY>

Where:

• YY = YYYY - 2000 (e.g. 2026 → 26)
• M = month number (1–12)
• DOY = day-of-year (1–365/366)

Examples:

• Tag v2026.4.1 (Apr 1 2026, DOY=91) → ApplicationDisplayVersion=26.4.91
• Tag v2027.4.1 (Apr 1 2027, DOY=91) → ApplicationDisplayVersion=27.4.91

This version is monotonic and “rolls” yearly (major changes per year), and satisfies Resizetizer requirements.

2. Windows MSIX/Appx package version (4-part numeric)
   <YYYY>.<M>.<D>.0

Example:

• v2026.4.1 → ApplicationVersion=2026.4.1.0

3. Android package versions

• ApplicationDisplayVersion should be set to the derived SemVer (same as Windows): YY.M.DOY
• ApplicationVersion / Android versionCode must be an integer and monotonic.

Proposed Android versionCode mapping (simple + monotonic):

• versionCode = YYYY * 1000 + DOY
  Example: v2026.4.1 (DOY=91) → 2026000 + 91 = 2026091

(Alternative acceptable mapping if preferred: versionCode = (YYYY-2000)*1000 + DOY.)

Scope / Work items

A) Update Windows workflow

• Locate .github/workflows/release_windows.yml
• Replace current “Extract version from tag” logic with parsing that accepts vYYYY.M.D and computes:
  • APP_DISPLAY_VERSION = (YYYY-2000).M.DOY
  • APP_MSIX_VERSION = YYYY.M.D.0
• Update dotnet publish to pass:
  • /p:ApplicationDisplayVersion=${{ env.APP_DISPLAY_VERSION }}
  • /p:ApplicationVersion=${{ env.APP_MSIX_VERSION }}

Acceptance criteria:

• The failing Resizetizer error is eliminated.
• Windows release job succeeds for a tag like v2026.4.1.

B) Update Android workflow

• Identify Android release workflow (e.g. .github/workflows/release_android*.yml or similar)
• Implement the same tag parsing + version derivation
• Ensure Android build uses:
  • ApplicationDisplayVersion = derived SemVer YY.M.DOY
  • ApplicationVersion / versionCode = derived monotonic integer (proposed: YYYY*1000+DOY)
• Confirm artifacts / publishing steps still work.

Acceptance criteria:

• Android build produces the expected versionName/versionCode
• Upgrade detection remains monotonic across releases

C) Add documentation

• Add a short section to README/release docs describing:
  • required tag format: vYYYY.M.D
  • how display version and platform versions are computed
  • example conversions

Notes / Constraints

• Keep existing tag strategy (vYYYY.M.D)—do not change release/tag naming.
• Do not attempt to bypass Resizetizer validation; instead ensure ApplicationDisplayVersion is always valid.
• Ensure all computed version components remain within required ranges:
  • SemVer parts: integers
  • MSIX/Appx parts: 0..65535 each (YYYY up to 65535 is fine; month/day <= 31; DOY <= 366)
  • Android versionCode: int32 safe (e.g. 2026366 is fine)

Suggested implementation detail (PowerShell snippet)

Use regex that accepts single or double digit month/day:

• ^v(\d{4})\.(\d{1,2})\.(\d{1,2})$

Compute DOY with PowerShell:

• $date = Get-Date -Year $year -Month $month -Day $day
• $dayOfYear = $date.DayOfYear