Chi scrive il changelog, e chi dovrebbe

Chiedete a un team chi scrive il changelog e la risposta onesta di solito è “chiunque se ne ricordi”, che è la stessa modalità di fallimento che imporre una voce di changelog in CI esiste per risolvere a livello meccanico. Ma forzare l’esistenza di una voce non decide chi è qualificata a scriverne una buona, e i team che saltano quella domanda tendono a ripiegare su chiunque sia più facile da obbligare, di solito chi apre la PR, senza controllare se quella sia davvero la persona che può scriverla bene.

Perché chi apre la PR non è automaticamente chi scrive meglio il changelog?

Perché conosce l’implementazione, non necessariamente l’impatto, e sono due tipi di conoscenza diversi. Dove si fermano i conventional commit copre questo divario dal lato del messaggio di commit: fix(auth): reject expired refresh tokens è corretto e inutile per una cliente, e chi ha scritto quella correzione è spesso la persona meno attrezzata per tradurla, perché ha pensato in termini del bug per ore e ha perso la visuale esterna di cosa un’utente abbia effettivamente vissuto. È la stessa ragione per cui le tecniche di scrittura esistono come professione: tradurre l’implementazione in impatto è un’abilità distinta dall’aver costruito la cosa, e serve pratica indipendentemente da quanto sia brava la sviluppatrice nel codice in sé.

Questo significa che prodotto o supporto dovrebbero scrivere ogni voce al posto loro?

No, perché hanno il divario opposto: sanno cosa conta per le utenti ma non sempre cosa è stato davvero rilasciato, il che produce voci leggibili ma occasionalmente sbagliate nell’ambito, un “ora supporta X” per una funzionalità ancora dietro un flag, o una correzione descritta come completa quando copre solo uno di tre casi. La modalità di fallimento delle voci scritte da sviluppatrici è illeggibile-ma-accurata; la modalità di fallimento delle voci scritte da PM è leggibile-ma-non-verificata. Nessun ruolo possiede entrambe le metà di ciò di cui ha bisogno una buona voce.

Come appare davvero un modello di proprietà che funziona?

Una bozza da chi è più vicino al cambiamento, revisionata da chi è più vicino all’utente, con una persona nominata responsabile della formulazione finale invece che tutti assumano che qualcun altro catturerà i problemi. La bozza deve esistere ed essere accurata più di quanto debba essere buona; una frase grezza scritta da una sviluppatrice che dice correttamente cosa è cambiato è un punto di partenza migliore di una levigata ma non verificata, perché riscrivere per chiarezza è più facile che riscrivere per correttezza. Il passaggio di revisione è dove una PM o responsabile del supporto legge la bozza e fa l’unica domanda che cattura il divario di leggibilità: lo capirei se non avessi visto il codice.

Dovrebbe essere sempre la stessa persona quella responsabile, o ruota?

Nominata e stabile batte rotante, almeno per l’approvazione finale. Una responsabile rotante significa che ogni voce viene revisionata da qualcuno che ri-deriva da zero le convenzioni del team, il che è esattamente come la voce deriva da una voce all’altra e chi legge inizia a notare che il changelog è stato scritto da un comitato. Una singola persona, o un gruppo stabile molto piccolo, accumula nel tempo i giudizi, quando dire “migliorato” invece di nominare la cifra specifica, quando una correzione ha bisogno di una propria voce invece di confluire in un lotto, e quel giudizio vale più della distribuzione uniforme del lavoro.

Bozza (sviluppatrice, dalla PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revisionata (responsabile del changelog, verificata contro la PR reale):
"Corretto: le esportazioni ordinate per data potevano
restituire risultati fuori ordine oltre la prima pagina.
Ora coerente su tutte le pagine."

Un piccolo team ha bisogno di così tanto processo per una riga di testo?

Non i ruoli come persone separate, ma i due passaggi contano ancora anche in solitaria. Un team di una persona è sia la sviluppatrice sia la revisora, e la disciplina che sopravvive a quella scala è fare la revisione come un passaggio mentale separato, non saltare direttamente dallo scrivere la correzione al pubblicarne una descrizione nello stesso respiro. La trappola su piccola scala è saltare del tutto il secondo passaggio, non la mancanza di una seconda persona, perché nessuno esterno lo impone, e il divario di accuratezza che quel passaggio esiste per catturare non scompare solo perché la stessa persona potrebbe teoricamente notare il proprio punto cieco.

Cosa succede quando nessuno è responsabile della voce finale?

Il changelog degrada in modo irregolare invece di fallire apertamente, il che è peggio perché nessuno se ne accorge finché una lettrice non lo segnala. Alcune voci restano nitide perché a chi le ha scritte importava; altre diventano vaghe, “vari miglioramenti e correzioni di bug”, perché chi le ha scritte andava veloce e nessuno l’ha notato prima della pubblicazione. I vincoli di formato di Keep a Changelog catturano la deriva strutturale, date mancanti, categorie sbagliate, ma niente in un template cattura una voce vaga che è tecnicamente ben formattata, che è esattamente il divario che una responsabile nominata è lì per colmare.

FAQ

La responsabile del changelog dovrebbe essere un ruolo di ingegneria o di prodotto? Entrambi possono funzionare se la persona ha sia fluidità tecnica per verificare l’ambito sia abbastanza distanza dall’implementazione per scrivere per una lettrice esterna; il titolo conta meno di se sappia fare entrambe le metà, o sappia a chi chiedere per la metà che non sa fare.

Un programma rotante tipo reperibilità è mai appropriato per la proprietà del changelog? Per il volume, a volte, se il team è troppo piccolo perché una persona revisioni tutto; per voce e giudizio, no, perché è esattamente ciò che la rotazione erode. Una rotazione che condivide il carico di stesura mantenendo una revisora stabile ottiene il beneficio senza la deriva.

Qual è il segno più veloce che qualcosa non va nell’attuale configurazione di proprietà? Voci che sono accurate ma illeggibili, o leggibili ma sbagliate nell’ambito, in uno schema che segue chi le ha scritte. Se la qualità correla con l’autrice invece di restare coerente, la proprietà è il divario, non l’abilità di scrittura.

L’automazione riduce quanto conta la proprietà? Riduce quanta scrittura serve, non quanto giudizio serve. Automazione del changelog copre cosa una pipeline può generare in sicurezza, formattazione, pubblicazione, cross-posting; la formulazione, il raggruppamento e cosa conta come degno di menzione restano decisioni umane indipendentemente da quanto della pipeline sia automatizzata.

Cosa succede se l’autrice della PR e la revisora non sono d’accordo sulla formulazione? Decide la revisora, perché la domanda a cui sta rispondendo, capirebbe questo una lettrice esterna, è quella che il ruolo esiste per proteggere. Questo non rende inutile il parere della sviluppatrice: se il disaccordo riguarda l’accuratezza invece della formulazione, la revisora si rimette a lei, perché l’ambito è la metà che spetta all’autrice fare bene. Separare i due tipi di disaccordo, formulazione contro accuratezza, evita che la maggior parte di questi casi diventi uno stallo.

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