Cine scrie changelog-ul, și cine ar trebui

Întrebați o echipă cine scrie changelog-ul și răspunsul sincer e de obicei “oricine își amintește”, ceea ce e același mod de eșec pe care impunerea unei intrări de changelog în CI există să-l repare la nivel mecanic. Dar a forța existența unei intrări nu decide cine e calificată să scrie una bună, iar echipele care sar peste acea întrebare tind să recurgă implicit la oricine e cel mai ușor de obligat, de obicei autoarea PR-ului, fără să verifice dacă asta e într-adevăr persoana care poate să o scrie bine.

De ce autoarea PR-ului nu e automat cea mai bună scriitoare de changelog?

Pentru că cunoaște implementarea, nu neapărat impactul, și acestea sunt tipuri diferite de cunoaștere. Unde se opresc conventional commits acoperă acest decalaj de la partea mesajului de commit: fix(auth): reject expired refresh tokens e corect și nu spune nimic unei cliente, iar cea care a scris acea remediere e adesea persoana cel mai puțin echipată să o traducă, pentru că s-a gândit în termenii erorii ore în șir și a pierdut perspectiva exterioară asupra a ceea ce a experimentat de fapt o utilizatoare. Ăsta e același motiv pentru care redactoarele tehnice există ca profesie: traducerea implementării în impact e o abilitate distinctă de a fi construit lucrul respectiv, și cere exercițiu indiferent cât de bună e dezvoltatoarea la codul în sine.

Asta înseamnă că produsul sau suportul ar trebui să scrie fiecare intrare în schimb?

Nu, pentru că au decalajul opus: știu ce contează pentru utilizatoare dar nu întotdeauna ce s-a lansat de fapt, ceea ce produce intrări citibile dar ocazional greșite ca domeniu, o afirmație “acum suportă X” pentru o funcționalitate încă în spatele unui flag, sau o remediere descrisă ca completă când acoperă doar unul din trei cazuri. Modul de eșec al intrărilor scrise de dezvoltatoare e ilizibil-dar-precis; modul de eșec al intrărilor scrise de PM-uri e citibil-dar-neverificat. Niciun rol nu deține ambele jumătăți din ce are nevoie o intrare bună.

Cum arată de fapt un model de responsabilitate care funcționează?

O ciornă de la oricine e cel mai aproape de schimbare, revizuită de oricine e cel mai aproape de utilizatoare, cu o persoană numită responsabilă de formularea finală în loc ca toată lumea să presupună că altcineva va prinde problemele. Ciorna trebuie să existe și să fie precisă mai mult decât trebuie să fie bună; o propoziție brută scrisă de o dezvoltatoare care spune corect ce s-a schimbat e un punct de plecare mai bun decât una lustruită dar neverificată, pentru că rescrierea pentru claritate e mai ușoară decât rescrierea pentru corectitudine. Pasul de revizuire e unde un PM sau lider de suport citește ciorna și pune singura întrebare care prinde decalajul de lizibilitate: aș înțelege asta dacă n-aș fi văzut codul.

Ar trebui să fie mereu aceeași persoană responsabilă, sau rotește?

Numită și stabilă bate rotativă, cel puțin pentru aprobarea finală. O responsabilă rotativă înseamnă că fiecare intrare e revizuită de cineva care re-derivă convențiile echipei de la zero, ceea ce e exact cum vocea deviază de la o intrare la alta și o cititoare începe să observe că changelog-ul a fost scris de un comitet. O singură persoană, sau un grup stabil foarte mic, acumulează judecățile în timp, când să spună “îmbunătățit” versus să numească cifra specifică, când o remediere are nevoie de propria intrare versus să se plieze într-un lot, iar acea judecată valorează mai mult decât distribuirea muncii în mod egal.

