Polygen SemVer in makefile

[tajmone]

Riporto qui quanto discusso su polygen-docs Issue #1:

Anche OCaml si attiene alla Semantic Versioning syntax (semver), il ché operativamente si traduce in una cosa: possiamo usare cppo (il preprocessore C-like di OCaml, da non confondere con camlp4 o camlp5 che appartengono alla categoria dei più sofisticati e generali preprocess-parse-pretty-printer) per i version number ecc.

Mi pare tu ti muova bene in questi territori, quindi magari un piccolo task per te potrebbe essere il seguente: sistemare il meccanismo di version syntax che avevo fatto all'epoca (il semplicissimo ver.ml.template che genera ver.ml tramite sed con una regole di makefile) e portarlo allo stato dell'arte attuale secondo le convenzioni di semver.

Se leggi il man di cppo vedrai che ci sono alcune macro (si chiamano così i simboli user-defined del preprocessore) atte all'uopo.

Ho iniziato a dare un'occhiata. Ricapitolando, se ho capito bene:

1. Il makefile legge il numero di versin dal file VERSION, w lo inietta nella variabile $VERSION
2. Il makefile usa sed per iniettare la stringa di $VERSION nel template ver.ml.template, salvando l'output in ver.ml
3. ver.ml viene infine usato nel codice sorgente come variabile di riferimento alla versione attuale — p.es., in main.ml (81–83:

let usage = (sprintf "Polygen v%s built %s - http://www.polygen.org\n" Ver.ver Ver.date)
          ^ "(c) 2002, 2003, 2004, 20015 Alvise Spano'\n\n"
          ^ "usage: polygen [OPTION]... SOURCES...\n\n"
          ^ " SOURCE     source file(s) providing grammar definition\n\n"
          ^ " OPTION"

La parte del makefile in questione per il punto (2) mi pare questa (righe 10 e 56–):

VERSION    := $(shell cat <VERSION)

[...]

ver.ml: ver.ml.template
    sed -e "s/%VERSION%/$(VERSION)/" -e "s/%DATE%/$(DATE)/" ver.ml.template >ver.ml

che dovrebbe creare ver.ml usando ver.ml.template come template, e iniettandovi il valore di $VERSION:

ver.ml.template:

let ver = "%VERSION%"

che genera ver.ml:

let ver = "1.1.0"

Quindi, alla fine, tutto si riduce al definire la version tramite una stringa nel file VERSION:

1.1.0

Non mi è chiaro che cosa mi chiedi esattamente rispetto alla SemVer. Vuoi un sistema di validazione della stringa? un sistema di automazione dell'incremento di versione?

Il sistema attuale sembra andare benissimo, basta solo assicurarsi di immettere una stringa che sia corretta dal punto di vista di SemVer 2.0 nel file VERSION. Le uniche accortezze con SemVer riguardano in genere l'uso dei segmenti (opzionali) pre-release e build metadata.

La notazione SemVer 2.0 è abbastanza semplice:

(link per anteprima a schermo intero)

E finché ci atteniamo ad'essa non dovrebbero esserci problemi con il sistema attuale per la gestione della versione.

L'unica cosa che mi viene in mente è di utilizzare uno strumento per validare la stringa, e assicurarsi di non pubblicare Polygen con una stringa SemVer non valida. Si potrebbe inserire questa verifica nel makefile stesso.

Premetto fin da subito che esistono già vari strumenti da riga di comando per validare stringhe SemVer e maneggiarle in vari modo (p.es. controllare se una data versione rientra in un range, o implementare version constraint operators, ecc), ma la maggior parte di essi sono realizzati in Javascript, disponibili come API o come "comandi" CLI. Se Javascript rapresentasse un problema per te, potrei adoperarmi a creare uno script che validi la stringa tramite espressioni regolari (ne ho già create di apposite per validare SemVer 2.0).

Secondo me, la soluzione migliore è quella di validare manualmente la stringa SemVer tramite uno strumento dedicato (online, o installando un tool CLI), per assicurarsi di non aver violato la notazione, dopodiché usare tranquillamente il sistema attuale. Per esempio, a questo link:

• http://jubianchi.github.io/semver-check/

è possibile digitare una stringa semver, e nel caso fosse malformata viene mostrata in rosso.