Șablon note de lansare

Șablonul

Tot ce e între paranteze drepte este un placeholder. Tot restul merită păstrat, inclusiv ordinea: utilizatorii caută lucrul care îi afectează, deci modificările incompatibile vin primele, iar munca internă nu apare deloc.

## [Produs] [versiune] - [dată]

[O propoziție care spune la ce servește această lansare. Omite pentru
lansări de rutină.]

### Modificări incompatibile
- [Ce s-a stricat, ce să schimbi și până când. Fă link la pașii de
  migrare.]

### Nou
- [Capacitate, descrisă ca un rezultat. „Fixează un filtru și
  refolosește-l”, nu „adăugat modelul SavedView”.]

### Îmbunătățit
- [Ce este mai rapid, mai clar sau mai fiabil, și aproximativ cu cât.]

### Corectat
- [Simptomul pe care l-a văzut utilizatorul, nu cauza din cod.]

Dacă o secțiune este goală, șterge titlul. O secțiune Corectat goală se citește de parcă nimic nu a fost corectat, iar un titlu fără nimic sub el îi face pe cititori să creadă că pagina nu s-a încărcat.

Același șablon, completat

Așa arată cu conținut real. Observă că nicio intrare nu menționează un fișier, un branch, un număr de tichet sau o persoană, iar modificarea incompatibilă începe cu acțiunea pe care cititorul trebuie să o ia.

## Acme API 4.2 - 20 august 2026

Paginarea este acum bazată pe cursor pe toate endpointurile de listă.

### Modificări incompatibile
- `?page=` a fost eliminat pe toate endpointurile de listă. Folosește
  valoarea `nextCursor` din răspunsul anterior. `?page=` returnează
  400 după 1 octombrie 2026. Pași de migrare:
  acme.example/docs/pagination

### Nou
- Vizualizări salvate în inbox. Fixează un filtru o dată și
  refolosește-l din bara laterală.
- Webhook-urile pot fi acum limitate la un singur proiect.

### Îmbunătățit
- Endpointurile de listă răspund de aproximativ patru ori mai
  repede pe conturi mari.
- Sarcina de export raportează acum progresul în loc să pară
  blocată.

### Corectat
- Membrii invitați nu mai văd un panou gol înainte de prima
  autentificare.
- Marcajele de timp din exporturi respectă acum fusul orar al
  contului.

Ce intră în fiecare secțiune

Modificări incompatibile

Singura secțiune cu un termen limită în ea. Spune ce încetează să funcționeze, ce să faci în schimb și data la care încetează. Dacă nu ai decis încă data, nu publica încă secțiunea: o modificare incompatibilă fără dată este citită ca urgentă, iar un flux de falsă urgență este modul în care oamenii învață să-ți ignore notele de lansare.

Nou

Descrie rezultatul, nu obiectul pe care l-ai construit. Testul este dacă linia mai are sens pentru cineva care nu a văzut niciodată codul tău. „Vizualizări salvate în inbox” trece. „Adăugat modelul SavedView și migrarea lui” nu trece.

Îmbunătățit

Cuantifică unde poți sincer. „Mai rapid” valorează aproape nimic, iar cititorii îl reduc; „de aproximativ patru ori mai rapid pe conturi mari” merită citit și stabilește o așteptare pentru care poți fi tras la răspundere. Dacă nu poți măsura, spune ce e mai bine într-un mod falsificabil.

Corectat

Scrie simptomul, nu cauza. Utilizatorii caută în aceste note lucrul care li s-a întâmplat, deci „membrii invitați ajungeau pe un panou gol” este găsibil, iar „corectată o cursă de date în cache-ul de apartenență” nu este.

Variante

Cele patru secțiuni sunt valabile pentru majoritatea lansărilor. Trei cazuri necesită o schimbare:

• Lansări de aplicații mobile. Magazinele de aplicații afișează un câmp scurt de noutăți, deci începe cu o propoziție pe care o persoană o poate citi în lista magazinului, apoi fă link către notele complete. Recenzia magazinului poate întârzia și un build cu zile întregi, deci datează notele după data lansării, nu după data îmbinării.
• Lansări de API. Versionează notele la fel cum versionezi API-ul, și pune fereastra de deprecare chiar în note, nu doar în documentație. Un consumator de API citește notele exact pentru a afla cât timp mai are.
• Instrumente interne sau administrative. Elimină secțiunea Îmbunătățit și îmbin-o cu Corectat. Utilizatorilor interni le pasă dacă fluxul lor de lucru s-a schimbat, iar o secțiune Îmbunătățit lungă îngroapă asta.

