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.

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

```bash
cd Data_Coupler
dotnet build

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

### Step 3: Commit e Push Modifiche

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

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

```bash
# 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

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

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

```xml
<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`:

```xml
<PropertyGroup>
  <MinVerDefaultPreReleasePhase>dev</MinVerDefaultPreReleasePhase>
</PropertyGroup>
```

## 📊 Comandi Utili

### Lista Tag Esistenti
```bash
git tag -l
```

### Cancella Tag Locale
```bash
git tag -d v2.1.0
```

### Cancella Tag Remoto
```bash
git push origin --delete v2.1.0
```

### Sposta Tag a Commit Diverso
```bash
# 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
```bash
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**:
```bash
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**:
```bash
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
```bash
# ✅ 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)
```bash
# ✅ 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
```bash
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
```bash
# Verifica commit
git log --oneline -5

# Verifica branch
git branch --show-current

# Verifica che sia pronto
dotnet build
dotnet test
```

## 🚦 Flusso Completo di Release

```bash
# 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