# 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)
```bash
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)
```cmd
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**:

```powershell
# 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** | `|| echo "2.1.0"` | `if-else` con default |
| **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`:

```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
```bash
# 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
```powershell
# 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**:
```bash
# 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

- [x] Workflow Linux mantiene funzionalità esistente
- [x] Workflow Windows corretto con PowerShell
- [x] Entrambi leggono da `.csproj`
- [x] Fallback identico ("2.1.0")
- [x] Formato JSON valido su entrambe le piattaforme
- [x] Data in formato UTC su entrambe le piattaforme
- [x] Logging appropriato per debugging
- [x] Documentazione aggiornata (`VERSIONING_SYSTEM.md`)
- [x] 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)