Tag-uri git, lansări și changelog-ul tău

Un tag git, o lansare și o intrare de changelog sunt trei înregistrări diferite ale aceluiași eveniment, iar confundarea lor face un changelog să devieze în tăcere de la ce s-a lansat de fapt. Un tag marchează un commit. O lansare împachetează acel tag cu artefacte și o descriere. O intrare de changelog explică, în termeni pe care o cititoare din afara depozitului îi poate folosi, ce s-a schimbat. De obicei se întâmplă apropiate în timp, și tocmai de aceea e ușor să le tratezi ca un singur pas în loc de trei, și tocmai de aceea diferența devine vizibilă abia luni mai târziu, când cineva întreabă „ce s-a lansat în v2.4” și răspunsul onest necesită săpat real.

Care e diferența reală dintre cele trei?

Un tag e cel mai mecanic dintre cele trei: git tag v2.4.0 și gata, fără nicio cerință ca ceva să explice ce conține. O lansare adaugă o descriere și, de obicei, artefacte descărcabile, iar publicul ei rămâne dezvoltatoare care știu ce e o pagină de lansare. O intrare de changelog e singura din cele trei scrisă pentru o cititoare care poate nu deschide niciodată depozitul, de aceea e cea care are nevoie de cea mai multă atenție editorială și cea mai probabil să fie sărită sub presiunea termenelor.

Are nevoie fiecare tag git de o intrare de changelog?

Nu, iar tratarea lor unu la unu e o greșeală comună. Un tag poate marca un jalon intern, un release candidate, sau o remediere urgentă care nu ajunge niciodată la majoritatea utilizatoarelor; niciunul dintre ele nu are neapărat nevoie de o intrare publică. Testul e același care decide dacă ceva aparține deloc unui changelog: dacă o utilizatoare sau o apelantă ar observa sau i-ar păsa. Majoritatea tag-urilor trec acest test. Unele, cum ar fi un tag creat doar pentru a declanșa un pipeline CI, niciodată.

Are nevoie fiecare intrare de changelog de propriul tag?

Nu întotdeauna, și aici diverg echipele care implementează continuu de echipele care lansează pachete versionate. Un produs SaaS care implementează de mai multe ori pe zi poate grupa mai multe implementări sub o intrare de changelog datată fără un tag 1:1 pe implementare; o bibliotecă publicată într-un registru de pachete are de obicei nevoie de un tag pe versiune publicată. Modulele Go și Swift Package Manager rezolvă versiunile direct din tag-uri; pe npm sau PyPI registrul deține versiunea publicată, iar tag-ul e felul în care oricine leagă acea versiune înapoi de sursa ei. Un repository cu mai multe pachete versionate independent trebuie să decidă asta pe pachet, nu o dată pentru tot repo-ul; changelog-uri de monorepo acoperă cum ar trebui să urmeze prefixele de tag-uri și scope-ul changelog-ului granițele pachetelor, nu ale folderelor. Semantic versioning și changelog-ul tău acoperă cum ar trebui să se mapeze numărul de versiune însuși la categoriile de changelog; tag-urile sunt mecanismul care face un număr de versiune verificabil față de codul real.

Cum ar trebui să se lege o descriere de lansare de intrarea de changelog?

Pot fi același text, dar doar dacă publicul ambelor e chiar același, ceea ce e mai rar decât pare. O pagină de lansare pe o gazdă de cod e citită aproape exclusiv de dezvoltatoare; dacă un produs are și utilizatoare non-tehnice care citesc changelog-ul, duplicarea descrierii de lansare cuvânt cu cuvânt trimite termeni interni și o formulare centrată pe cod către o cititoare care avea nevoie de versiunea în limbaj simplu. Modelul cel mai curat: scrie intrarea de changelog ca artefactul principal, orientat spre cititoare, și lasă descrierea de lansare fie să lege către ea, fie să păstreze un rezumat mai scurt și mai tehnic pentru publicul deja confortabil acolo.

# Lansare v2.4.0 (GitHub, pentru dezvoltatoare)
Ridică pipeline-ul de rapoarte la noul motor de agregare. Vezi
changelog pentru rezumatul orientat spre client:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, orientat spre client)
### Added
- Rapoartele se încarcă acum în mai puțin de o secundă, chiar și
  pentru conturi cu peste un milion de rânduri.

Aceeași lansare, două documente, fiecare cu propria formulare pentru propria cititoare.

De unde vine de fapt intrarea de changelog?

Din două puncte de plecare, iar majoritatea pipeline-urilor reale sunt un amestec al ambelor. Poate fi generată din mesajele de commit în momentul tag-ului, ceea ce e rapid și nu ratează niciodată un pull request îmbinat; de la conventional commits la changelog acoperă acel pipeline integral. Sau poate fi scrisă manual, complet separat de tag, sincronizată cu momentul în care o funcționalitate e considerată gata, nu cu momentul în care codul e îmbinat. Intrările generate sunt consistente dar moștenesc fiecare mesaj de commit vag; intrările scrise manual sunt mai clare dar au nevoie de cineva care să le scrie de fapt. Majoritatea echipelor care automatizează tot păstrează o trecere ușoară de editare pe textul generat înainte să devină intrarea publică, aceeași disciplină pe care o recomandă Keep a Changelog, în practică, indiferent de unde a venit inițial textul brut.

Ce se strică atunci când cele trei ies din sincronizare?

Încrederea în ce a verificat prima cititoarea. Un tag care există fără o intrare de changelog corespunzătoare pare, din partea cititoarei de changelog, că săptămâna aceea nu s-a întâmplat nimic. O intrare de changelog fără un tag sau lansare corespunzătoare face imposibil ca cineva care depanează o problemă de producție să facă checkout la exact codul care era live când a fost publicată o intrare. Soluția nu e automatizare perfectă, e o singură sursă de adevăr pentru corespondență: un loc, chiar dacă e doar lista de verificare proprie a procesului de lansare, care spune că o schimbare lansabilă primește toate trei, în același commit sau pull request care o introduce.

FAQ

Ar trebui generate automat intrările de changelog din tag-uri git? Pot fi un punct de plecare, dar un tag singur nu poartă nicio descriere orientată spre cititoare, doar un interval de commit-uri. Generarea automatizată trebuie să citească mesajele de commit din acel interval, nu doar existența tag-ului, pentru a produce ceva utilizabil.

Ce se întâmplă dacă nu etichetăm fiecare lansare? Atunci intrarea de changelog devine înregistrarea principală, și ar trebui totuși să poarte o dată și, dacă produsul are unul, un număr de versiune, ca intrarea să rămână ceva la care o cititoare se poate referi mai târziu chiar și fără un tag corespunzător.

Ar trebui tag-urile de pre-lansare (cum e v2.4.0-rc.1) să aibă intrări de changelog? În general nu. Un release candidate e pentru testare internă sau beta, iar o intrare de changelog pentru el antrenează cititoarele să se aștepte la intrări pentru versiuni care s-ar putea să nu se lanseze niciodată așa cum au fost descrise. Păstrează intrările pentru tag-urile care ajung la disponibilitate generală.

Poate o singură intrare de changelog să acopere mai multe tag-uri git? Da, și adesea ar trebui pentru echipele care etichetează frecvent. Grupează tag-urile înrudite sub o intrare datată care descrie schimbarea netă, în loc să publici o intrare subțire pe tag care fragmentează o funcționalitate pe mai multe citiri.

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

Pe changeloop: Generator de changelog, Documentație pentru dezvoltatori