LSS revision

.github/workflows/release.yml

@@ -64,6 +64,15 @@ jobs:
           ./gradlew generateVersionFile
           echo "RELEASE_VERSION=$(cat ./build/version)" >> $GITHUB_ENV
 
+        # It is necessary to manually setting the tag, as simply creating a release generates a
+        # lightweight tag, making the gitSemVer plugin not working properly.
+      - name: Add tag
+        run: |
+          git config user.name releaserbot
+          git config user.email github-actions@github.com
+          git tag ${{ env.RELEASE_VERSION }} -a -m "Release ${{ env.RELEASE_VERSION }}"
+          git push --follow-tags
+
       - name: Create release
         id: create-release
         uses: actions/create-release@v1

src/lss-report/1-introduzione.md

@@ -15,7 +15,7 @@ su un'interfaccia da linea di comando. Questa permetterà ad utenti terzi di
 interagire con le storie create precedentemente, modificando lo stato nel gioco
 e avanzando man mano nella storia.
 
-Il progetto è stato pensato per essere oggetto di esame in maniera mutuata per i
+Il progetto è stato ideato per essere oggetto di esame in maniera mutuata per i
 corsi di PPS e LSS. A tale scopo, fin dalla definizione delle fondamenta del
 progetto si è posta particolare attenzione nell'adozione di una metodologia tale
 da integrare le peculiarità di entrambi i corsi. Il report di PPS descrive

src/lss-report/2-ddd.md

@@ -1,7 +1,7 @@
-# Aspetti di Domanin Driven Design
+# Aspetti di Domain Driven Design
 
 Sin dalle prime iterazioni di progetto, particolare attenzione è stata posta
