Release notes de software: ce sunt și ce includ

Release notes de software sunt documentul care însoțește o versiune a unui program și îi spune cititorului ce s-a schimbat în ea, pe cine afectează schimbarea și ce, dacă e cazul, trebuie să facă. Se scriu o dată pe lansare și le citesc oamenii care hotărăsc dacă fac upgrade, cei care verifică dacă o problemă pe care au întâlnit-o e rezolvată și cei care oferă suport pentru produs. Cele bune sunt scurte, specifice versiunii și sincere în privința a tot ce se strică.

Ce sunt release notes de software?

Sunt un rezumat datat și versionat al unei singure lansări. O notă de lansare răspunde la trei întrebări pentru un cititor care n-a fost în încăpere: ce e diferit, mă afectează și trebuie să fac ceva. Istoricul complet al proiectului e changelog-ul, iar jurnalul de commit-uri e pentru cei care au scris codul.

Aceleași fapte pot apărea într-o intrare de changelog și în release notes. Diferența e selecția și publicul: changelog-ul listează fiecare schimbare notabilă, iar release notes încep cu cele pe care le va observa un cititor și le explică. Changelog vs release notes trasează linia în detaliu.

Ce ar trebui să includă release notes de software?

Includeți versiunea și data, un rezumat de un paragraf, apoi schimbările grupate după ce poate face cititorul cu ele. Pentru fiecare schimbare, spuneți ce e diferit în termenii cititorului, cine e afectat și dacă e nevoie de o acțiune.

Un set complet are aceste părți:

1. Numărul versiunii și data lansării. Folosiți formatul tag-urilor voastre, ca un cititor să poată potrivi notele cu un build.
2. Un rezumat. Două-trei propoziții: la ce folosește lansarea și dacă upgrade-ul cere ceva de la cititor.
3. Funcționalități noi și îmbunătățiri. Ce poate face acum cititorul, nu ce conține acum codul.
4. Corecții. Simptomul care a dispărut și versiunea în care a apărut.
5. Schimbări incompatibile și deprecieri. Ce nu mai merge, de când și ce să folosească în loc. Puneți-le primele, dacă există.
6. Probleme cunoscute. Orice ați livrat și știți că nu e în regulă, cu o soluție ocolitoare dacă există.
7. Cerințe și pași de upgrade. Platforme suportate, versiuni minime, comenzi de migrare.

Lăsați afară refactorizările, actualizările de dependențe fără efect vizibil și tichetele interne. Dacă un cititor nu poate observa schimbarea, locul ei e în istoricul git. Cum se scriu release notes tratează formularea și ordinea.

Cum arată o notă de lansare de software?

Iată una scurtă pentru un instrument imaginar de linie de comandă. Forma contează mai mult decât conținutul.

## 2.4.0 (2026-10-08)

Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.

### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
  with "unknown key". Rename the key; nothing else changes.

### New
- Exports stream to disk, so files over 100 MB no longer time out.

### Fixed
- Search works again for queries containing a hyphen. Broken
  since 2.3.0.

### Known issues
- Windows paths longer than 260 characters still fail. Use a
  shorter output directory for now.

Schimbarea incompatibilă e prima, cu textul exact al erorii pe care o va vedea cititorul, pentru că oamenii caută mesajele de eroare. Corecția numește versiunea în care s-a stricat, ca un cititor să o poată potrivi cu momentul în care a început problema lui. Problema cunoscută are o soluție ocolitoare, ceea ce e mai bine decât tăcerea. Exemple de release notes are mai multe formulări pentru fiecare tip de intrare.

Cum diferă release notes de software pentru fiecare public?

Păstrați o singură sursă de adevăr și scrieți câte o versiune pentru fiecare public. Faptele nu se schimbă, dar nivelul de detaliu da. Clienții vor beneficiul într-o linie, administratorii vor cerințele și problemele cunoscute, dezvoltatorii vor nume și versiuni exacte, iar suportul vrea să știe ce să spună când sosește un tichet.

La produsele cu API, versiunea pentru dezvoltatori cere cea mai multă grijă, pentru că o schimbare care pentru voi e o mică corecție poate fi o pană pentru cel care apelează. Changelog API și schimbările incompatibile tratează acest public. Pentru versiunea internă, notele de lansare interne descriu ce au nevoie suportul și vânzările și clienții nu.

Unde ar trebui publicate release notes de software?

Publicați-le acolo unde se află deja cititorul când pune întrebarea. Pentru o aplicație mobilă, asta e pagina din magazin, unde platforma oferă un câmp de release notes pentru fiecare versiune; Apple documentează cum se furnizează release notes pentru build-uri. Pentru un produs web, e o pagină de changelog legată din aplicație. Pentru o bibliotecă, e pagina de release și un fișier din repository, așa cum e descris în GitHub release notes.

Dați fiecărei versiuni o adresă stabilă, ca suportul să poată trimite linkuri la ea, și păstrați versiunile vechi. Un cititor aflat pe versiunea 2.2 are nevoie și de notele pentru 2.3 și 2.4. Dacă vreți o structură de pornire, șablonul de release notes vă dă titlurile de copiat.

Cât de lungi ar trebui să fie release notes?

Cât cere schimbarea și nu mai mult. O lansare de patch poate avea trei linii. O lansare majoră cu migrare are nevoie de o pagină, probabil și de un ghid de migrare separat, legat din note. Testul e dacă un cititor care parcurge doar primul ecran află dacă lansarea îl afectează. Dacă nu, mutați rezumatul mai sus și tăiați restul. Cele mai bune practici pentru release notes enumeră ce rezistă și ce e doar obicei.

FAQ

Ce sunt release notes de software? Sunt un rezumat versionat al schimbărilor dintr-o lansare a unui program, scris pentru cei care îl folosesc sau îl susțin. Acoperă funcționalități noi, corecții, schimbări incompatibile și tot ce trebuie să facă cititorul.

Care e diferența dintre release notes și un changelog? Un changelog e registrul complet al schimbărilor notabile. Release notes sunt un mesaj despre o singură lansare, selectat și rescris pentru cititorii care decid dacă fac upgrade. Multe echipe publică intrarea de changelog a unei versiuni drept release notes ale ei.

Cine scrie release notes de software? De obicei product managerul, un technical writer sau inginerul care a livrat schimbarea, cu cineva care verifică tonul. Cele mai bune rezultate apar când persoana cea mai aproape de schimbare scrie ciorna, iar a doua o editează pentru cititor.

Au nevoie lansările minore de release notes? Da, scurte. Chiar și o lansare de patch ar trebui să spună ce s-a corectat și dacă cititorul trebuie să acționeze. O notă de o linie e mai bună decât niciuna, pentru că „corecții de erori și îmbunătățiri” nu-i spune cititorului nimic.

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

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