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.

  • Alpha vs beta testing: differenze e quando usarli

    Alpha e beta testing a confronto: chi testa, quanto è finita la build, beta chiusa e aperta, criteri di uscita e come raccogliere e rispondere ai feedback.

    Ciclo di feedback7 min di lettura

  • Cos'è un hotfix? Significato, hotfix vs patch e rilascio

    Un hotfix è una correzione urgente rilasciata fuori dal ciclo di release normale. Cosa significa, come si distingue da patch e bugfix, come rilasciarlo.

    Ingegneria7 min di lettura

  • Modello Kano: ordina le richieste come le vivono i clienti

    Il modello Kano divide le funzionalità in obbligatorie, di prestazione e di piacere con un sondaggio a due domande. Come usarlo sulle richieste e leggerlo.

    Ciclo di feedback6 min di lettura

  • Release candidate (RC): cos'è e come gestirla

    Una release candidate è una build che esce come versione finale se i test non trovano blocchi. Dove sta dopo la beta, come numerarla e i criteri di uscita.

    Ingegneria5 min di lettura

  • RICE scoring: formula, esempio pratico e errori comuni

    Il RICE scoring ordina le idee per reach, impact, confidence ed effort. Formula, esempio con quattro funzionalità, scale ed errori che falsano i punteggi.

    Ciclo di feedback5 min di lettura

  • CHANGELOG.md: cosa contiene e come tenerlo aggiornato

    Un CHANGELOG.md registra per i lettori ciò che cambia in ogni versione. Le sezioni che servono, un esempio completo e l'abitudine che lo tiene aggiornato.

    Ingegneria6 min di lettura

  • Release notes su GitHub: generarle, poi renderle leggibili

    GitHub crea una bozza di release notes dalle pull request integrate con un clic. Cosa contiene, come la struttura release.yml e come renderla leggibile.

    Ingegneria7 min di lettura

  • Come costruire una roadmap di prodotto dal feedback

    Come costruire una roadmap di prodotto in sei passaggi, partendo dalle richieste che hai già. Raggruppa, ordina, indica la certezza e rivedi.

    Ciclo di feedback5 min di lettura

  • Template di roadmap di prodotto: i campi da copiare

    Un template di roadmap di prodotto è una tabella con campi fissi per ogni voce. Copia la versione a sei campi, vedila compilata e scopri cosa tagliare.

    Ciclo di feedback6 min di lettura

  • Versionamento REST API: URL, header o query, quale scegliere

    Il versionamento REST API mette la versione nel percorso, in un header o nella query string. Cosa comporta per chiamanti, cache e annunci, con esempi.

    Modifiche alle API6 min di lettura

  • Release notes software: cosa sono e cosa includere

    Le release notes software dicono al lettore cosa è cambiato in una versione, chi riguarda e cosa fare. I quattro tipi, cosa includere e un esempio.

    Release notes in pratica5 min di lettura

  • 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 feedback8 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 API8 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 API7 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.

    Ingegneria6 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

  • Imporre una voce di changelog in GitHub Actions: workflow

    Un check di changelog in GitHub Actions rifiuta il merge senza una voce, perché affidarsi alla memoria fallisce puntualmente. E cosa rompe quel check.

    Ingegneria6 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

  • 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

  • Richiesta di funzionalità vs bug: come distinguerli

    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

  • 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 vs release GitHub vs changelog: le differenze

    Un tag git, una release e una voce di changelog sono tre registrazioni di un evento. Confonderli fa deragliare il changelog. Come farli combaciare.

    Ingegneria6 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 pratica6 min di lettura

  • Release notes app mobile: limiti di App Store e Google Play

    Su App Store le note arrivano a 4.000 caratteri, su Google Play a 500, e mostrano poche righe senza link. Cosa taglia il limite e come tagliare bene.

    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.

    Ingegneria6 min di lettura

  • Annunciare una nuova funzionalità: modelli e come scriverlo

    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 pratica6 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 changelog: cosa significa ogni salto

    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.

    Ingegneria6 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

  • Cos'è un changelog? Definizione ed esempio di voce

    Un changelog è il registro datato delle modifiche a un prodotto, scritto per i suoi utenti. La definizione, una voce di esempio e un modello da copiare.

    Release notes in pratica6 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

  • Changelog pubblico: come costruire una pagina 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.

    Ingegneria7 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

  • Deprecazione di API: tempistiche, avviso e header RFC 9745

    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

  • Cos'è un breaking change? Cosa conta e come rilasciarlo

    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 API11 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 feedback7 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: cosa automatizzare e cosa no

    Automatizzate raccolta, formattazione e pubblicazione. Non automatizzate selezione o formulazione. Dove sta il confine e cosa succede quando si muove.

    Ingegneria7 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. Cosa li distingue.

    Release notes in pratica6 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 pratica7 min di lettura

  • Keep a Changelog spiegato, con un template CHANGELOG.md

    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.

    Ingegneria6 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