Data-Coupler/VERSIONING_CONSISTENCY_FIX.md

Fix: Consistenza Versioning tra Linux e Windows

🐛 Problema Identificato

Durante la revisione del sistema di versioning, è stato identificato un problema critico di inconsistenza tra i workflow Linux e Windows.

Stato Precedente

Linux (Corretto)

VERSION=$(grep '<Version>' Data_Coupler/Data_Coupler.csproj | sed 's/.*<Version>\(.*\)<\/Version>.*/\1/' || echo "2.1.0")

✅ Legge dinamicamente la versione dal file .csproj

Windows (Problematico)

set VERSION=2.1.0

❌ Versione hardcoded, non legge dal .csproj

Conseguenze del Bug

1. Desincronizzazione: Container Linux e Windows avrebbero potuto avere versioni diverse
2. Manutenzione difficile: Necessario aggiornare il workflow ad ogni cambio di versione
3. Errori umani: Rischio di dimenticare di aggiornare la versione hardcoded
4. Single Source of Truth violato: .csproj non era più l'unica fonte

✅ Soluzione Implementata

Nuovo Workflow Windows

Implementato script PowerShell che replica la logica Linux:

# Extract version from Data_Coupler.csproj or use default
$csprojPath = "Data_Coupler\Data_Coupler.csproj"
$VERSION = "2.1.0"

if (Test-Path $csprojPath) {
  $csprojContent = Get-Content $csprojPath -Raw
  if ($csprojContent -match '<Version>(.*?)<\/Version>') {
    $VERSION = $matches[1]
    Write-Host "Version extracted from csproj: $VERSION"
  } else {
    Write-Host "Version tag not found in csproj, using default: $VERSION"
  }
} else {
  Write-Host "csproj not found, using default version: $VERSION"
}

$COMMIT_SHA = "${{ github.sha }}"
$SHORT_SHA = $COMMIT_SHA.Substring(0, 7)
$BRANCH = "${{ github.ref_name }}"
$BUILD_DATE = (Get-Date).ToUniversalTime().ToString("yyyy-MM-dd HH:mm:ss UTC")

# Create version.json
$versionJson = @{
  version = $VERSION
  commitSha = $SHORT_SHA
  branch = $BRANCH
  buildDate = $BUILD_DATE
  buildEnvironment = "Gitea Actions"
} | ConvertTo-Json

$versionJson | Out-File -FilePath "Data_Coupler\wwwroot\version.json" -Encoding UTF8

Vantaggi della Soluzione

1. ✅ Consistenza: Linux e Windows leggono dalla stessa fonte
2. ✅ Single Source of Truth: .csproj è l'unica fonte della versione
3. ✅ Manutenzione semplificata: Nessun bisogno di aggiornare workflow
4. ✅ Robustezza: Fallback a default se .csproj non trovato
5. ✅ Logging: Output chiaro per debugging
6. ✅ Formato JSON corretto: Uso di ConvertTo-Json per output valido
7. ✅ Data UTC: Consistenza formato data tra piattaforme

📊 Confronto Tecnico

Metodi di Estrazione

Aspetto	Linux	Windows
Tool	grep + sed	PowerShell regex
Pattern	sed 's/.*<Version>\(.*\)<\/Version>.*/\1/'	'<Version>(.*?)<\/Version>'
Shell	Bash	PowerShell (pwsh)
Fallback	`
Test esistenza file	Implicito in grep	Test-Path esplicito
Output JSON	cat con heredoc	ConvertTo-Json

Formato Output Generato

Entrambi i workflow ora generano identico version.json:

{
  "version": "2.1.0",
  "commitSha": "abc1234",
  "branch": "main",
  "buildDate": "2026-02-02 10:30:45 UTC",
  "buildEnvironment": "Gitea Actions"
}

🧪 Testing

Verifica Workflow

Linux Build

# Verifica che legga dal .csproj
grep '<Version>' Data_Coupler/Data_Coupler.csproj
# Output atteso: <Version>2.1.0</Version>

# Verifica version.json generato
cat Data_Coupler/wwwroot/version.json

Windows Build

# Verifica che legga dal .csproj
$content = Get-Content Data_Coupler\Data_Coupler.csproj -Raw
$content -match '<Version>(.*?)<\/Version>'
$matches[1]
# Output atteso: 2.1.0

# Verifica version.json generato
Get-Content Data_Coupler\wwwroot\version.json | ConvertFrom-Json

Test di Consistenza

Dopo un push su Gitea:

1. Attendi completamento di entrambi i build (Linux + Windows)
2. Verifica logs Gitea Actions:
   • Linux: "Version extracted from csproj: 2.1.0"
   • Windows: "Version extracted from csproj: 2.1.0"
3. Confronta immagini Docker:

# Estrai version.json da entrambi i container
docker run --rm gitea.home-nas-ds.org/alessio/data-coupler:latest-linux cat /app/wwwroot/version.json > linux-version.json
docker run --rm gitea.home-nas-ds.org/alessio/data-coupler:latest-windows cat /app/wwwroot/version.json > windows-version.json

# Confronta (dovrebbero essere identici eccetto buildDate)
diff linux-version.json windows-version.json

📋 Checklist Validazione

• Workflow Linux mantiene funzionalità esistente
• Workflow Windows corretto con PowerShell
• Entrambi leggono da .csproj
• Fallback identico ("2.1.0")
• Formato JSON valido su entrambe le piattaforme
• Data in formato UTC su entrambe le piattaforme
• Logging appropriato per debugging
• Documentazione aggiornata (VERSIONING_SYSTEM.md)
• Test locali completati

🚀 Impatto della Correzione

Prima della Fix

Developer aggiorna .csproj → Linux usa versione corretta
                            → Windows usa 2.1.0 hardcoded ❌
                            → INCONSISTENZA tra container

Dopo la Fix

Developer aggiorna .csproj → Linux legge da .csproj ✅
                            → Windows legge da .csproj ✅
                            → STESSA versione in entrambi i container ✅

📝 Best Practices Applicate

1. DRY (Don't Repeat Yourself): .csproj è single source of truth
2. Fail-Safe: Fallback a default se problemi con .csproj
3. Logging esplicito: Output chiaro per troubleshooting
4. Cross-platform: Logica equivalente su Linux/Windows
5. Testabilità: Script facilmente testabile localmente
6. Manutenibilità: Nessun hardcoding, tutto dinamico

🔮 Considerazioni Future

Possibili Miglioramenti

1. Auto-increment (opzionale):

   • Potrebbe essere aggiunto parsing di commit messages
   • Conventional Commits per determinare bump MAJOR/MINOR/PATCH
   • Aggiornamento automatico .csproj prima del build

2. Git Tags:

   • Sincronizzazione versione con git tags
   • Creazione automatica tag al push su main

3. Changelog Automatico:

   • Generazione CHANGELOG.md basato su commit
   • Integrazione con versioning

4. Multi-versione per branch:

   • Branch development: 2.1.0-dev
   • Branch staging: 2.1.0-rc1
   • Branch main: 2.1.0

Nota: Tutte queste feature richiederebbero complessità aggiuntiva. L'approccio attuale (incremento manuale) è intenzionale per mantenere semplicità e controllo esplicito.

📚 Riferimenti

• File modificato: .gitea/workflows/docker-build.yml
• Documentazione aggiornata: VERSIONING_SYSTEM.md
• Data correzione: 2 Febbraio 2026
• Autore: Alessio Dalsanto

---

Status: ✅ Fix Completato e Testato
Criticità: 🔴 Alta (inconsistenza versioni multi-platform)
Complessità Fix: 🟢 Bassa (sostituzione script Windows)