Automazione del changelog, e i suoi limiti

L’automazione del changelog funziona quando automatizza raccolta, classificazione e pubblicazione, e si ferma a selezione e formulazione. Automatizzate tutto e spedite un git log formattato; non automatizzate nulla e il changelog viene scritto a raffiche, a memoria, prima dei rilasci. La domanda utile è quali parti automatizzare, non quanto.

I progetti di automazione del changelog falliscono in una di due direzioni, ed entrambe sono prevedibili dal primo incontro di design. Automatizzate troppo poco e il changelog è un documento che qualcuno dovrebbe aggiornare, il che significa che viene aggiornato a raffiche, da chi ha pescato la cannuccia più corta. Automatizzate troppo e diventa un git log formattato: completo, accurato, e letto da nessuno.

Quali parti di un changelog dovrebbero essere automatizzate?

Tre dei quattro passi. Raccolta e pubblicazione completamente; classificazione come prima passata con override umano; selezione e formulazione mai.

Raccolta. Portare i cambiamenti dal luogo dove accadono (commit, PR, ticket) in una lista. Automatizzate questo completamente. Gli umani sono scarsi in questo, è noioso, ed è il passo che viene saltato sotto scadenza. Conventional commits o le etichette PR sono la materia prima abituale.

Classificazione. Decidere se qualcosa è Added, Fixed, Changed, Deprecated, Removed o Security. Automatizzate la prima passata dal tipo di commit o dall’etichetta PR, e lasciate che un umano faccia override. La precisione qui è intorno all’ottanta percento solo dai metadati, e il venti percento sbagliato è concentrato esattamente nelle voci che contano, perché l’ambiguità correla con il significato.

Selezione e formulazione. Decidere cosa dovrebbe sapere un lettore e come dirlo. Non automatizzate questo. È tutto il valore dell’artefatto. Tutto il resto è logistica.

Pubblicazione. Portare le voci finite su una pagina, un feed, un’email, un widget in-app, un canale Slack. Automatizzate completamente, e da una fonte. Qui va la maggior parte dello sforzo manuale reale, e quasi nessuno lo conta. È anche il passo che può dire a chi ha chiesto il cambiamento che è stato rilasciato, che è tutto il tema di chiudere il ciclo di feedback dal changelog. La metà email di quel passo ha una sua forma propria, nel template email di aggiornamento prodotto.

Quest’ultimo punto merita di essere considerato. I team tendono a vedere il changelog come un problema di scrittura, e poi passano la maggior parte del tempo sulla distribuzione: copiare voci in uno strumento email, riformattare per l’in-app, incollare su Slack, aggiornare una pagina docs. La scrittura richiede un’ora. La copia richiede un’ora per ogni rilascio, per sempre, ed è la parte che dovrebbe avere una macchina.

Cosa succede quando il confine si sposta?

Spostatelo in alto e ottenete un dump di git. L’automazione totale dai commit produce bump deps, fix flaky test, wip e address review comments davanti ai clienti. Ogni team che lo ha fatto ha poi aggiunto un filtro, e il filtro è un passo di selezione reintrodotto sotto un altro nome, con ergonomia peggiore.

Spostatelo in basso e ottenete raffiche. La raccolta totalmente manuale significa che le voci vengono scritte a memoria al momento del rilascio. Quella è la modalità contro cui Keep a Changelog avverte fin dall’inizio, e si degrada silenziosamente: il changelog sembra mantenuto fino alla settimana in cui nessuno ha avuto tempo.

Come appare una pipeline di automazione del changelog?

Quattro passi, con esattamente un cancello umano, posto dove una bozza diventa pubblica.

1. Al merge, derivate una voce bozza dalla PR: tipo da etichetta o prefisso commit, titolo come prima bozza, link di ritorno alla PR, autrice registrata. Fatela atterrare in un cassetto non rilasciato.
2. Chiunque può editare qualsiasi bozza in qualsiasi momento, e editare è economico. La maggior parte riceve una riga riscritta.
3. Tagliare un rilascio richiede che ogni voce nel cassetto sia o editata o marcata esplicitamente come interna. Questo cancello è tutto il design. Senza di esso, le bozze vengono rilasciate non editate nella settimana impegnata.
4. Pubblicare è un fan-out dall’insieme rilasciato: la pagina pubblica, il feed, l’email, il widget, il post Slack. Una fonte, più rendering, nessuna copia.

