Keep a Changelog, implementat cu adevărat

Keep a Changelog e o convenție de o pagină pentru un CHANGELOG.md: cea mai recentă versiune prima, o secțiune pe versiune cu un număr și o dată ISO, intrări grupate sub șase tipuri (Added, Changed, Deprecated, Removed, Fixed, Security), și o secțiune Unreleased sus pentru intrări între versiuni. Majoritatea echipelor care o citează implementează cam două treimi din ea, iar treimea pe care o lasă deoparte e treimea care le protejează utilizatorii.

Olivier Lacan a publicat Keep a Changelog în 2014 cu o propoziție care a îmbătrânit mai bine decât majoritatea prozei despre software: don’t let your friends dump git logs into changelogs. Zece ani mai târziu, e cel mai apropiat lucru de un standard pe care îl are acest colț al software-ului. Merită citită sursa în loc de un rezumat; acest text e despre părțile care sunt lăsate deoparte.

Ce cere Keep a Changelog?

Un CHANGELOG.md la rădăcina repo-ului, cea mai recentă versiune prima, cu o secțiune pe versiune. Fiecare versiune poartă un număr și o dată ISO, și grupează intrările sub șase tipuri:

Plus o secțiune Unreleased sus, ca să fie un loc unde să puneți o intrare în clipa în care e integrată, și ca oricine să poată vedea ce urmează.

Asta e aproape tot. Restul e raționamentul: intrările sunt pentru oameni, o intrare pe schimbare, și fișierul e un document, nu un jurnal.

Ce părți din Keep a Changelog sunt lăsate deoparte?

Secțiunea Unreleased, apoi patru din cele șase tipuri, Security printre ele, în această ordine.

Unreleased dispare prima. E secțiunea fără termen limită, deci e cea a cărei întreținere se oprește prima, și odată dispărută, intrările sunt scrise la momentul lansării din istoricul commit-urilor. Ăsta e exact deversarea de jurnal git împotriva căreia specificația avertizează încă de la început, atinsă treptat. Automatizarea changelog-ului e în mare parte despre menținerea vie a acestei secțiuni fără ca cineva să trebuiască să-și amintească.

Cele șase tipuri se prăbușesc în două. Majoritatea changelog-urilor reale ajung cu Added și Fixed, pentru că Changed și Deprecated necesită o judecată despre pe ce s-a bazat cineva. Acea judecată e partea valoroasă. Deprecated în special e singurul tip care e o promisiune despre viitor, și lăsarea lui deoparte e cum o eliminare se transformă într-un incident; mecanica menținerii acelei promisiuni e în cum se depreciază un API.

Security încetează să fie separat. O corecție de securitate arhivată sub Fixed e invizibilă pentru singura cititoare care o căuta. Păstrați-o distinctă chiar și când corecția e trivială, și mai ales când ați prefera să nu atrageți atenția asupra ei.

Ce nu răspunde specificația?

E un format de fișier. Nu spune nimic despre întrebările pe care le întâlniți imediat după adoptarea ei:

• Cum află cineva? Un fișier într-un repo ajunge la contribuitori. Nu ajunge la o clientă care n-a deschis niciodată GitHub.
• Dar produsele fără versiuni? Un serviciu implementat continuu nu are o v4.2.0 după care să grupeze. Majoritatea echipelor substituie cu date, ceea ce funcționează, iar specificația nici n-o binecuvântează, nici n-o interzice.
• Cine scrie intrarea? Specificația presupune că o face un om. Nu spune când.
• Dar audiențele multiple? Un fișier servește dezvoltatorii. Nu servește același conținut unei administratoare netehnice, iar reformatarea manuală pentru ea e unde începe duplicarea. Changelog vs release notes e împărțirea pe care specificația v-o lasă vouă să o faceți.

Common Changelog, o furcă mai strictă a ideii, strânge o parte din asta: interzice anumite formulări de intrări, necesită un link către schimbare, și are o opinie clară despre cine e cititorul. Merită citit dacă părțile libere ale Keep a Changelog sunt ce dezbate echipa voastră la nesfârșit.

Poate fi automatizat Keep a Changelog fără să deverseze jurnale git?

Da: derivați ciorna din commit-uri structurate, puneți-o în Unreleased cu tipul pre-completat, și cereți ca un om să editeze formularea înainte ca o versiune să fie tăiată. Avertismentul specificației e despre rezultat, nu despre unealtă. Derivarea unei ciorne din commit-uri e în regulă. Publicarea acelei ciorne needitate e ce se opune.

Mașina se ocupă de colectare și formatare, la ce e bună. Omul se ocupă de selecție și formulare, la ce nu e. Conventional commits acoperă împărțirea pe două niveluri de care depinde asta, și ce tipuri de commit se mapează la care dintre cele șase categorii de mai sus. Rezumatul nostru unelte pentru changelog acoperă ce există pentru jumătatea de colectare.

Unde încetează Keep a Changelog să fie suficient?

Se oprește la distribuție. Keep a Changelog e un răspuns bun la “cum ar trebui să arate acest fișier”. Nu e un răspuns la “cum află utilizatorii noștri ce s-a schimbat”, pentru că un fișier Markdown într-un repo e o strategie de distribuție care funcționează doar dacă utilizatorii voștri sunt contribuitori.

Ăsta e obstacolul pe care majoritatea echipelor îl întâlnesc al doilea: fișierul e în regulă, și nimeni din afara echipei nu-l citește. Rezolvarea asta înseamnă că intrările trebuie să devină date care pot fi randate în altă parte, ceea ce e o problemă diferită de formatarea unui fișier, și motivul pentru care exemple de changelog adună pagini publice de changelog, nu fișiere de repository. Cum transformi acele intrări în ceva la care revin oamenii acoperă cum construiești o pagină de changelog.

Adoptați specificația oricum. Costă o după-amiază, face a doua problemă tratabilă, și încă e cea mai bună pagină scrisă vreodată despre asta.

FAQ

E Keep a Changelog un standard? E o convenție larg adoptată, nu specificația unui organism de standardizare. Uneltele (scripturi de lansare, linter-e, parsere) presupun forma lui destul de des încât urmarea lui cumpără compatibilitate.

Ce intră în secțiunea Unreleased? Fiecare intrare pentru o schimbare care a fost integrată dar nu încă lansată într-o versiune numerotată. Când o versiune e tăiată, secțiunea e redenumită la versiune și dată, iar o secțiune Unreleased nouă, goală, merge deasupra ei.

Ar trebui un changelog să folosească versionarea semantică? Keep a Changelog o recomandă și nu o cere. Bibliotecile și API-urile beneficiază; un serviciu implementat continuu de obicei substituie cu date, ceea ce formatul permite.

Ar trebui corecțiile de securitate să fie în changelog înainte de a fi publice? Adăugați intrarea când corecția e lansată, cu destul detaliu ca o operatoare să poată acționa și nu mai mult. Amânarea intrării până la o dată de dezvăluire coordonată e normal; omiterea ei nu e.

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

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