LSS revision (enhanched)

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

@@ -1,10 +1,10 @@
 # Gradle e struttura multi-progetto
 
 Una volta definiti i bounded context, si è proseguito andando a definire
-l'architettura di progetto. È stata predisposta la repository di base di
-progetto, dal nome
-[PPS-19-ScalaQuest](https://github.com/scalaquest/PPS-19-ScalaQuest). È qui che
-risiede il sorgente alla base dei principali moduli.
+l'architettura di progetto. È stata predisposta la repository di base, dal nome
+[scalaquest/PPS-19-ScalaQuest](https://github.com/scalaquest/PPS-19-ScalaQuest),
+come richiesto da specifiche di PPS. È qui che risiede il sorgente alla base dei
+principali moduli.
 
 Si è deciso di utilizzare il tool di build automation **Gradle** per strutturare
 il progetto. Pur non essendo pensato primariamente per il linguaggio Scala,
@@ -13,16 +13,18 @@ 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
-  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.
-- **examples**: sono stati definiti diversi moduli che consistono di fatto in
+- **Core**: modulo che va a rappresentare di fatto il bounded context Core. Esso
+  è stato pensato infatti per definire specifiche alla base del 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.
 
 ## Strategia basata su convention plugin
@@ -32,34 +34,38 @@ correttamente. Il dettaglio dei plugin specifici richiesti da ogni modulo viene
 trattato nei capitoli successivi.
 
 Di particolare interesse è invece una scelta architetturale che ha permesso di
-condividere tra vari insiemi di sub-projects plugin e configurazioni comuni. Si
-è infatti deciso di sfruttare una strategia fortemente raccomandata da Gradle
-nella sua documentazione, basata sui **convention plugins**.
+condividere, tra vari insiemi di sub-projects, plugin e configurazioni comuni.
+Si è infatti deciso di sfruttare una strategia fortemente raccomandata da Gradle
+nella sua documentazione, basata sui **convention plugin**.
 
 Questa consiste nella definizione di vari plugin custom all'interno della
-directory standard `buildSrc`, ognuno comprendente configurazioni comuni a
-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:
+directory standard `/buildSrc`, ognuno comprendente configurazioni comuni a più
+sotto-progetti, inscrivibili in determinate categorie. Una volta definiti, è
+quindi possibile includere tutte le configurazioni comuni semplicemente
+includendo all'interno dei singoli sotto-progetti 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
-  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.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 il plugin `scala` e la sua
+  configurazione, `scalatest` e `scoverage` per la gestione dei test, il plugin
+  `spotless` per operazioni di lint-formatting del codice, varie opzioni comuni
+  di configurazione del compilatore Scala, il plugin
+  `git-sensitive-semantic-versioning` per la gestione dei numeri di versione
+  delle release;
 
-- `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
-  `libraries-conventions`. Comprende il plugin java-library, la configurazione
-  Scoverage specifica per le librerie, e la configurazione necessaria per la
+- **scalaquest.libraries-conventions**: definisce le configurazioni comuni a
+  tutti i sotto-progetti che vanno a comporre una libreria Scala. Questo 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
-  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.
+- **scalaquest.examples-conventions**: definisce le configurazioni comuni a
+  tutti i sotto-progetti _Examples_. Questo 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.