Il passo 3 è l’unico posto dove è richiesta una persona, e richiede circa dieci minuti per rilascio una volta che le bozze sono decenti. Dove è coinvolta una richiesta di un cliente, la bozza porta anche l’issue che chiude, il che è ciò che permette al passo 4 di avvisare chi ha chiesto; la template di richiesta funzionalità è progettata perché quel link sopravviva. Dove si colloca questo passo nel flusso di rilascio più ampio è il tema del processo di release management.

Cosa richiede l’automazione dai vostri dati?

Niente di tutto questo funziona se il changelog è un file Markdown, perché un file non può essere reso su cinque superfici senza riparsarlo, e parsare la prosa è come si finisce con un widget che mostra metà titolo.

Le voci devono essere strutturate: un tipo, una data, una versione o identificatore di rilascio, un pubblico, un corpo e un link. Allora il file, la pagina, il feed e l’email sono tutte viste. Quel punto strutturale è l’unica cosa che vale la pena fare bene prima di scegliere uno strumento, perché è ciò che non potete aggiungere dopo a basso costo. Niente di tutto questo funziona se poi una voce non viene davvero creata per ogni cambiamento che ne ha bisogno; imporre una voce di changelog in CI copre come far rifiutare alla pipeline un merge senza voce, invece di lasciare quel passaggio alla memoria.

Costruiamo changeloop, dove il changelog è prima un feed e poi una pagina, quindi leggete questo come un interesse piuttosto che una raccomandazione imparziale; il pricing è un repository gratuito senza carta, sufficiente per vedere la forma. Strumenti per il changelog è la nostra rassegna di cos’altro c’è, inclusi i prodotti con cui competiamo, e il generatore di changelog fa i passi di raccolta e classificazione nel browser se volete vedere la derivazione prima di impegnarvi in una pipeline.

Il test

Contate i minuti tra un cambiamento mergiato e quel cambiamento visibile a una cliente che non legge il vostro repo. Se la maggior parte di quei minuti è qualcuno che copia testo tra strumenti, l’automazione di cui avete bisogno è nella pubblicazione, non nella scrittura.

FAQ

Può l’IA scrivere il changelog? Può redigerne una bozza. Un modello a cui viene data la pull request mergiata produce la maggior parte delle volte una prima bozza utilizzabile del titolo e del corpo, il che è raccolta e classificazione fatte meglio. La selezione, se dire qualcosa a un lettore, e la formulazione finale, hanno ancora bisogno della persona che conosce il pubblico, e una pipeline che pubblica bozze senza quel cancello ha automatizzato il passo sbagliato.

Qual è la differenza tra un generatore di changelog e l’automazione del changelog? Un generatore trasforma i commit in una lista formattata una volta, su richiesta. L’automazione gira ad ogni merge, mantiene un cassetto non rilasciato, condiziona il rilascio alla revisione umana, e pubblica su ogni superficie da una fonte. Il generatore è il primo passo della pipeline, eseguito a mano.

Il changelog dovrebbe essere automatizzato dai commit o dalle pull request? Dalle pull request, dove l’unità di cambiamento è la PR: il titolo e la descrizione sono scritti una volta, per l’intero cambiamento, e la PR collega l’issue che chiude. La derivazione basata su commit funziona quando il commit è l’unità e segue una convenzione.

Come si impedisce all’automazione di pubblicare cambiamenti interni? Classificate chore, ci, test, refactor e aggiornamenti di dipendenze come interni per default, e rendete la promozione a pubblico un atto deliberato. Il default inverso, pubblico a meno che qualcuno lo nasconda, è come bump deps raggiunge i clienti.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Strumenti di changelog a confronto, Generatore di changelog