Ciornă (dezvoltatoare, din PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revizuită (responsabila changelog-ului, verificată cu PR-ul real):
"Corectat: exporturile sortate după dată puteau returna
rezultate în afara ordinii dincolo de prima pagină.
Acum consistent pe toate paginile."

O echipă mică are nevoie de atât de mult proces pentru o linie de text?

Nu rolurile ca persoane separate, dar cei doi pași încă contează chiar și solo. O echipă de o persoană e atât dezvoltatoarea, cât și reviewer-ul, iar disciplina care supraviețuiește la acea scară e să faci revizuirea ca o trecere mentală separată, nu să sari direct de la scrierea remedierii la publicarea unei descrieri a ei în aceeași respirație. Capcana la scară mică e sărirea completă peste a doua trecere, nu lipsa unei a doua persoane, pentru că nimeni din exterior n-o forțează, iar decalajul de precizie pe care acea trecere există să-l prindă nu dispare doar pentru că aceeași persoană ar putea teoretic să-și observe propriul punct orb.

Ce se întâmplă când nimeni nu e responsabil de intrarea finală?

Changelog-ul se degradează inegal în loc să eșueze complet, ceea ce e mai rău pentru că nimeni nu observă până când o cititoare nu semnalează. Unele intrări rămân clare pentru că cui i-a scris i-a păsat; altele devin vagi, “diverse îmbunătățiri și corectări de erori”, pentru că cui le-a scris mergea repede și nimeni n-a prins asta înainte de publicare. Constrângerile de format ale Keep a Changelog prind deriva structurală, date lipsă, categorii greșite, dar nimic dintr-un șablon nu prinde o intrare vagă care e tehnic bine formatată, ceea ce e exact decalajul pe care o responsabilă numită e acolo să-l închidă.

FAQ

Ar trebui responsabila changelog-ului să fie un rol de inginerie sau de produs? Oricare poate funcționa dacă persoana are atât fluență tehnică pentru a verifica domeniul, cât și suficientă distanță de implementare pentru a scrie pentru o cititoare din exterior; titlul contează mai puțin decât dacă poate face ambele jumătăți, sau știe pe cine să întrebe pentru jumătatea pe care n-o poate face.

Un program rotativ de tip gardă e vreodată potrivit pentru responsabilitatea changelog-ului? Pentru volum, uneori, dacă echipa e prea mică pentru ca o persoană să revizuiască totul; pentru voce și judecată, nu, pentru că asta e exact ce erodează rotația. O rotație care împarte sarcina de redactare menținând o reviewer stabilă obține beneficiul fără deriva.

Care e cel mai rapid semn că ceva nu e în regulă cu configurația actuală de responsabilitate? Intrări care sunt precise dar ilizibile, sau citibile dar greșite ca domeniu, într-un tipar care urmărește cine le-a scris. Dacă calitatea corelează cu autoarea în loc să rămână consistentă, responsabilitatea e decalajul, nu abilitatea de a scrie.

Automatizarea reduce cât de mult contează responsabilitatea? Reduce câtă scriere e necesară, nu câtă judecată e necesară. Automatizarea changelog-ului acoperă ce poate genera în siguranță un pipeline, formatare, publicare, cross-posting; formularea, gruparea și ce contează ca demn de menționat rămân decizii umane indiferent cât de mult din pipeline e automatizat.

Ce se întâmplă dacă autoarea PR-ului și reviewer-ul nu sunt de acord cu formularea? Decide reviewer-ul, pentru că întrebarea la care răspunde, ar înțelege asta o cititoare din exterior, e exact cea pentru care există rolul. Asta nu face lectura dezvoltatoarei fără valoare: dacă dezacordul e despre precizie, nu despre formulare, reviewer-ul cedează, pentru că domeniul schimbării e jumătatea pe care autoarea trebuie s-o nimerească. Separarea celor două tipuri de dezacord, formulare versus precizie, oprește majoritatea acestora să devină o încleștare.

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

Pe changeloop: Comparație instrumente changelog, Generator de changelog