Alessio Dal Santo
ae16f99776
- Aggiunto MinVer per calcolo automatico versione da git tags - Creato modello VersionInfo e servizio VersionService - Integrato display versione nel NavMenu (Data_Coupler v2.1.0) - Aggiornato workflow Gitea Actions (Linux e Windows) per generare version.json - Risolto problema inconsistenza versioning tra container Linux e Windows - Documentazione completa: VERSIONING_SYSTEM.md e MINVER_SETUP.md - Versione ora calcolata automaticamente da git tags (Semantic Versioning)
222 lines
6.9 KiB
Markdown
222 lines
6.9 KiB
Markdown
# 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)
|