Release notes pentru corecții de erori: cum le scrii bine

Release notes bune pentru corecții de erori descriu ce a văzut utilizatorul mergând prost, nu ce a greșit codul. Fiecare intrare spune cine a fost afectat, de când, dacă remedierea e completă și dacă cititorul trebuie să facă ceva, chiar dacă e doar „nu e necesară nicio acțiune”.

Majoritatea echipelor copiază o linie din mesajul de commit. Tabelul arată șase rescrieri, iar secțiunile de după explică regulile.

Cum scrii o intrare despre o corecție în release notes?

Începeți cu simptomul pe limba utilizatorului, apoi cine a fost afectat și de când, apoi starea remedierii, apoi acțiunea. De obicei ajung una sau două propoziții. Cauza din cod aparține pull request-ului, unde o va căuta un inginer.

Un cititor caută un singur lucru: „am fost eu?” Patru părți acoperă aproape orice intrare:

1. Simptomul. Ce a apărut pe ecran, în răspunsul API sau pe factură. Citați textul erorii dacă a existat una, pentru că oamenii îl caută.
2. Sfera. Ce plan, platformă, versiune de API sau formă a datelor. „Conturile cu peste 50.000 de rânduri” se poate verifica. „Unii utilizatori” nu.
3. Intervalul. De la ce versiune sau dată, ca cititorul să poată hotărî dacă rezultatul ciudat de ieri a fost eroarea.
4. Acțiunea. Rulați din nou, resincronizați, actualizați, eliminați o soluție ocolitoare sau nimic.

Dacă utilizatorii și-au construit o soluție ocolitoare, linia de acțiune e locul în care le spuneți că o pot șterge.

Care e diferența dintre o notă de lansare și un changelog?

Un changelog e registrul complet, continuu al schimbărilor. Notele de lansare sunt un mesaj selectat și rescris despre o versiune, pentru oameni care decid dacă le pasă. La corecții, changelog-ul listează fiecare corecție, iar notele o pornesc cu cele pe care un cititor le-ar fi putut observa.

O greșeală de tipar într-un tooltip aparține doar changelog-ului. O cotă de taxă greșită pe facturi aparține ambelor. Împărțirea completă e în changelog vs release notes, iar forma unui set bun de note e în cum se scriu release notes.

Keep a Changelog e o convenție utilă pentru partea de registru. Păstrează „Fixed” pentru corecții și un titlu separat „Security” pentru vulnerabilități, adică aceeași împărțire pe care o face acest articol pentru cititor.

O corecție de eroare este o actualizare?

Da. O corecție schimbă produsul, deci livrarea ei e o actualizare. Conform semantic versioning, o corecție compatibilă înapoi este o versiune patch, de exemplu de la 4.2.0 la 4.2.1.

Dacă cititorul trebuie să facă ceva e o întrebare separată, iar nota ar trebui să-i răspundă. O corecție care schimbă ce observă un apelant corect e aproape o schimbare incompatibilă, iar breaking changes explică unde se află acea linie.

Când primește o corecție propria intrare și când e o corecție minoră?

Dați unei corecții propria intrare când un utilizator ar fi putut observa eroarea, ar fi pierdut timp sau date din cauza ei sau și-ar fi construit o soluție ocolitoare. Grupați-o într-o listă scurtă „Corecții minore” când nimeni din afara echipei n-ar fi putut-o vedea. Judecați după experiența cititorului, oricât de mare ar fi diff-ul.

Fiecare linie din grup ar trebui totuși să spună ceva: „Am corectat unele probleme de interfață” e un înlocuitor.

Cum scrii despre o regresie?

Numiți versiunea care a introdus-o, numiți-o regresie și dați versiunea care o corectează. Cei care au dat de eroare știu deja că s-a stricat, așa că o recunoaștere scurtă și directă îi servește mai bine decât formulările vagi.

De exemplu: „Rezultatele căutării pentru interogări cu cratimă veneau goale în 4.1.0. Asta e corectat în 4.1.1. Dacă v-ați schimbat interogările ca să evitați cratimele, le puteți schimba înapoi.”

„Fiabilitate îmbunătățită a căutării” sună a evaziune pentru oricine a pierdut o după-amiază din cauza erorii. Dacă cauza e încă în curs de confirmare, spuneți-o, așa cum o formulează ghidul despre note de lansare de urgență: nu lăsați niciodată nota să sune mai sigur decât este echipa.

Cum anunți o remediere de securitate?

Declarați gravitatea pe față, numiți versiunile afectate și versiunea care le corectează, spuneți cât de urgentă e actualizarea și includeți identificatorul CVE dacă există unul. Publicați detaliile doar când utilizatorii pot acționa pe baza unei remedieri, urmând un proces de divulgare coordonată când a fost implicat un raportor.

