Versionamento & Build

Versionamento indipendente

I progetti Lino possono contenere più servizi e applicazioni web. Ogni elemento distribuibile ha la propria versione, quindi una piccola correzione in un servizio non forza un release artificiale di tutto il sistema. Questo è importante in architetture modulari e distribuite, dove API, workers, web apps, migrations e contratti di integrazione possono evolvere a ritmi diversi.

La versione operativa è archiviata in un semplice file di testo chiamato version.txt. Per i servizi, il file si trova in src/Services/<ServiceName>/version.txt. Per le applicazioni web, si trova in src/WebApps/<WebAppName>/version.txt. La CLI di Lino legge questi file quando elenca, consulta, incrementa e genera build versionate.

Regola SemVer usata da Lino

MAJOR.MINOR.PATCH

• PATCH incrementa l'ultimo numero e deve essere usato per correzioni compatibili, piccoli miglioramenti interni e modifiche che non alterano il contratto pubblico.
• MINOR incrementa il numero centrale e azzera patch. Usalo per funzionalità retrocompatibili, nuovi endpoints, campi opzionali o comportamento additivo.
• MAJOR incrementa il primo numero e azzera minor e patch. Usalo quando i consumatori devono adattarsi, ad esempio perché un contratto di API è cambiato in modo incompatibile o un comportamento è stato sostituito intenzionalmente.

Esempi: 1.0.0 può rappresentare la prima versione stabile, 1.0.1 una correzione compatibile, 1.1.0 una nuova capacità compatibile o nuovi endpoints senza rotture, e 2.0.0 un release con modifiche che richiedono l'aggiornamento dei client.

Consultare le versioni attuali

Usa lino version list per vedere le versioni attuali di tutti i servizi e applicazioni web del progetto:

lino version list

Usa lino version show quando devi consultare la versione di un servizio o di un'applicazione web specifica. Il comando chiede se il target è un servizio o un'applicazione web e mostra la versione letta dal file version.txt corrispondente.

lino version show

Incrementare una versione

Usa lino version bump quando un servizio o un'applicazione web è pronto per un nuovo release:

lino version bump

1. Esegui il comando dalla radice del progetto.
2. Seleziona uno o più servizi o applicazioni web. Il prompt mostra ogni elemento con la sua versione attuale.
3. Scegli il tipo di incremento: patch, minor o major.
4. Conferma le risposte. Lino aggiorna i file version.txt selezionati e mostra una tabella con le nuove versioni.

Ogni esecuzione mantiene un tracciamento chiaro delle modifiche, migliora la coerenza con le pratiche di release e facilita l'allineamento con pipeline CI/CD. Il numero di versione smette di essere un dettaglio isolato e passa a identificare l'artefatto distribuibile che è realmente cambiato.

Le modifiche di versione devono essere riviste insieme all'impatto tecnico del release. Una migration di database può essere collegata alla versione di un servizio, i consumatori di API possono aver bisogno di note di contratto e gli eventi di integrazione possono richiedere controlli di compatibilità. Mantenere la versione vicina all'elemento distribuibile rende queste decisioni esplicite e più facili da auditare.

Prima di un incremento major, rivedi API pubbliche, contratti di eventi, migrations, compatibilità dei client e consumatori esterni. Prima di un incremento minor, conferma che il nuovo comportamento sia additivo. Prima di un patch, conferma che la modifica sia compatibile e non cambi le aspettative d'uso.

Build e containerizzazione

Nei video e nello sviluppo quotidiano, dotnet build viene usato spesso per validare che la soluzione generata compili ancora dopo ogni fase di modellazione. Il comando lino build ha un altro obiettivo: preparare servizi e applicazioni web selezionati per release, pubblicandoli in modalità Release con il profilo di pubblicazione container di .NET.

Questa separazione evita di trattare una semplice validazione di compilazione come pacchetto di consegna. Usa dotnet build durante lo sviluppo per trovare errori in anticipo. Usa lino build quando l'artefatto è pronto per ricevere una versione, diventare un'immagine di container e passare a un registry o a una pipeline di deploy.

Cosa fa lino build

Esegui il comando dalla radice di un progetto Lino:

lino build

La CLI valida l'utente autenticato e la configurazione attuale del progetto, chiede quali servizi o applicazioni web devono entrare nel build e poi chiede se la versione deve essere mantenuta o incrementata. Quando viene selezionato un incremento, Lino aggiorna il version.txt corrispondente prima di generare i comandi di build.

Il backend restituisce i comandi esatti da eseguire. Attualmente questi comandi usano dotnet publish con -c Release, -p:PublishProfile=DefaultContainer, -p:ContainerRepository, -p:ContainerImageTag e -p:ContainerLabelVersion. La tag dell'immagine e il label di versione del container ricevono lo stesso valore SemVer scelto per il release.

In pratica, il processo compila il codice del servizio o dell'applicazione web, applica la configurazione di pubblicazione necessaria, genera un'immagine di container basata sulla versione SemVer attuale e assegna nome, tag e metadati standardizzati all'artefatto.

Nomi di repository generati

Lino normalizza i nomi del progetto e degli elementi per generare repository di container prevedibili:

• API di servizio semplice: <project-name>/services/<service-name>-api:1.2.3
• Host di servizio modulare: <project-name>/services/<service-name>-host:1.2.3
• Applicazione web Blazor: <project-name>/webapps/<webapp-name>:1.2.3

Questa convenzione mantiene API di servizi, host modulari e applicazioni web separati nel registry, preservando la versione di release nella tag. Il modello elimina anche decisioni manuali ripetitive e riduce divergenze tra ambienti, script CI/CD e documentazione operativa.

Pubblicazione nei registry

Le immagini generate possono essere pubblicate nel registry usato dalla piattaforma di deploy:

• Docker Hub
• GitHub Container Registry
• AWS ECR
• Azure Container Registry
• qualsiasi altro registry compatibile con OCI.

Quando possibile, fai deploy puntando a tag di versione immutabili, come 1.2.3, invece che a tag flottanti. Questo migliora rollback, audit e confronto tra ciò che è stato compilato, pubblicato e distribuito.

Flusso di release consigliato

1. Esegui i test del progetto e dotnet build per validare il codice sorgente prima del packaging.
2. Consulta le versioni attuali con lino version list e rivedi quali servizi o applicazioni web sono cambiati.
3. Usa lino build e scegli se mantenere la versione attuale o applicare un incremento patch, minor o major.
4. Pubblica le immagini di container generate nel registry usato dalla piattaforma di deploy, come Docker Hub, GitHub Container Registry, AWS ECR, Azure Container Registry o un altro registry compatibile.
5. Distribuisci referenziando tag di versione tracciabili e mantieni changelog, migrations e piano di rollback collegati allo stesso release.

Non inserire secrets, connection strings di produzione o credenziali specifiche di ambiente dentro le immagini generate. Usa variabili di ambiente, user secrets per lo sviluppo locale, vault di secrets del CI/CD o il meccanismo di secrets della piattaforma di deploy.

Con questo flusso, versionamento e build restano collegati: lo stesso valore SemVer registrato nel progetto viene usato come tag del container e come metadato di release, migliorando la tracciabilità tra codice sorgente, migrations, contratti di API, eventi di integrazione e artefatti distribuiti.