Data-Coupler/MINVER_SETUP.md

MinVer - Setup e Utilizzo per Versioning Automatico

🎯 Cos'è MinVer

MinVer è un tool che calcola automaticamente la versione del progetto basandosi sui git tags. Elimina la necessità di aggiornare manualmente la versione nel .csproj.

📦 Implementazione Completata

Modifiche Apportate

1. ✅ Pacchetto MinVer aggiunto a Data_Coupler.csproj
2. ✅ Workflow Gitea Linux aggiornato per usare MinVer
3. ✅ Workflow Gitea Windows aggiornato per usare MinVer
4. ✅ Rimozione <Version> manuale (ora calcolata automaticamente)

Come Funziona

Git Tags → MinVer → Calcola Versione → Build → version.json → UI

MinVer cerca il tag git più recente nel formato:

• v2.1.0 o 2.1.0 (tag esatto = quella versione)
• Nessun tag = 0.0.0-alpha.0 + commit count
• Tag + commit successivi = 2.1.0-alpha.0.5 (5 commit dopo il tag)

🚀 Setup Iniziale sulla Repository

Step 1: Creare il Primo Tag

⚠️ AZIONE RICHIESTA: Devi creare un tag git per inizializzare MinVer.

# Assicurati di essere sulla branch main (o quella desiderata)
git checkout main

# Assicurati di avere l'ultimo commit
git pull

# Crea il tag per la versione corrente
git tag v2.1.0

# Push del tag su Gitea
git push origin v2.1.0

Step 2: Verifica Locale (Opzionale)

Puoi testare MinVer localmente prima del push:

cd Data_Coupler
dotnet build

# MinVer mostrerà nei log la versione calcolata:
# MinVer: Using version 2.1.0

Step 3: Commit e Push Modifiche

# Aggiungi le modifiche (MinVer nel .csproj e workflow)
git add .
git commit -m "feat: Implement MinVer for automatic versioning"

# Push su Gitea
git push origin main

📋 Workflow di Versioning con MinVer

Scenario 1: Nuovo Tag (Release)

Quando sei pronto per una nuova release:

# Fai i tuoi commit normalmente
git commit -am "feat: Add new feature"
git commit -am "fix: Bug correction"

# Quando pronto per release, crea il tag
git tag v2.2.0
git push origin v2.2.0

# Gitea Actions automaticamente:
# 1. Rileva il tag v2.2.0
# 2. MinVer calcola versione: 2.2.0
# 3. Build con quella versione
# 4. UI mostra "Data_Coupler v2.2.0"

Scenario 2: Commit senza Tag (Development)

# Durante sviluppo, commit normali senza tag
git commit -am "feat: Work in progress"
git push

# MinVer calcola versione automaticamente:
# - Ultimo tag: v2.1.0
# - Commit dopo il tag: 5
# - Versione calcolata: 2.1.0-alpha.0.5
# - UI mostra: "Data_Coupler v2.1.0-alpha.0.5"

Scenario 3: Branch Diversi

# Branch main con tag v2.1.0
git checkout main
# Versione: 2.1.0

# Branch development (3 commit dopo tag)
git checkout development
# Versione: 2.1.0-alpha.0.3

# Branch feature (5 commit dopo tag)
git checkout feature/new-feature
# Versione: 2.1.0-alpha.0.5

🎨 Convenzioni Tag

Tag Format

MinVer supporta questi formati:

# ✅ Consigliato (con v)
v2.1.0
v2.2.0
v3.0.0

# ✅ Anche valido (senza v)
2.1.0
2.2.0

# ✅ Pre-release (opzionale)
v2.1.0-beta
v2.1.0-rc.1

Semantic Versioning

Segui sempre Semantic Versioning per i tag:

Tipo	Da	A	Comando
PATCH (bug fix)	2.1.0	2.1.1	git tag v2.1.1
MINOR (feature)	2.1.0	2.2.0	git tag v2.2.0
MAJOR (breaking)	2.1.0	3.0.0	git tag v3.0.0

🔧 Configurazione Avanzata (Opzionale)

Personalizzare MinVer nel .csproj

Puoi aggiungere opzioni MinVer nel Data_Coupler.csproj:

