Version Strategy update for releases #560

Summary

Our release tags use a calendar format (e.g. 2026.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 2026.4.1 (Apr 1 2026, DOY=91) → ApplicationDisplayVersion=26.4.91
• Tag 2027.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:

• 2026.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: 2026.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:

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

Compute DOY with PowerShell:

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

As part of the job can something be added to my PR workflow that uses an expected tag value (e.g. 2026.4.1) and verify it works on androd and windows when building the release packages