Questa pagina
Un registro delle modifiche, all’indirizzo /changelog e collegato dal piè di pagina. Ogni versione e, in mezzo, i cambiamenti che vale la pena nominare — letti da un solo elenco tipizzato e composti dal convertitore che il prodotto vende.
Un registro delle modifiche serve solo se puoi fidarti di quello che non c’è dentro, quindi ecco che cosa riceve una voce.
Che cosa entra
Tutto quello che noteresti usando TransformPipe: una conversione che prima non esisteva, una pagina nuova, un altro modo di accedere, un limite che si è spostato, un difetto visibilmente sbagliato. Una versione etichettata porta il proprio numero; quasi tutto quello che è uscito è uscito fra un’etichetta e l’altra e non ne porta nessuno, ed è per questo che l’elenco è più lungo dell’elenco delle versioni.
Che cosa no
Riscritture interne, aggiornamenti di dipendenze, lavoro di build e di infrastruttura: tutto ciò che da fuori è invisibile. La nota in cima alla pagina lo dice, ed è la ragione per tenerla vera: una voce su un file spostato renderebbe quella nota una bugia, e un registro che devi filtrare è un registro che smetti di leggere.
Un solo elenco, più posti
Ogni voce viene da un unico elenco tipizzato nel repository. La pagina, le cinque lingue pre-renderizzate, il lastmod nella mappa del sito e la manciata di voci con una pagina propria lo leggono tutti: non c’è un secondo file da tenere allineato, e quindi nessuno da dimenticare. I testi sono Markdown e li compone il convertitore del prodotto stesso: una nota di rilascio che rompesse il renderer romperebbe anche il documento di una cliente, e questo è un posto migliore per scoprirlo.
In inglese, di proposito
La cornice è tradotta: il titolo, l’occhiello, il pannello degli anni, e le date e i nomi dei mesi, che Intl compone nella tua lingua. Le voci no. Cinque traduzioni per voce, per versione, per sempre, sono un costo che si abbandona dopo la seconda versione, e un registro a cui mancano tre lingue è peggio di uno onestamente inglese. Dove una voce si è meritata una pagina propria, quella pagina si può tradurre: ce n’è una manciata, non una per versione.
Da leggere: note di rilascio scritte in Markdown e documentazione che vive nel repository.