Il blog di changeloop
Le release notes, in pratica
Due cose a cui pensiamo molto: come scrivere release notes che qualcuno legga e come smettere di mantenere un changelog a mano. Niente newsletter, niente registrazione. Solo gli articoli.
Release notes per le correzioni di bug: voci che servono
Le release notes delle correzioni di bug funzionano se ogni voce nomina sintomo, persone colpite e azione. Riscritture e regole su sicurezza e dati.
Release notes in pratica8 min di lettura
Come chiedere feedback ai clienti in un prodotto software
Fai una domanda specifica subito dopo che l'utente ha fatto qualcosa, dove sta lavorando. Formulazioni pronte per ogni momento e le richieste da evitare.
Ciclo di feedback7 min di lettura
Esempi di roadmap di prodotto: sei formati e come falliscono
Sei esempi di roadmap di prodotto con voci realistiche: Now/Next/Later, trimestrale, per temi, per risultati, pubblica e di rilascio. Dove si rompono.
Ciclo di feedback7 min di lettura
Processo di release management per chi rilascia spesso
Un processo di release management in sette passi, con responsabile e criteri di uscita per ciascuno, più le metriche DORA e un altro KPI da seguire.
Ingegneria8 min di lettura
Esempi di release notes per ogni tipo di modifica
Esempi di release notes per una funzionalità, una correzione, una breaking change, un fix di sicurezza, una deprecazione, un app store e una nota interna.
Release notes in pratica8 min di lettura
Versionamento API di Stripe: come funziona e cosa copiare
Il versionamento API di Stripe fissa ogni account a una versione datata e ammette l'override per richiesta. Come funziona, cosa costa e cosa copiare.
Modifiche alle API7 min di lettura
Chi scrive il changelog, e chi dovrebbe
Chi scrive il changelog? Chi apre la PR sa cosa è cambiato, la PM perché conta. Nessuna delle due scrive sola una voce utile, e sceglierne una la logora.
Ingegneria5 min di lettura
Release notes di emergenza: scrivere sotto vera pressione
Un rilascio guidato da un incidente richiede note scritte in minuti, non giorni, e il solito processo di scrittura presuppone tempo che non avete.
Release notes in pratica5 min di lettura
I breaking change di Protobuf: cosa sopravvive sul wire
I breaking change di Protobuf avvengono sul wire, non nell'URL. Certi cambi di campo gRPC sono gratis, altri rompono i client muti, e sembrano uguali.
Modifiche alle API6 min di lettura
Formati file del changelog: JSON, YAML o solo Markdown
Il formato del file di un changelog decide se alimenta una pagina e un widget, o solo lo legge una persona. Markdown, JSON e YAML costano cose diverse.
Ingegneria5 min di lettura
Richieste duplicate: unire senza perdere la voce originale
Raggruppare richieste di funzionalità duplicate protegge il conteggio. Unirle senza cura perde la formulazione che rendeva utile una di esse.
Ciclo di feedback6 min di lettura
Deprecazione di GraphQL senza numero di versione
GraphQL non ha v1 o v2 nell'URL. I campi si deprecano uno alla volta con una direttiva, su uno schema condiviso, e questo cambia cosa deve un changelog.
Modifiche alle API6 min di lettura
Come scrivere una guida di migrazione per API
Una guida di migrazione API trasforma un cambiamento incompatibile in una checklist. Cosa deve contenere, e perché una voce di changelog da sola non basta.
Modifiche alle API5 min di lettura
Un check di changelog per GitHub Actions
Un check di changelog in GitHub Actions rifiuta il merge senza una voce, perché affidarsi alla memoria fallisce puntualmente. E cosa rompe quel check.
Ingegneria5 min di lettura
Come rifiutare una richiesta senza perdere la cliente
Chiudere il cerchio di solito vuol dire dire a qualcuno che la sua richiesta è uscita. La parte difficile è dire di no senza rovinare il rapporto.
Ciclo di feedback5 min di lettura
Release notes per i feature flag: cosa dire, e quando
Le release notes per i feature flag separano merge e rilascio, che con un flag non coincidono. Chiudere il ciclo presto annuncia una funzione invisibile.
Ciclo di feedback6 min di lettura
Quando una richiesta di funzionalità è in realtà un bug
Un ticket che chiede una nuova impostazione può essere un workaround per un bug nascosto. L'etichetta sbagliata la manda a coda e responsabile sbagliate.
Ciclo di feedback5 min di lettura
Come tracciare le richieste di funzionalità senza perderle
Il tracciamento delle richieste fallisce di solito in due modi: non arrivano da nessuna parte, o dove nessuno le riguarda. Un sistema che regge a entrambi.
Ciclo di feedback6 min di lettura
Ticket di supporto vs. richieste: di cosa ti fidi?
Un ticket di supporto e una bacheca richieste misurano cose diverse, e trattare un picco nell'uno come nell'altro produce priorità sbagliate con sicurezza.
Ciclo di feedback5 min di lettura
Tag git, release e il tuo changelog
Un tag git, una release e una voce di changelog sono tre registrazioni di un evento. Confonderli fa deragliare il changelog. Come farli combaciare.
Ingegneria5 min di lettura
Changelog di API interne: cosa cambia per l'altro team
Un changelog di API pubblica ha un pubblico che non puoi contattare. Uno interno ha un pubblico a due piani di distanza, e questo cambia cosa gli si deve.
Modifiche alle API6 min di lettura
Release note interne: chi altro deve sapere cosa è uscito
Supporto e vendite di solito scoprono un lancio da una cliente confusa. Le release note interne lo risolvono, con una forma diversa da quelle pubbliche.
Release notes in pratica5 min di lettura
Changelog nei monorepo: uno solo, o uno per pacchetto?
Un monorepo può avere un changelog per tutto il repo o uno per pacchetto, e scegliere male rende ogni release troppo confusa da leggere o troppo dispersa.
Ingegneria5 min di lettura
Come annunciare una nuova funzionalità (senza silenzio)
La maggior parte degli annunci muore in un canale che nessuno legge due volte. Dove annunciare, cosa dire per primo, e chi raggiungere per primo.
Release notes in pratica5 min di lettura
Release notes per app mobile: cosa taglia il limite
App Store e Play Store danno poche righe visibili e nessun link. Ciò che funziona in un changelog web si rompe con quel budget così ristretto.
Release notes in pratica5 min di lettura
Dare priorità alle richieste che si accumulano
Un backlog lascia la domanda difficile: quale richiesta esce per prima. I framework utili, dove ognuno si rompe e cosa nasconde il conteggio dei voti.
Ciclo di feedback6 min di lettura
Release notes enterprise: cosa cambia per un solo account
Le release notes enterprise per un cliente su build privata vanno calibrate sulla sua istanza. Sbagliare svela la roadmap o confonde il suo supporto.
Release notes in pratica5 min di lettura
Semantic versioning e il tuo changelog
Il semantic versioning dice a chi chiama quanto può fargli male una release prima di leggere il changelog. Cosa promette ogni numero e cosa deve una voce.
Ingegneria5 min di lettura
L'header sunset delle API, e quando inviarne uno
L'header sunset delle API dice quando una versione smette di rispondere, a differenza di una deprecazione. Cosa copre la RFC 8594, cosa dà un brownout.
Modifiche alle API5 min di lettura
Changelog dei webhook: il breaking change non richiesto
Un cambiamento nel payload di un webhook si rompe in silenzio, perché nessuno lo rifiuta. Cosa rende breaking un cambio di payload, e come versionarlo.
Modifiche alle API6 min di lettura
Changelog: cos'è, con un esempio di voce
Un changelog è il registro datato delle modifiche a un prodotto. Un esempio di voce, la differenza dalle release notes e dal commit log, dove pubblicarlo.
Release notes in pratica5 min di lettura
Changelog di API: cosa pubblicare e chi lo legge
Un changelog di API lo legge chi decide se il proprio codice funzionerà ancora il mese prossimo. Cosa deve ogni voce, dove vive, come ci si iscrive.
Modifiche alle API7 min di lettura
Come costruire una pagina di changelog che si segue
Una pagina di changelog vale la pena quando qualcuno ci torna. Dove dovrebbe vivere, cosa serve a ogni voce, feed e markup, e come si inserisce il widget.
Ingegneria6 min di lettura
Il template email di aggiornamento prodotto che si legge
L'email di aggiornamento che si legge è andata a chi l'ha chiesta. Un template, i quattro tipi di email, oggetti efficaci, segmentazione e consenso.
Release notes in pratica6 min di lettura
Come deprecare un'API senza perdere gli sviluppatori
La deprecazione è una promessa con una data. Il calendario, il modello di avviso, gli header di risposta, e il passo che evita un incidente al sunset.
Modifiche alle API7 min di lettura
Buone pratiche di versionamento API, per i chiamanti
Versionate solo ciò che rompe qualcosa, mettete la versione ben visibile, e mantenete la vecchia attiva fino a una data. Quattro schemi a confronto.
Modifiche alle API8 min di lettura
Cambiamenti che rompono: cosa conta e come rilasciarli
Un cambiamento che rompe qualcosa è uno che un chiamante corretto non sopravvive. Cosa conta, cosa no, come intercettarlo in CI e come rilasciarlo.
Modifiche alle API10 min di lettura
Chiudere il ciclo di feedback dal changelog
Un ciclo di feedback si chiude quando chi ha chiesto sa: rilasciato. Quattro passi, dove si rompe, e perché il changelog è il posto giusto per chiuderlo.
Ciclo di feedback8 min di lettura
Template di richiesta funzionalità che diventa changelog
Una richiesta di funzionalità serve solo se si trova al rilascio. Il modello, le etichette che la instradano, e i campi che poi legge il changelog.
Ciclo di feedback6 min di lettura
Roadmap pubblica dal vostro issue tracker, tre colonne
Una roadmap pubblica è una promessa sul futuro. Tenetela piccola, alimentatela dai vostri issue, e spostate ogni elemento con un'etichetta sul suo issue.
Ciclo di feedback6 min di lettura
Automazione del changelog, e i suoi limiti
Automatizzate raccolta, formattazione e pubblicazione. Non automatizzate selezione o formulazione. Dove sta il confine e cosa succede quando si muove.
Ingegneria6 min di lettura
Changelog vs release notes: qual è la differenza?
Un changelog è un registro continuo per chi cerca qualcosa. Le release notes sono un messaggio curato per chi decide se interessarsene. Ecco la divisione.
Release notes in pratica5 min di lettura
Dai conventional commits a un changelog
I conventional commit rendono un changelog derivabile. Non lo rendono leggibile. Cosa offre la convenzione, dove si ferma, e come colmare il divario.
Ingegneria6 min di lettura
Come scrivere release notes che la gente legge davvero
«Correzioni di bug e miglioramenti prestazioni» non è una release note. La domanda a cui ogni voce deve rispondere, e la riscrittura di una reale.
Release notes in pratica6 min di lettura
Keep a Changelog, davvero implementato
La specifica è una pagina e si legge in dieci minuti. Implementarla è dove i team deviano. Cosa dice, cosa lascia aperto, e dove finisce per sbagliare.
Ingegneria5 min di lettura
Buone pratiche per le release notes che meritano
La maggior parte delle liste di buone pratiche sono consigli di stile. Queste cambiano cosa fa il lettore, e tre popolari che sono puro culto della forma.
Release notes in pratica6 min di lettura