Ce este un changelog și ce ar trebui să conțină?

Un changelog este înregistrarea datată a ceea ce s-a schimbat într-un produs, scrisă pentru persoanele afectate de schimbare, nu pentru echipa care a lansat-o. Fiecare intrare numește o schimbare, spune când a intrat în vigoare și spune ce trebuie să facă cititoarea în privința ei, ceea ce pentru majoritatea intrărilor înseamnă nimic. Tocmai această ultimă parte separă un changelog de un jurnal de commit-uri: un jurnal de commit-uri este o înregistrare pentru cei care au scris codul, un changelog este o înregistrare pentru cei care îl folosesc.

Ce este un changelog, mai exact?

O listă de intrări datate, cea mai recentă prima, fiecare descrie o singură schimbare în termeni pe care cititoarea îi poate verifica. Nu ce a construit echipa, ci ce e diferit acum. “Refactorizat serviciul de facturare” este un mesaj de commit. “Facturile arată acum taxa ca linie separată” este o intrare de changelog, pentru că îi spune cititoarei ceva ce poate verifica în propriul cont.

Formatul este vechi și deliberat simplu: un titlu pe versiune sau pe zi, o listă scurtă dedesubt, uneori o etichetă de categorie. Keep a Changelog este specificația cea mai citată pentru această formă, și există pentru că majoritatea proiectelor care sar peste o specificație ajung să verse istoricul de commit-uri în loc, ceea ce răspunde la o altă întrebare decât cea cu care a venit cititoarea.

Cele cinci se suprapun în practică, dar nu sunt același document, iar diferența stă în cine îl ține în mână când îl citește. Un changelog e cel construit pentru a fi căutat și linkuit din nou mai târziu, de aceea intrările lui au nevoie mai mult decât celelalte de date și URL-uri stabile.

Ce conține de fapt o intrare de changelog?

Patru lucruri, în această ordine: ce s-a schimbat, exprimat în termenii pe care utilizatoarea sau apelanta i-ar observa; când a intrat în vigoare; din ce categorie face parte (added, fixed, changed, removed sunt cele patru comune); și, când contează, ce trebuie să facă cititoarea în privința asta. Un link către mai multe detalii e binevenit. Un paragraf de justificare internă nu e, pentru că cititoarea nu a întrebat de ce, a întrebat ce.

## 2026-09-07

### Added
- Facturile arată acum taxa ca linie separată, în moneda contului
  clientului.

### Fixed
- Exportul unui raport ca CSV nu mai pierde ultima linie când raportul
  depășește 10.000 de linii.

Această formă se scalează de la o actualizare de două linii la o sută de intrări într-o lansare fără să schimbe structura, și acesta e testul real al faptului că un format funcționează: se citește la fel într-o săptămână încărcată ca într-una liniștită.

Cine scrie un changelog, și când?

Cine a făcut schimbarea, în momentul lansării, nu o redactoare tehnică care îl reconstruiește din tichete o săptămână mai târziu. Cine a atins codul știe ce s-a schimbat cu adevărat pentru utilizatoare; un rezumat scris ulterior tinde să descrie tichetul în loc de ce s-a lansat efectiv, și de obicei e mai larg sau mai îngust decât domeniul real. Unele echipe adaugă un pas de revizuire înainte ca o intrare să devină publică, mai ales pentru a prinde limbajul intern care s-a strecurat, iar acea revizuire trebuie să fie suficient de rapidă încât intrarea să apară în aceeași zi.

Unde ar trebui să stea un changelog?

Pe pagina lui proprie, la un URL stabil, distribuit ca feed. Îngropat într-un meniu de setări sau o etichetă de lansare pe o gazdă de cod, ajunge doar la cei care știau deja unde să caute. O pagină publică poate fi linkuită dintr-un tichet de suport, citată într-o recenzie, sau abonată. Feed-ul contează la fel de mult ca pagina: o cititoare care verifică changelog-ul unui produs o dată pe lună e rară, una care se abonează la el nu e, și doar feed-ul deservește al doilea grup.

Cum diferă de notele de lansare?

Cele două sunt confundate constant, și suficient de diferite încât amestecarea lor produce un document care nu servește bine niciuna dintre cele două cititoare. Changelog versus note de lansare parcurge distincția integral; pe scurt, un changelog este înregistrarea completă și cronologică, iar notele de lansare sunt un subset curatoriat, scris ca o actualizare să pară că merită avută. Un produs are de obicei nevoie de amândouă, adresate unor momente diferite din ziua cititoarei.

Ce face un changelog demn de citit?

Specificitate și onestitate despre propria întindere. “Diverse remedieri de erori” e propoziția care învață o cititoare să nu mai deschidă pagina, pentru că nu promite nimic ce poate verifica. O intrare care numește comportamentul exact care s-a schimbat, chiar și pentru o remediere mică, este cea care ține un abonament în viață. Această disciplină se aplică și la ce se omite: un changelog care anunță doar reușite și niciodată o remediere pentru ceva ce era stricat se citește ca marketing deghizat în changelog, și cititoarele observă asta.

Disciplina de versionare contează și ea. Semantic versioning și changelog-ul tău arată cum ar trebui să se potrivească numărul de versiune și intrarea, ca o cititoare care parcurge istoricul versiunilor să primească același semnal de două ori în loc de două semnale diferite.

Cum sunt generate changelog-urile?

În două moduri, și majoritatea configurațiilor reale sunt un amestec. Generarea automatizată citește mesajele de commit, de obicei în format Conventional Commits, și le transformă în intrări fără ca cineva să atingă rezultatul; de la conventional commits la changelog acoperă acel pipeline. Generarea curatoriată înseamnă că cineva scrie sau editează fiecare intrare de mână. Rezultatul automatizat e mai rapid și nu ratează niciodată un pull request îmbinat, dar moștenește fiecare mesaj de commit vag cuvânt cu cuvânt, așa că majoritatea echipelor care automatizează păstrează totuși un pas ușor de editare înainte de publicare, în loc să arate rezultatul brut.

FAQ

Are nevoie orice produs de un changelog? Orice produs cu utilizatoare afectate de schimbare are nevoie de unul, fie că e o aplicație SaaS, un instrument intern, sau un API public. Forma se adaptează (un changelog de API se citește diferit de cel al unei aplicații pentru consumatori), nevoia nu.

Ce este un changelog în termeni software? Aceeași definiție ca mai sus: o listă datată și cronologică a ceea ce s-a schimbat în software, scrisă pentru cei care îl folosesc, nu pentru cei care l-au construit.

Poate fi generat un changelog automat din commit-uri? Da, și multe echipe fac exact asta, de obicei din mesaje în format Conventional Commits. Compromisul e că o intrare generată e la fel de clară ca mesajul de commit din care provine, așa că o trecere de revizuire înainte de publicare prinde intrările care trebuie reformulate.

Este un changelog același lucru cu un istoric de versiuni? Suficient de apropiat încât termenii sunt folosiți interschimbabil. Un istoric de versiuni e uneori doar o listă de numere de versiune și date fără descriere; un changelog include mereu ce s-a schimbat.

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, Documentație pentru dezvoltatori