Patru reguli care le mențin lizibile

1. Scrie pentru cineva care nu-ți cunoaște codul. Fără nume de fișiere, fără nume de branch-uri, fără id-uri de tichete, fără nume de servicii, fără nume de cod interne.
2. Omite orice fără efect vizibil pentru utilizator. Actualizările de dependențe, refactorizările, modificările CI și corectările de erori de tipar aparțin istoricului de commit-uri, nu notelor de lansare. Cel mai comun mod în care mor notele de lansare este umplerea lor cu muncă pe care nimeni din afara echipei nu o poate vedea.
3. O intrare, o modificare. Dacă o linie are nevoie de cuvântul „și” de două ori, probabil sunt două intrări.
4. Publică într-un ritm pe care oamenii se pot baza, chiar dacă ritmul este „ori de câte ori lansăm”. Notele care apar de patru ori într-o săptămână și apoi deloc timp de două luni sunt tratate ca zgomot.

Formatul notelor de lansare: părțile, în ordine

Formatul contează mai puțin decât ordinea. Indiferent ce stil de titlu folosești, un cititor care parcurge note de lansare vrea aceleași patru lucruri în aceeași secvență, iar fiecare format popular de note de lansare este o variație a asta.

1. Un titlu care spune ce s-a schimbat pentru cititor, nu numărul versiunii. Versiunea merge pe o linie mai mică dedesubt, cu data în format ISO (2026-08-29) ca să se citească la fel în orice locale.
2. Modificările incompatibile și orice are un termen limită, primele, chiar dacă sunt mici. Dacă un cititor se oprește după un paragraf, acesta este paragraful de care avea nevoie.
3. Ce e nou, un element pe paragraf, cu rezultatul în prima propoziție și acțiunea necesară, inclusiv „nu e necesară nicio acțiune”, menționată de fiecare dată.
4. Corecturi și îmbunătățiri, apoi tot restul ca o listă cu o linie în partea de jos. Actualizările de dependențe și modificările interne rămân, pentru că singura persoană care le caută chiar are nevoie de ele.

În Markdown asta e un titlu H2, o linie estompată de versiune și dată, apoi secțiuni H3 pentru Incompatibil, Nou, Îmbunătățit și Corectat. Într-un e-mail e aceeași ordine cu titlul ca subiect. Într-un widget de changelog e titlul și primul paragraf, cu restul în spatele unui link. Șablonul de mai sus este acea formă scrisă în întregime.

Pentru scrierea în sine, nu forma, vezi cum să scrii note de lansare pe care oamenii chiar le citesc și bune practici de note de lansare care merită păstrate pe blog.

Întrebări frecvente

Cât de lungi ar trebui să fie notele de lansare?

Cât de lungi cer modificările care afectează utilizatorii, și nu mai mult. O lansare cu o corectare de bug primește două linii. Umflarea unei lansări mici ca să pară substanțială îi antrenează pe oameni să treacă cu vederea pe cele mari.

Care e diferența dintre notele de lansare și un changelog?

În practică, termenii sunt folosiți interschimbabil. Acolo unde echipele îi disting, notele de lansare descriu o singură lansare și sunt scrise pentru utilizatori, în timp ce un changelog este lista continuă a fiecărei lansări în timp. Acest șablon acoperă o lansare; un changelog este ce obții stivuindu-le de la cea mai nouă.

Ar trebui notele de lansare să aibă un număr de versiune?

Doar dacă utilizatorii tăi îl pot vedea. Numerele de versiune sunt utile pentru API-uri, biblioteci și software instalat, unde un cititor trebuie să știe pe ce versiune se află. Pentru o aplicație web implementată continuu, data este mai utilă, pentru că asta poate potrivi utilizatorul cu ce a experimentat.

Cine ar trebui să le scrie?

Oricine știe ce s-a schimbat, ceea ce de obicei înseamnă inginerul care a îmbinat modificarea, editat de oricine deține vocea. Modul de eșec al predării lor complet cuiva din afara muncii sunt notele care descriu tichetul în loc de modificare.