Changelog vs release notes: care e diferența?

Un changelog e un registru continuu, cumulativ al tot ce s-a schimbat, scris pentru cineva care caută ceva. Release notes sunt un mesaj selectat despre o versiune, scris pentru cineva care decide dacă îl privește. Diferența e audiența, nu formatarea, și majoritatea echipelor au nevoie de ambele: unul ca referință, unul ca anunț, derivate din aceleași intrări.

Majoritatea echipelor ajung să aibă unul dintre ele din întâmplare și celălalt la cerere. Începeți cu un changelog pentru că o dezvoltatoare vrea un registru al ce s-a lansat. Luni mai târziu cineva de la suport întreabă de ce clienții nu știau despre o funcție care e live din aprilie, și acum aveți nevoie de release notes.

Changelog vs release notes, alăturate

Ce e un changelog?

Un changelog e un registru cronologic, aproape complet al ce s-a schimbat, cel mai recent primul, cu fiecare intrare tipizată (added, changed, deprecated, removed, fixed, security) și datată. Cititorul lui a decis deja că îl interesează. Caută ceva: când s-a schimbat un comportament, dacă o eroare e corectată, ce versiune a introdus un flag. Completitudinea e toată valoarea, de aceea convenția Keep a Changelog petrece cea mai mare parte a singurei sale pagini pe structură și aproape deloc pe proză.

Ce sunt release notes?

Release notes sunt un mesaj selectiv, scris în proză, despre o versiune. Cititorul lor n-a decis încă nimic. Decide dacă această versiune îl privește, și dacă trebuie să facă ceva în legătură cu asta. Selecția e toată valoarea: o release note care listează totul e un changelog cu paragrafe, și eșuează cititorul în același fel în care un changelog care omite lucruri eșuează cititorul lui. Cum se scriu release notes e despre selecție și formulare.

Aveți nevoie atât de un changelog, cât și de release notes?

Aveți nevoie de ambele odată ce cele două audiențe voastre vor lucruri diferite; până atunci, un singur artefact care face ambele treburi e corect. Echipele mici publică o singură pagină /changelog cu un paragraf scurt în capul fiecărei intrări, și pentru o vreme asta servește la fel de bine o dezvoltatoare care caută o corecție și o clientă care scanează după noutăți. Împărțirea prea devreme vă dă două lucruri de întreținut și unul dintre ele va putrezi.

Împărțirea devine merituoasă când astea încep să se întâmple:

• Intrările voastre de changelog au crescut paragrafe explicative pe care dezvoltatorii le sar.
• Sau opusul: anunțurile voastre de lansare au început să listeze actualizări de dependențe.
• Suportul copiază intrări în e-mailuri și le rescrie pe drum.
• Cineva cere “doar schimbările care rup compatibilitatea” și nu le puteți filtra.

Ultimul e semnul adevărat. Dacă nimeni nu poate răspunde “ce s-a schimbat care mă afectează” fără să citească totul, aveți un singur artefact care face rău două treburi.

O sursă, două vizualizări

Greșeala e să le tratați ca două documente. Sunt două vizualizări asupra aceluiași set de schimbări.

Scrieți changelog-ul pe parcurs, o intrare pe schimbare semnificativă, fiecare etichetată cu ce este: fixed, added, changed, removed, deprecated, security. Păstrați intrările suficient de scurte încât să scrieți una să nu fie o decizie. Apoi, la momentul lansării, release notes sunt o selecție și o rescriere: luați intrările care contează pentru o persoană, grupați-le după ce permit cuiva să facă, și puneți motivul deasupra.

Asta are o consecință practică. Dacă changelog-ul e sursa, trebuie să fie date structurate, nu o pagină întreținută manual. O intrare are nevoie de un tip, o dată, o versiune, și un mod de a spune pentru cine e. Odată ce are asta, pagina publică, widget-ul in-app și fluxul RSS sau JSON sunt trei randări ale unui singur lucru, și nimeni nu rescrie nimic pe drumul către un client. Un e-mail de release notes poate cita aceeași intrare, din orice unealtă vă trimite e-mailurile. Automatizarea changelog-ului e despre care dintre acești pași ar trebui să-l dețină o mașină. Ăsta e tot argumentul pentru a trata un changelog ca un flux în loc de o pagină. E de asemenea, cu deplină transparență, ce construim noi, deci citiți asta ca un interes, nu ca un sondaj imparțial.

Dacă aveți timp doar pentru unul

Scrieți changelog-ul. E mai ieftin pe intrare, e util în ziua în care îl scrieți, și release notes pot fi derivate din el mai târziu. Reciproca nu e adevărată: nu puteți reconstrui un an de schimbări din douăsprezece e-mailuri de anunț, și oamenii vă vor cere asta.

Păstrați-l într-un format fix ca derivarea să rămână posibilă. Pagina noastră exemple de changelog adună intrări de la echipe care fac asta bine, iar șablonul de release notes e forma pe care o folosim când transformăm un set de intrări în ceva ce merită trimis.

O notă despre denumire

Nimic din asta nu e standardizat, și veți găsi “release notes” folosit pentru o listă continuă și “changelog” folosit pentru un anunț trimestrial. Nu merită să vă certați pe cuvinte. Decideți care dintre cele două treburi îl face fiecare dintre artefactele voastre, numiți-l cum îl numește deja echipa voastră, și asigurați-vă că niciunul nu face ambele în tăcere.

Pe ce suprafață ajunge rezultatul e o decizie separată, acoperită în cum construiești o pagină de changelog.

FAQ

E un changelog la fel cu release notes? Nu. Un changelog e registrul complet, citit de cei care caută ceva; release notes sunt anunțul selectat, citit de cei care decid dacă îi interesează. Aceeași schimbare apare în ambele, formulată diferit pentru fiecare cititor.

Pot fi generate release notes dintr-un changelog? Da, și asta e direcția corectă. Selectați intrările care ar interesa o persoană, grupați-le după rezultat, rescrieți titlul. Reciproca, reconstruirea unui changelog din anunțuri, pierde tot ce au omis anunțurile.

Unde ar trebui să trăiască un changelog? Undeva permanent și legabil unde cititorul poate ajunge fără un repository: o pagină /changelog, un site de documentație, sau un flux randat în mai multe locuri. Un CHANGELOG.md singur ajunge la contribuitori, nu la clienți.

Ar trebui un changelog să includă schimbări interne? Da, la sfârșit, câte o linie fiecare. Changelog-ul e registrul complet. Release notes le pot păstra și ele, într-o scurtă secțiune finală, atâta timp cât schimbările pe care un cititor le va observa vin primele.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Exemple de changelog, Șablon note de lansare