Linee guida per i riferimenti alla versione di Alan Italian e la Alan SDK nei file sorgenti di codice e documentazione.
Indice dei contenuti
I file sorgenti della Libreria, delle avventure (test, ricettario, demo, ecc.) e della documentazione contengono riferimenti alla versione di Alan Italian cui fanno riferimento, nonché alla versione della Alan SDK richiesta.
Al fine di semplificare l'aggiornamento di tali riferimenti (tramite script d'automazione) sono state adottate alcune convenzioni standard.
Alan Italian adotta lo schema Semantic Versioning 2.0.0:
Supponendo che la versione attuale sia la versione 0.17.0 (Alpha), la versione estesa sarà riportata nel seguente formato:
v0.17.0-Alpha
mentre la versione breve sarà riportata come:
Alan Italian 17 Alpha
Quest'ultima viene impiegata nei sorgenti della Test Suite, del Ricettario e nelle Demo che usano la Libreria, poiché in questi casi non serve fare riferimento alla PATCH.
Invece, i moduli della libreria devono necessariamente riportare tutti i segmenti (MAJOR, MINOR, PATCH e PRE-RELEASE) dato che servono a distinguere e tracciare i vari aggiornamenti del sorgente specifico.
La versione di Alan è sempre riportata nel seguente formato:
Alan 3.0beta6 build 1878
Questo formato univoco semplifica le sostituzioni automatizzate.
La presenza della parte finale build <ver> è legata all'uso di developer snapshots (versioni Alpha), e va tenuto conto che nei periodi in cui si utilizzerà una Beta release tale segmento non sarà presente nella stringa di versione.
L'aggiornamento delle informazioni di versione avviene tramite script.
Lo script ver.sh definisce le versioni attuali di Alan Italian e Alan SDK:
#!/bin/bash
AlanSDK="3.0beta6 build 1880"
AlanITA="0.18.0"
AlanITA_RevDate="2019-03-19"Mentre lo script verbump.sh si occupa di sostituire tutte le occerrenze delle informazioni di versione nei sorgenti del progetto.
Una volta aggiornati i riferimenti sarà necessario eseguire tutti gli script automatizatti del progetto (test suite, documentazione, ecc.); a tal scopo è stato aggiunto uno script batch nella root del progetto:
Qui di seguito sono riassunti i vari passaggi eseguiti da verbump.sh:
- Attributi AsciiDoc nella documentazione
- Attributi Alan nella Libreria
- Commenti header nei moduli della Libreria
- Commenti header in sorgenti Alan
- Attributi AsciiDoc/Doxter in sorgenti Alan
Il file README.adoc contiene le informazioni di versione nello Header AsciiDoc, sotto forma di attributi alle righe 5 e 6:
= Alan Italian
Tristano Ajmone <tajmone@gmail.com>
2019-03-01
// tag::AlanRevInfo[]
:AlanItaV: 17
:AlanSDK: 3.0beta6 build 1878
:revnumber: 0.{AlanItaV}-Alpha
// end::AlanRevInfo[]Questi attributi vengono utilizzati anche dagli altri documenti tramite inclusione, quindi modificandone la definizione in questo documento aggiornerà la versione riportata in tutti i documenti HTML finali.
Il riferimento ad Alan Italian è in forma abbreviata.
Nel modulo alanlib_ita/lib_definizioni.i vengono definite la versione della Alan SDK utilizzata durante lo sviluppo e quella della Libreria:
HAS AlanV "3.0beta6 build 1878".
HAS AlanItaV "17 Alpha".
Questi attributi vengono mostrati nel banner dell'avventura, e gli autori possono modificarne i valori nelle proprie avventure qualora utilizzassero una versione differente del compilatore di Alan, o nel caso abbiano modificato i sorgenti della Libreria.
In questo progetto si dà per scontanto che tutte le avventure del progetto utilizzino la medesima Alan SDK, per cui non è necessario sovrascrivere questo attributo nelle singole avventure.
I moduli della libreria contengono le informazioni di versione nella quinta riga commentata dello header:
--= Alan StdLib Italian: Modulo Principale
--| Tristano Ajmone <tajmone@gmail.com>
--~-----------------------------------------------------------------------------
--~ "libreria.i"
--| v0.17.0-Alpha, 2019-02-27: Alan 3.0beta6 build 1878
--| ============================================================================
Ciascun modulo riporterà la propria versione attuale, nel formato esteso, seguito da , e la data dell'ultima modifica nel format YYYY-MM-DD, seguito da : e la versione della Alan SDK utilizzata.
Tutti i sorgenti delle avventure nel progetto, così come moduli aggiuntivi che non siano i moduli della Libreria, in genere contengono le informazioni di versione nella prima riga commentata:
-- Alan Italian 17 Alpha | Alan 3.0beta6 build 1878
A differenza dei moduli della libreria, viene usata la versione breve di Alan Italian poiché le informazioni di PATCH non sono rilevanti nel contesto.
La notazione è la seguente:
-- <Alan Italian versione breve> | <Alan SDK>
Questo si applica ai sorgenti della test suite, le demo e il ricettario. Alcune avventure demo non riportano questa riga di header — p.es. avventure che usano solo il modulo della grammatica italiana.
Alcune avventure vengono auto-documentate tramite Doxter — per esempio le avventure demo, qulle del Ricettario e anche alcune nella test suite.
I sorgenti delle avventure doxterizzate riportano le informazioni di versione in righe commentate per Doxter, di modo che diventino attributi Asciidoctor utilizzabili nell'autodocumentazione:
-->rev_info
--| :revdate: 2019-03-07
--| :revnumber: 1.0.0-alpha.1
--| :revremark: Alan 3.0beta6 build 1878
--<<
L'esatta collocazione di tali righe è variabile da sorgente a sorgente.
Si noti che :revnumber: in questo contesto non è un riferimento alla versione di Alan Italian ma a quella dell'avventura.
NOTA — Il sistema attualmente in uso nei sorgenti auto-documentati è provvisorio e va rivisto.