<PropertyGroup>
  <!-- Tag prefix (default: v) -->
  <MinVerTagPrefix>v</MinVerTagPrefix>
  
  <!-- Pre-release phase (default: alpha) -->
  <MinVerDefaultPreReleasePhase>alpha</MinVerDefaultPreReleasePhase>
  
  <!-- Minimum major/minor version -->
  <MinVerMinimumMajorMinor>2.1</MinVerMinimumMajorMinor>
  
  <!-- Build metadata -->
  <MinVerBuildMetadata>build.$(BUILD_NUMBER)</MinVerBuildMetadata>
</PropertyGroup>

Esempio Personalizzazione

Se vuoi versioni tipo 2.1.0-dev.5 invece di 2.1.0-alpha.0.5:

<PropertyGroup>
  <MinVerDefaultPreReleasePhase>dev</MinVerDefaultPreReleasePhase>
</PropertyGroup>

📊 Comandi Utili

Lista Tag Esistenti

git tag -l

Cancella Tag Locale

git tag -d v2.1.0

Cancella Tag Remoto

git push origin --delete v2.1.0

Sposta Tag a Commit Diverso

# Cancella vecchio tag
git tag -d v2.1.0
git push origin --delete v2.1.0

# Crea nuovo tag al commit corrente
git tag v2.1.0
git push origin v2.1.0

Verifica Versione Calcolata Localmente

cd Data_Coupler
dotnet build -v minimal | grep MinVer
# Output: MinVer: Using version 2.1.0-alpha.0.3

🐛 Troubleshooting

Problema: MinVer calcola 0.0.0-alpha.0

Causa: Nessun tag git trovato nella repository

Soluzione:

git tag v2.1.0
git push origin v2.1.0

Problema: Versione non si aggiorna dopo nuovo tag

Causa: Gitea Actions non ha fatto fetch dei tag

Soluzione: I workflow sono già configurati con git fetch --tags --force

Problema: Versione locale diversa da CI/CD

Causa: Tag non sincronizzati

Soluzione:

git fetch --tags
git pull

Problema: Voglio tornare a versioning manuale

Soluzione: Rimuovi MinVer dal .csproj e ripristina <Version>2.1.0</Version>

📚 Vantaggi MinVer

Aspetto	Prima (Manuale)	Dopo (MinVer)
Versione	Manuale in .csproj	Automatica da tag
Sincronizzazione	Rischio errore umano	Sempre consistente
Development	Solo release versions	Alpha versions per dev
CI/CD	Update .csproj ogni volta	Solo tag per release
Tracciabilità	Manuale	Git tags = release
Commit count	Non tracciato	Incluso in alpha versions

🎯 Best Practices

1. Tag Solo su Main/Releases

# ✅ Buona pratica
git checkout main
git tag v2.2.0
git push origin v2.2.0

# ❌ Evitare
git checkout feature/temp
git tag v2.2.0  # Non taggare feature branch

2. Annotated Tags (Raccomandato)

# ✅ Con messaggio
git tag -a v2.2.0 -m "Release 2.2.0: Add new features"

# ❌ Lightweight (meno informazioni)
git tag v2.2.0

3. Changelog nei Tag Messages

git tag -a v2.2.0 -m "Release 2.2.0

New Features:
- Feature A
- Feature B

Bug Fixes:
- Fix issue #123
"

4. Verificare Prima di Taggare

# Verifica commit
git log --oneline -5

# Verifica branch
git branch --show-current

# Verifica che sia pronto
dotnet build
dotnet test

🚦 Flusso Completo di Release

# 1. Finalizza feature
git checkout development
git commit -am "feat: Complete feature X"
git push

# 2. Merge to main
git checkout main
git merge development
git push

# 3. Crea tag release
git tag -a v2.2.0 -m "Release 2.2.0: Feature X"
git push origin v2.2.0

# 4. Gitea Actions automaticamente:
#    - Build con versione 2.2.0
#    - Deploy container
#    - UI mostra v2.2.0

# 5. Continua sviluppo
git checkout development
git commit -am "feat: Start feature Y"
# Versione automatica: 2.2.0-alpha.0.1

📖 Riferimenti

• MinVer Docs: https://github.com/adamralph/minver
• Semantic Versioning: https://semver.org/
• Git Tags: https://git-scm.com/book/en/v2/Git-Basics-Tagging

---

Status: ✅ Implementato e Pronto
Azione Richiesta: Crea primo tag v2.1.0 sulla repository
Data: 2 Febbraio 2026
Autore: Alessio Dalsanto