Workflow Organization

In questo capitolo si approfondiranno le buone pratiche di DevOps che sono state adottate dal team durante lo sviluppo del sistema, definendo un processo e un ambiente di sviluppo standard per i membri del team.

Lo scopo di questo processo è di definire un’organizzazione del processo di sviluppo a priori, promuovendo l’autonomia dei membri del team a posteriori.

GitHub Organization

Il sistema da realizzare è stato suddiviso in diversi componenti software indipendenti tra di loro, ma comunque parte dello stesso sistema.

Per questo, si è deciso di separare lo sviluppo di ciascun componente in un repository corrispondente, ma anche di raggruppare tutti i repository all’interno di una unica GitHub Organization, corrispondente al sistema nella sua interezza.

I vantaggi di utilizzare una GitHub Organization in questo progetto sono stati quelli di poter accedere facilmente ai repository che vi appartengono, separandoli da altri progetti, e di condividere delle impostazioni, delle variabili e dei segreti che sarebbero stati altrimenti ripetuti in ogni repository.

Di seguito, si riporta la struttura della GitHub Organization creata:

ldss-project: la GitHub Organization relativa al progetto per il corso di Laboratorio di Sistemi Software 2022-2023. Contiene i seguenti repository:
- hexarc: framework per la definizione ed il deployment di servizi secondo le buone pratiche della Clean Architecture.
- wartremover-gradle-plugin: plugin gradle per configurare WartRemover come code linter in un progetto Scala 3.
- scala3-project-template: template repository per la creazione di progetti Scala 3.
- frontend: implementazione del Frontend Service, come descritto nei capitoli precedenti.
- authentication-service: implementazione dell’Authentication Service, come descritto nei capitoli precedenti.
- statistics-service: implementazione dello Statistics Service, come descritto nei capitoli precedenti.
- chess-game-service: implementazione del Chess Game Service, come descritto nei capitoli precedenti.
- swagger-apis: sito web per la pubblicazione delle API dei servizi del sistema (creato per non essere vincolati dai limiti sulle pubblicazioni imposti dalla licenza gratuita di SwaggerHub).

DVCS Workflow

Durante lo sviluppo del sistema, si è cercato il più possibile di suddividere il lavoro tra i membri del team, in modo da ridurre al minimo i possibili conflitti di pubblicazione del codice sui repository. In particolare, nella maggior parte dei casi, a ogni repository ha lavorato principalmente un unico membro del team, con piccole eccezioni durante l’integrazione tra i vari moduli del sistema.

L’approccio adottato per lo sviluppo all’interno dei singoli repository è una versione semplificata di Git Flow e, in generale, prevede i seguenti branch:

master (o main): branch utilizzato per la pubblicazione del software.
feature/<topic>: branch utilizzato per aggiungere una feature nel software. Nasce dal master e ritorna sul master.
fix/<topic>: branch utilizzato per rimuovere un difetto nel software. Nasce dal master e ritorna sul master.
<module>/<topic>: branch utilizzato per modificare uno specifico modulo del software, utile per identificare velocemente la parte del software modificata maggiormente nel branch, quando il software è composto da numerosi moduli, come ad esempio il Frontend (logica, pagine, componenti grafici…). Nasce dal master e ritorna sul master.

In generale, si è deciso di adottare quando opportuno una strategia di merge basata sul rebase, allo scopo di mantenere la storia dei commit il più lineare possibile e quindi più facilmente interpretabile sia per gli umani che per le macchine.

All’interno di un branch, i commit aderiscono allo standard Conventional Commit in modo da supportare il versionamento automatico del software. I principali tipi di commit utilizzati sono i seguenti:

feat: indica che il commit ha aggiunto una nuova funzionalità al software visibile ai suoi utilizzatori.
fix: indica che il commit ha rimosso un difetto dal software visibile ai suoi utilizzatori.
docs: indica che il commit ha aggiornato la documentazione del software.
build: indica che il commit ha modificato uno script di build automation (ad esempio, ha aggiunto una dipendenza al software o ha modificato il processo di creazione degli artefatti software…).
ci: indica che il commit ha modificato uno script di continuous integration (ad esempio, ha aggiunto un GitHub Workflow…).
test: indica che il commit ha aggiunto un test per una parte del software.
chore: indica che il commit ha modificato una parte del software non visibile ai suoi utilizzatori (ad esempio, inizializzazione del repository, refactoring, aggiunta di un componente non ancora utilizzato…).
<module>: equivalente a chore(<module>). Utilizzato per identificare velocemente la parte del software modificata maggiormente nel commit, quando il software è composto da numerosi moduli, come ad esempio il Frontend (logic, page, component, style…).

Versioning

Per quanto riguarda il versionamento del software, si è deciso di adottare lo standard Semantic Versioning in modo da garantire che una modifica sulla versione del software rifletti un effettivo cambiamento del software dal punto di vista dei suoi utilizzatori.

Il vantaggio di adottare tale standard è la disponibilità di alcuni strumenti per automatizzare il versionamento e la pubblicazione del software, come Semantic Release, che permette di assegnare una versione al software sulla base della sua storia dei commit. Questo stesso strumento sarà anche utilizzato per automatizzare la pubblicazione degli artefatti software del sistema.

In maggior dettaglio, la tecnica di versionamento adottata parte dalla versione 0.1.0, come prima versione instabile di un repository. Quindi, ad ogni aggiornamento del branch master, la storia dei commit del branch viene controllata, eventualmente producendo una nuova versione del software che viene associata come tag all’ultimo commit del branch.

In particolare, la versione del software viene modificata come segue:

Se la storia dei commit dall’ultima versione contiene un Breaking Change, la versione del repository viene incrementata di una Major;
Altrimenti, se la storia dei commit dall’ultima versione contiene un commit di tipo feat, la versione del repository viene incrementata di una Minor;
Altrimenti, se la storia dei commit dall’ultima versione contiene un commit di tipo fix, la versione del repository viene incrementata di una Patch;
Altrimenti, la versione non viene modificata.

In questo progetto, non si è mai fatto uso di Breaking Change esplicitamente, infatti i moduli realizzati sono ancora in una versione instabile, per cui ogni modifica del software potrebbe comportare delle modifiche sostanziali alla sua API.

GitHub Template Repositories

Per evitare di dover definire la stessa configurazione per ogni repository quando creato, sono stati utilizzati dei template repository.

In particolare, per la documentazione dei moduli è stato applicato un template di terze parti, chiamato just-the-docs, mentre per l’inizializzazione di progetti Scala 3 è stato creato un template interno, chiamato scala3-project-template.

Un altro metodo utilizzato agli stessi scopi, è quello di creare delle fork da progetti pre-configurati. Ad esempio, questa stessa documentazione è stata creata a partire da una fork della documentazione del progetto realizzato per il corso di Project Management 2022-2023, disponibile al seguente link.