Secvența contează: raportorul vă spune în privat, livrați remedierea, iar nota publică iese când utilizatorii se pot proteja. Procesul CISA de divulgare coordonată a vulnerabilităților coordonează raportarea, analiza și divulgarea publică a vulnerabilităților. Regulile CVE Numbering Authority guvernează cum sunt atribuite și publicate înregistrările CVE, iar pe GitHub un repository security advisory vă lasă să redactați avizul în privat și să cereți un identificator.

O intrare de securitate poartă de obicei patru fapte:

• Ce ar putea face un atacator, într-o propoziție și fără o demonstrație de concept.
• Versiunile afectate și versiunea care o corectează.
• Cât de urgent e: „actualizați astăzi” sau „actualizați la următoarea lansare”.
• Dacă ați văzut exploatare și mulțumiri pentru raportor, dacă a fost de acord.

Lăsați deoparte pașii de exploatare.

Ce ar trebui să spună o notă despre o corecție de pierdere de date?

Spuneți ce date au fost afectate, cum își poate da seama cineva dacă ale lui au fost și dacă pot fi recuperate. „Nu e necesară nicio acțiune” e rareori adevărat aici, iar prima întrebare a cititorului e „mi-au dispărut datele?”

O intrare utilă dă condiția care a pierdut date („ștergerea unui folder în timp ce rula o sincronizare”), intervalul în care a fost posibil, o cale de verificare („deschideți Coșul și căutați elemente datate între 3 și 9 septembrie”) și calea de recuperare. Dacă datele nu pot fi recuperate, spuneți asta. Contactați direct și clienții afectați, pentru că nota de lansare nu ar trebui să fie singurul loc în care cineva află că datele lui au fost atinse.

De ce e „Corecții de erori și îmbunătățiri de performanță” o notă slabă?

Nu-i dă cititorului nimic pe baza căruia să acționeze și ascunde corecțiile pe care cineva le aștepta. Un client care a raportat o blocare nu poate spune dacă e corectată, iar un client cu o soluție ocolitoare nu poate spune dacă s-o elimine.

Există două alternative cinstite. Dacă o versiune nu are nimic ce un cititor ar putea observa, nu publicați note pentru ea și lăsați changelog-ul să țină evidența. Dacă are corecții, listați-le pe limba cititorului:

Înainte:
  Corecții de erori și îmbunătățiri de performanță.

După:
  Corectat: exportul CSV eșua pentru proiectele fără etichete.
  Corectat: modul întunecat ascundea cursorul în caseta de
  comentarii.
  Mai rapid: dashboard-ul se deschide mai repede pentru
  spațiile cu peste 100 de proiecte.

De unde vin notele despre corecții?

Vin din pull request-ul care a corectat eroarea și din raportul care a declanșat-o. Dacă cuvintele raportorului călătoresc împreună cu remedierea, jumătate din simptom e deja scris.

Cerere de funcționalitate sau eroare explică de ce etichetarea corectă a unui raport decide cine îl preia. În Changeloop, o eroare raportată prin widget devine un issue GitHub cu eticheta bug, iar intrarea de changelog e redactată din pull request-ul integrat și ținută până o aprobă un om, înainte să se publice. Șablonul de release notes vă dă aceeași formă de intrare pentru scrierea de mână: simptom, sferă, interval, acțiune.

FAQ

Ce ar trebui să includă release notes pentru corecții de erori? Fiecare intrare ar trebui să numească simptomul văzut de utilizator, cine a fost afectat, de la ce versiune sau dată, dacă remedierea e completă și ce trebuie să facă cititorul, inclusiv „nimic”.

Ar trebui listată în release notes fiecare corecție de eroare? Nu. Listați-le pe cele pe care un utilizator le-ar fi putut observa, din cauza cărora ar fi pierdut timp sau pe care le-ar fi ocolit, și grupați corecțiile cosmetice sau interne într-o listă scurtă „Corecții minore”. Changelog-ul păstrează fiecare corecție pentru oricine trebuie s-o caute.

Cum scrii release notes pentru o eroare pe care ai introdus-o tu? Spuneți că a fost o regresie, numiți versiunea care a introdus-o și pe cea care o corectează și spuneți-le cititorilor dacă pot elimina vreo soluție ocolitoare. O declarație simplă se citește mai bine decât o formulare îndulcită.

Cum verifici release notes pentru un produs pe care îl folosești? Căutați o pagină de changelog sau de release notes legată din meniul de ajutor, din subsol sau din documentația produsului, sau în fila de lansări a repository-ului pentru proiectele open source.

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