-nell'utilizzo di metodologie di topo Domain Driven. Nella pratica,
+nell'utilizzo dell'approccio Domain Driven Design. Nella pratica,
 [una board collaborativa **Miro**](https://miro.com/app/board/o9J_lfd9ZK0=/) è
 stata utilizzata per mettere nero su bianco idee e concetti base. È bene
 sottolineare che oltre ai costrutti richiesti dal DDD, la board contiene anche
@@ -11,12 +11,12 @@ componenti.
 ## Knowledge Crunching
 
 Prima ancora di mettere mano all'architettura di progetto, per diverse settimane
-sono state portate avanti sessioni di knowledge crunching che hanno visto la
+sono state effettuate sessioni di knowledge crunching che hanno visto la
 partecipazione di tutti i membri del team. Scopo di queste sessioni era lo
-studio del dominio applicativo, e la definizione di paletti tali da guidare lo
+studio del dominio applicativo, e la definizione di requisiti tali da guidare lo
 sviluppo in un'ottica DDD.
 
-Si sono in primo luogo andati a delineare in linea di massima i casi d'uso, per
+In primo luogo si sono andati a delineare in linea di massima i casi d'uso, per
 poi definire Ubiquitous Language e Bounded Context. Alla prima bozza degli
 stessi sono seguiti raffinamenti successivi, fino alla definizione di una
 struttura quanto più precisa e dettagliata.
@@ -25,57 +25,78 @@ Dal documento di Scrum Overview allegato in appendice è possibile individuare
 chiaramente come il primo Sprint tracciato (quello conseguente all'approvazione
 del progetto da parte del prof. Viroli) è stato interamente dedicato a questa
 fase. È però importante sottolineare come il lavoro di knowledge crunching sia
-iniziato ben prima, seppir con minore impegno, già dagli inizi di dicembre,
+iniziato ben prima, seppur con minore impegno, già dagli inizi di dicembre,
 ovvero dalla data di sottomissione dello stesso.
 
 ## Ubiquitous Language
 
-Di particolare importanza si è rilelvata l'individuazione di un Ubiquitous
-Language associato ai concetti alla base del progetto. Qui ne viene riportata la
+Di particolare importanza si è rilevata l'individuazione di un Ubiquitous
+Language originato dai concetti base del progetto. In @fig:ul viene riportata la
 versione finale, che comprende tutti i concetti principali. Sulla
 [board Miro](https://miro.com/app/board/o9J_lfd9ZK0=/) è disponibile una
 versione dello stesso nel quale viene ampliata la descrizione di ogni termine.
 
-![Ubiquitous Language del progetto.](./images/ul.jpg)
+![Ubiquitous Language del progetto.](./images/ul.jpg){#fig:ul}
 
 ## Individuazione dei requisiti e dei casi d'uso
 
 Nell'ambito di progetto sono stati individuati due principali attori, tali da
 interagire con lo stesso. Sulla base della loro definizione, sono stati quindi
-individuati vari casi d'uso:
+individuati vari casi d'uso, riportati in @fig:usecase:
 
 - **Storyteller**: rappresenta l'attore in grado di creare delle storie
   giocabili. Questo è di fatto un programmatore che usufruisce del framework, e
-  si assume quindi presenti delle conoscenze di programmazione Scala. La
-  creazione della storia consiste nella creazione delle `Room` e degli `Item` ad
-  essi associate (includendo come parte di questa interazione la definizione del
-  _come_ tali entità reagiscono ai comandi utente), e alla definizione della
-  grammatica alla base del motore per il riconoscimento dei comandi;
+  si assume quindi che abbia delle conoscenze di programmazione Scala. La
+  creazione della storia consiste nella definizione delle `Room` e degli `Item`
+  ad essa associati (includendo come parte di questa interazione la descrizione
+  di _come_ tali entità reagiscono ai comandi utente), e alla definizione dei
+  verbi che comporranno la grammatica di una specifica storia;
 
 - **User**: il termine indica l'attore che usufruisce della storia giocabile.
   Esso interagisce con il sistema immettendo comandi testuali, e consultandone
   l'output risultante.
 
-![Diagramma dei casi d'uso del progetto.](./images/use-case.jpg)
+![Diagramma dei casi d'uso del progetto.](./images/use-case.jpg){#fig:usecase}
 
 ## Bounded context e Context map
 
 A seguito dell'individuazione dei casi d'uso, si è andata a espandere l'analisi
-andando ad individuare i principali bounded context associati al progetto.
+al fine di individuare i principali bounded context associati al progetto.
 
-![Context map di progetto.](./images/context-map.jpg)
+![Analisi dei bounded context di progetto.](./images/bounded-context-analysis.jpg){#fig:bcontextan}
 
-L'immagine riporta i principali bounded context, disposti con particolare
-attenzione alla complessità di modellazione degli stessi e all'importanza per il
-business. Si è intesa quest'ultima misura come rilevanza ti tale context, dal
-punto di vista di user e storyteller. Dal grafico si può individuare anche come
-le operazioni DevOps siano state elevate a vero e proprio bounded context: in
-ottica di effettuare un progetto di esame per LSS, esso rappresenta un vero e
-proprio requisito, ad alta complessità. L'utente finale, inteso come
+L'immagine @fig:bcontextan riporta i principali bounded context, posti nel
+grafico in base alla complessità di modellazione degli stessi e all'importanza
+per il business. Si è intesa quest'ultima misura come la rilevanza di tale
+context, dal punto di vista di user e storyteller. Dal grafico si può evincere
+anche come le operazioni DevOps siano state elevate a vero e proprio bounded
+context: in ottica di effettuare un progetto di esame per LSS, esso rappresenta
+un vero e proprio requisito, ad alta complessità. L'utente finale, inteso come
 storyteller/user, può percepire da tali operazioni benefici indiretti (es. nella
-velocità delle release, nella qualità dell'API), ma di fatto maniera indiretta.
+velocità delle release, nella qualità dell'API).
 
-I bounded context individuati nella sezione verde del grafico rappresentano i
-context core di progetto.
+Sulla base di questa analisi preliminare, si è andata quindi a definire la
+context map, mostrata in @fig:contextmap.
 
-<!-- todo individuazione della mappa dei context estesa -->
+![Context map di progetto.](./images/context-map.jpg){#fig:contextmap}
+
+Nello specifico, si è andato a accorpare quelli che erano stati individuati come
+bounded context di primaria importanza, in un unico **Core** bounded context.
+Questo in quanto, concettualmente, rappresentano moduli strettamente collegati.
+
+Il bounded context **Storyteller Application** include ciò che concerne
+l'implementazione di vere e proprie UI per l'interazione con l'utente. HTML è
+stato rappresentato come tratteggiato, in quanto rappresenta un elemento da
+valutare in corso d'opera.
+
+**Storyteller Support** include tutto ciò che concerne il supporto per lo
+storyteller alla costruzione della propria storia. In una libreria di queste
+dimensioni, fornire della documentazione di supporto diventa infatti un
+requisito di primaria importanza.
+
+Infine, è stato definito un bounded context anche per ciò che concerne le
+pratiche **DevOps**. Graficamente, essi sono sono collegati agli altri bounded
+context. Ma non per il fatto di non influenzare gli altri; anzi, i collegamenti
+non sono rappresentati per il semplice fatto che il primo contiene degli
+elementi per loro natura pervasivi, che influenzano in maniera indiretta a tutti
+gli altri bounded context.

src/lss-report/3-gradle-e-struttura.md

@@ -13,15 +13,17 @@ Gradle fornisce supporto per lo stesso.
 Si è predisposta una **struttura multi-progetto** il più possibile aderente
 all'analisi DDD effettuata. Sono stati definiti i seguenti sotto-progetti:
 
-- **core**: modulo che va a rappresentare di fatto i bounded context core di
+- **core**: modulo che va a rappresentare di fatto il bounded context core di
   progetto. Esso è stato pensato infatti per definire specifiche alla base del
-  model, della pipeline di progetto, la definizione del'API per lo storyteller,
-  e il motore semantico del gioco per l'interpretazione dei comandi;
-- **cli**: modulo che va a mappare il bounded context CLI. Rappresenta una
-  "piattaforma" sulle quali giocare le storie, basata su un'implementazione a
-  linea di comando. A livello pratico, CLI eredita come dipendenza il modulo
-  core, permettendo allo storyteller di iniziare a creare storie importando il
-  solo modulo cli.
+  model, della pipeline di progetto, la definizione dell'API per lo storyteller,
+  e l'engine Prolog del gioco per l'interpretazione dei comandi;
+
+- **cli**: modulo che va a mappare l'elemento CLI del bounded context
+  Storyteller Application. Rappresenta una "piattaforma" sulle quali giocare le
+  storie, basata su un'implementazione a linea di comando. A livello pratico,
+  CLI eredita come dipendenza il modulo core, permettendo allo storyteller di
+  iniziare a creare storie importando il solo modulo cli.
+
 - **examples**: sono stati definiti diversi moduli che consistono di fatto in
   delle storie di esempio, giocabili da un'utente finale.
 
@@ -42,24 +44,24 @@ insiemi di sub-project. Una volta definiti, è quindi possibile includere tutte
 le configurazioni comuni semplicemente includendo all'interno dei singoli
 sub-project i convention plugin richiesti. In particolare:
 
-- `scalaquest.common-scala-conventions.gradle.kts`: definisce le configurazioni
-  comuni a tutti i sotto-progetti basati su linguaggio Scala (di fatto, tutti i
+- `scalaquest.common-scala-conventions`: definisce le configurazioni comuni a
+  tutti i sotto-progetti basati su linguaggio Scala (di fatto, tutti i
   sub-project). Questo comprende quindi i plugin Scala e la sua configurazione,
   scalatest e scoverage per la gestione dei test, un plugin per operazioni di
   lint-formatting del codice, varie opzioni comuni di configurazione del
   compilatore Scala, un plugin per il semantic versioning basato su Git;
 
-- `scalaquest.libraries-conventions.gradle.kts`: definisce le configurazioni
-  comuni a tutti i sotto-progetti che vanno a comporre una libreria Scala. Il
-  plugin a sua volta importa il plugin `common-scala-conventions`, rendendo
-  possibile configurare i moduli `core` e `cli` importando solamente
+- `scalaquest.libraries-conventions`: definisce le configurazioni comuni a tutti
+  i sotto-progetti che vanno a comporre una libreria Scala. Il plugin a sua
+  volta importa il plugin `common-scala-conventions`, rendendo possibile
+  configurare i moduli `core` e `cli` importando solamente
   `libraries-conventions`. Comprende il plugin java-library, la configurazione
   Scoverage specifica per le librerie, e la configurazione necessaria per la
   pubblicazione su Maven Central.
 
-- `scalaquest.examples-conventions.gradle.kts`: definisce le configurazioni
-  comuni a tutti i sotto-progetti esempio. Il plugin a sua volta importa il
-  plugin `common-scala-conventions`, rendendo possibile configurare gli esempi
+- `scalaquest.examples-conventions`: definisce le configurazioni comuni a tutti
+  i sotto-progetti esempio. Il plugin a sua volta importa il plugin
+  `common-scala-conventions`, rendendo possibile configurare gli esempi
   importando solamente `examples-conventions`. Complende il plugin application,
   la configurazione di Scoversage specifica per gli esempi, e la configurazione
   necessaria a rendere gli esempi giocabili da linea di comando.

src/lss-report/4-modelli-di-sviluppo.md

@@ -0,0 +1,59 @@
+# Modelli di sviluppo
+
+Durante lo sviluppo del progetto, non si è adottato sempre lo stesso modello di
+sviluppo. Nelle prime fasi di progetto, durante le quali non si aveva del codice
+abbastanza stabile da essere "rilasciabile", si è seguito un approccio più
+flessibile e prototipale, denominato GitFlow, per poi evolvere il modello ad un
+più strutturato GitFlow.
+
+## GitHub Flow in fase embrionale
+
+**GitHub Flow** è un modello di sviluppo ispirato a GitFlow, ma con alcune
+caratteristiche che lo rendono più flessibile e semplice da porre in atto.
+
+Il modello richiede ad esempio che la versione stabile del software sia
+mantenuta su un branch `main` (o `master`), senza però la necessità di un branch
+`dev` parallelo. Allo stesso tempo, però, GitHub Flow suggerisce di organizzare
+il lavoro in `feature/*` branch, come in GitFlow, i quali confluiscono nel main
+a seguito della revisione di un secondo utente.
+
+Alla luce di ciò, le prime iterazioni di progetto hanno presentato particolare
+flessibilità sulle modalità di modifica del codice. Le varie feature sono state
+sviluppate sui rispettivi `feature/*` branch, poi riversati nel `main` tramite
+pull request. Si è subordinato la chiusura di queste alla revisione da parte di
+un membro del team (solitamente, non appartenente allo stesso sub-team) e al
+passaggio di determitati workflow di CI e QA (descritti al {@sec:chap5}).
+
+## GitFlow a regime
+
+Una volta predisposta una codebase sufficientemente stabile, e una volta
+abilitati i workflow di Continuous Deploy, si è migrato al più strutturato
+modello **GitFlow**. Questo permette di avere nel branch `main` la versione
+ufficiale e stabile, sempre associata a una release. A ogni push nel `main` deve
+corrispondere un tag, associato a sua volta a un numero di versione. La versione
+"di lavoro" del codice, stabile ma potenzialmente parziale, risiede nel branch
+`dev`.
+
+I vari `feature/*` branch confluiscono ora tramite pull request in `dev`, con
+gli stessi vincoli formulati per modello precedente (controlli di CI obbligatori
+e revisione di un utente). In aggiunta, per una maggiore leggibilità e
+organizzazione del codice, si è adottata una precisa politica di merge, che
+prevede che queste pull request vengano chiuse tramite **squash and merge**.
+
+Il `main` viene aggiornato tramite delle pull request sullo stesso originate da
+branch `release/X.Y.Z` (o `hotfix/X.Y.Z`), originati dal `dev`, dove con `X.Y.Z`
+si intende un numero di versione formulato secondo semantic versioning. Queste
+pull request presentano, oltre ai vincoli di validazione visti per le precedenti
+(controlli di CI e revisione di un membro del team), anche la necessità di
+presentare una coverage superiore al 75% nei moduli `core` e `cli`. Sono poi
+presenti degli accorgimenti di automazione ulteriori per la delivery
+automatizzata degli artefatti, e la gestione dei tag, indicati in {@sec:chap6}.
+Infine, una politica di merge ben precisa è adottata alla chiusura di queste
+pull request, le quali richiedono un **merge commit** che riporti, come commento
+del commit, un breve changelog[^1].
+
+[^1]: è necessario far presente che alcuni problemi sono incorsi tra la release
+
+0.3.1 e 0.4.0, frangente nel quale, a seguito di un errore nelle politiche di
+commit, si è dovuto agire tramite rebase per preservare la repository. La storia
+tra questi due tag risulta quindi non perfettamente lineare.