Ako radite na digitalnom proizvodu, prije ili kasnije dođe vrijeme da se zapitate Kako napisati korisne zapise promjena koji olakšavaju rad tima I, usput rečeno, da vaši klijenti mogu lako razumjeti šta se promijenilo. Mnogi timovi počinju s bilješkama o izdanju izgubljenim u centru za pomoć ili skrivenim u Git commitovima, sve dok ne shvate da ih niko ne čita niti koristi.
Dobra vijest je da se uz određenu metodu ovaj haos može transformirati u sistem koji doprinosi Jasnoća, transparentnost i stvarna vrijednost za razvoj, poslovanje, kupce, investitore i podršku.Pogledajmo, korak po korak, kako dizajnirati dnevnik promjena koji funkcionira na dnevnoj bazi, koristeći prednosti i najboljih tehničkih praksi (Git, automatizacija, predlošci...) i ljudske strane upravljanja promjenama unutar organizacije.
Šta je dnevnik promjena i zašto je toliko važan?
Dnevnik promjena je, u suštini, hronološki zapis relevantnih promjena napravljenih na proizvoduNove funkcije, poboljšanja, ispravke, duboke tehničke promjene, ukidanja, eksperimenti... To bi bio "dnevnik evolucije" vašeg softvera, napisan na takav način da svako može pratiti šta se dogodilo između jedne verzije i sljedeće.
U praksi se obično pojavljuju dvije glavne vrste dnevnika promjena, koje treba razlikovati od samog početka jer Ton, dubina i publika su različiti u svakom slučaju:
- Poslovna saopštenjaOvo su bilješke namijenjene korisnicima koji nisu tehnički potkovani i poslovnim profilima. One jednostavnim riječima objašnjavaju šta je novo, šta je poboljšano i koji su problemi riješeni, uvijek se fokusirajući na prednosti i slučajeve upotrebe.
- Dnevnik tehničkih promjenaFokusira se na detalje implementacije: promjene u bazi podataka, refaktorisanje, migracije, verzije zavisnosti, izvršene skripte… Pomaže timu da shvati šta se dogodilo bez udubljivanja u commit po commit.
Obje vrste zapisa su važne jer Služe različitim, ali komplementarnim svrhamaInterno pružaju kontekst i kontrolu; eksterno pokazuju napredak, grade povjerenje i pomažu u komunikaciji vrijednosti.
Prave prednosti održavanja dobrog dnevnika promjena
Osim što jednostavno "izgleda profesionalno", dobro održavan popis promjena nudi vrlo konkretne koristi za tim, kompaniju i korisnikeTo nije samo lijepa dokumentacija: to je radni alat.
Prvo, postaje ključni dio za rješavanje incidenata i analiza regresijaU slučaju greške u produkciji, mogućnost brzog pregleda onoga što je objavljeno tog dana (komponente, verzije, migracije, izvršene skripte) štedi sate istrage i smanjuje prosječno vrijeme rješavanja.
Drugo, jasan, javni popis promjena je moćan način da ostvariti transparentnost i ojačati povjerenje u proizvodKupci i zainteresovane strane vide da se proizvod razvija, da se problemi rješavaju i da postoji živi plan, umjesto da percipiraju "crnu kutiju" koja se mijenja bez objašnjenja.
Nadalje, za poslovne, marketinške ili investitorske profile, dnevnik promjena služi kao primjer pružene vrijednosti: Prikazuje evoluciju proizvoda tokom vremena.Pomaže u praćenju prioriteta i omogućava vam da procijenite da li tempo poboljšanja prati ciljeve kompanije.
Ne smijemo zaboraviti ni internu korisnost: dobro organiziran registar omogućava programerima, proizvodu, osiguranju kvalitete ili podršci osvježiti pamćenje o tome šta se dogodilo u sprintu ili u izdanju bez potrebe za praćenjem desetina grana i spajanja u Gitu. A za podršku, služi kao skripta za odgovaranje korisnicima o novostima ili nedavnom rješavanju problema.
Takođe ima značajnu motivacijsku komponentu: uvid u organizovanu istoriju promena pomaže da se vizualizirajte kolektivni rad obavljen tokom vremenaNešto što se često izgubi među tiketima i commitima, a vidjeti to odraženo jača ponos tima.
Privatni dnevnik promjena: interni dnevnik koji sadrži sve
Većini proizvoda je potreban, barem, jedan privatni, tehnički i prilično detaljan dnevnik promjenaOvo je dokument koji služi kao osnova za revizije, dijagnostiku i koordinaciju između timova. Iako kasnije možete objaviti pojednostavljenu verziju za klijente, ovo je "originalni" dokument na kojem se sve ostalo zasniva.
U mnogim sistemima, ovaj zapis ima oblik tabele ili strukturiranog dokumenta gdje se za svako produkcijsko izdanje ili verziju prikupljaju polja poput sljedećih: Pogođeni modul ili komponenta, vrsta napravljene promjene, prethodne i nove verzije, posebne napomene, tehnički vodič i linkovi do testova (na primjer, za slučajeve testiranja, dokaza ili CI cjevovoda).
Kada promjena uključuje utjecaj na bazu podataka, posebno je korisno dokumentirati je. detalje izvršenih operacija i referencu na određeni skript Pušteno u produkciju. Na ovaj način, ako mjesecima kasnije budu trebali pregledati tačno šta je urađeno, tim ne mora ručno rekonstruirati priču.
Ovaj privatni dnevnik promjena može se snimati po implementaciji (svakom "produkcijskom puštanju u rad") ili po verziji aplikacije. U proizvodima s visokom prilagodljivošću, može se i organizirati. prema slučaju upotrebe ili prema kupcu, što ukazuje na to kako se svaki scenario razvijao tokom vremena.
Najbolje prakse za privatne zapise promjena
Da bi se spriječilo da taj interni zapis postane mrtvi dokument, ključno je da biti smješten na lokaciji koja je pristupačna, sigurna i jednostavna za uređivanje timu.To može biti prostor u korporativnom wikiju, dobro strukturirani dijeljeni dokument ili direktno pohranjen u repozitoriju (na primjer, kao interni CHANGELOG).
Također je preporučljivo da odabrani sistem omogućava Održavajte sigurnosne zahtjeve i zahtjeve kontrole pristupa neophodno u projektu, posebno ako su uključeni osjetljivi tehnički detalji ili podaci o infrastrukturi.
Ključno je učiniti proces ažuriranja dovoljno agilnim kako tim ne bi to doživljavao kao neodrživo dodatno opterećenje, budući da Zastarjeli popis promjena je gotovo gori nego nemati ništa.Pruža lažne sigurnosne informacije i prisiljava vas da sve provjeravate na druge načine.
Javni popis promjena: kako prenijeti istu poruku bez preopterećenja
Na osnovu tog detaljnog internog zapisa, može se izgraditi javni dnevnik promjena, mnogo jednostavniji za korištenje i usmjeren prema krajnjem korisnikuTehnički aspekt "kako" ovdje nije toliko važan koliko "šta" i "zašto": koji problem je riješen, šta poboljšava iskustvo, šta mogu uraditi sada što prije nisu mogli.
Iako je osnovni sadržaj isti kao u internoj verziji, poruka se radikalno mijenja: detalji implementacije se uklanjaju, a promjene se prevode u poslovni jezik, slučajevi upotrebe i konkretne koristiUobičajeno je da se grupišu u odjeljke kao što su "Nove funkcije" i "Ispravke i poboljšanja".
Možete čak ići i korak dalje uključivanjem malog bloka sa nadolazeće ili funkcije u razvojuOvo omogućava korisnicima da znaju šta dolazi u kratkoročnom ili srednjoročnom periodu. Pomaže u upravljanju očekivanjima i pokazuje da postoji dinamičan plan.
Također je dobro mjesto za dodavanje poruke zahvale, obavještenja ili izvinjenja Kada je bilo relevantnih incidenata, koristili smo dnevnik promjena kao iskren komunikacijski kanal s korisničkom bazom.
Neki proizvodi prate javne unose u dnevnik promjena sa snimke ekrana ili animirane GIF-ove Oni prikazuju novu funkciju u akciji, slično kao i poznati alati u razvojnom ekosistemu. Vizuelno, ovo uveliko pomaže korisnicima da shvate promjenu bez potrebe za čitanjem dugih paragrafa.
Savjeti za sastavljanje javnog zapisa
Zlatno pravilo ovdje je Pišite imajući na umu osobu koja će koristiti alat, a ne osobu koja ga je napravila.To znači izbjegavanje nepotrebnog tehničkog žargona, objašnjavanje utjecaja („sada možete X brže“) i davanje prioriteta onome što zaista utiče na svakodnevni život korisnika.
Preporučljivo je održavati prepoznatljivu strukturu od jedne verzije do druge, kako bi čitalac mogao brzo pronaći ono što je relevantno. odjeljci koji vas najviše zanimaju (Na primjer, prvo nove funkcije, zatim poboljšanja, i na kraju ispravke grešaka). Dosljednost olakšava razvoj navike čitanja dnevnika promjena.
Konačno, važno je da su unosi dovoljno jasni kako bi podrška mogla... Jednostavno kopirajte i prilagođavajte tekstove dnevnika promjena Prilikom odgovaranja na zahtjeve ili pripreme komunikacije, ako je tekst koristan u objašnjavanju promjena kupcu, na pravom ste putu.
Dnevnici promjena, Git i automatizacija pravilno shvaćeni
Ako koristite Git kao sistem za kontrolu verzija (što je danas najčešća praksa), imate zlatni rudnik informacija koji možete iskoristiti za generirati dnevnike promjena na sistematičniji način i s manjom vjerovatnoćom da će biti zaboravljeniMeđutim, to se mora uraditi razborito.
Prvi korak je održavanje discipline sa commit-ovima: opisne, konzistentne poruke i, ako je moguće, zasnovane na standardu kao što su konvencionalni commiti. Ovo omogućava automatsku klasifikaciju promjena u tipove (feat, fix, docs, refactor...), što se zatim prevodi u dijelove dnevnika promjena.
Na osnovu toga, alati kao što su conventional-changelog, git-changelog ili generatori ugrađeni u platforme poput GitHub-a ili GitLab-a da izdvoji promjene između oznaka ili izdanja i pohrani ih u CHANGELOG datoteku organiziranu po verzijama.
Tipičan tok rada bi bio: inicijalizacija repozitorija, rad na granama sa dobro napisanim commit-ovima, označavanje verzija, a zatim Automatski ili poluautomatski generirajte dnevnik promjena iz historijena primjer, integrirajući ga u CI/CD cjevovod s GitHub akcijamaZatim se pregleda, jezik se usavršava i objavljuje javna verzija ako je prikladno.
Ova automatizacija ne zamjenjuje ljudsku prosudbu, ali pomaže kako bi se spriječilo da promjene ostanu nedokumentovane Održavanje dnevnika promjena ažurnim zahtijeva manje napora. Međutim, ako se standardi napuste u porukama commit-a, korisnost sistema naglo opada.
Ključni koraci za izgradnju solidnog dnevnika promjena
Pored specifičnih alata, korisno je razmišljati o dizajnu dnevnika promjena kao o malom, višefaznom procesu koji se ponavlja verziju za verzijom i omogućava kako bi se održala kvaliteta i korisnost zapisa.
Prva faza se sastoji od Identifikujte sva relevantna ažuriranja od posljednje verzije.Ne radi se o sastavljanju svake pojedinačne interne mikro-promjene, već o prikupljanju funkcija, ispravki i poboljšanja koja imaju primjetan utjecaj na proizvod.
Onda moraš organizirajte te promjene po verzijama i, unutar svake verzije, po kategorijamaUobičajena je praksa da se grupišu u blokove kao što su „Dodano / Novo“, „Poboljšano / Promijenjeno“, „Ispravljeno“, „Zastarjelo“ ili slično, tako da je vrlo lako locirati koja se vrsta promjene dogodila.
Sljedeći dio je pisanje: opisivanje svake promjene jezikom koji je i jasan i precizan. Idealno, Objasnite šta je urađeno i zašto je to relevantnoizbjegavajući prazne fraze poput „nekoliko manjih poboljšanja“ koje nikome ne koriste.
Nakon što su verzija, kategorije i opisi definirani, preporučljivo je usvojiti standardni i konzistentni format Što se tiče naslova, redoslijeda, stila rečenica, korištenja linkova itd., ovo olakšava i čitanje i integraciju s vanjskim alatima (generatorima, skriptama za objavljivanje).
Konačno, svako novo izdanje treba biti popraćeno ažuriranje dnevnika promjena i dostavljanje istog relevantnim timovima, bilo putem same platforme za kod (izdanja na GitHub-u/GitLabu), web stranice proizvoda, centra za pomoć ili putem e-maila i kampanja na društvenim mrežama.
Kako upravljati i održavati dnevnik promjena tokom vremena
Prava poteškoća nije otvaranje CHANGELOG datoteke, već da ga održi aktivnim i pouzdanim tokom cijelog životnog vijeka projektaZbog toga se prema tome treba odnositi kao prema još jednom dijelu radnog procesa, a ne kao prema nečemu što se na brzinu popunjava na kraju „ako ima vremena“.
Za početak, mnogo pomaže da se to definiše od samog početka. jasna struktura, kompatibilna s vanjskim alatima i jednostavna za praćenjeKlasična shema je navođenje verzija obrnutim redoslijedom (od najnovijih prvo) i, unutar svake od njih, odjeljci s kratkim listama promjena.
Također je ključno da odabrani format bude čitljiv ljudima i jednostavan za uređivanje: Markdown i običan HTML su obično dobre opcije jer Dobro se integriraju sa repozitorijima i sistemima za upravljanje dokumentima i lako ih je obraditi pomoću skripti.
Što se tiče sadržaja, najbolje je fokusirati se na značajne promjene (nove funkcije, ispravke većih grešaka, arhitektonske odluke, promjene u ponašanju) i izbjegavati pretjerano detaljiziranje trivijalnosti. Dnevnik promjena zasićen bukom čini ga... Relevantne informacije se gube među desetinama trivijalnih bilješki.
Druga ključna stvar je ne prebacivati svu odgovornost na jednu osobu: idealno, Cijeli tim se osjeća dijelom održavanja rekordaSvaka osoba može doprinijeti nacrtima svojih tiketa ili korisničkih priča, koje zatim pregleda i objedinjuje neko sa globalnom vizijom.
Konačno, vrlo je praktično povezati dnevnik promjena sa samim alatima za upravljanje poslom (problemi, zadaci, incidenti). U mnogim okruženjima, oznake i unakrsne reference se koriste za ovu svrhu. Povežite svaki unos u dnevniku promjena s odgovarajućim problemom ili zahtjevom za povlačenjem., olakšavajući sljedivost ukoliko bude potrebna daljnja istraga.
Alati i resursi za profesionalizaciju vašeg dnevnika promjena
Kada su temelji postavljeni, pravo je vrijeme da se oslonite na alate koji olakšavaju zadatak i omogućavaju automatizirati dijelove procesa bez gubitka kontrole na konačnom rezultatu.
S jedne strane, postoje alati koji generiraju bilješke o izdanju iz oznaka i poruka o potvrđivanju, kao što su Generatori bilješki o izdanju Gita ili skripte zasnovane na konvencijama poruka. Obično vam omogućavaju da prilagodite izlazni format kako bi odgovarao vašim predlošcima.
Platforme za hosting koda same po sebi nude korisne funkcije: na primjer, Mehanizmi izdanja GitHub-a ili GitLab-a Omogućavaju vam kreiranje označenih verzija i pisanje povezanog dnevnika promjena odmah na mjestu, koji se zatim može sinhronizovati sa javnom dokumentacijom.
Postoje i standardizirani vodiči i predlošci, kao što je dobro poznata inicijativa „Vodite dnevnik promjena“, koja predlaže standardna struktura sekcija i konvencije imenovanjaUsvajanje nečega ovakvog pomaže svakome ko je upoznat s tim standardom da se snađe u vašem registru.
Konačno, postoje online generatori koji mogu upoređivati oznake u repozitoriju i kreirati nacrt dnevnika promjena između njih. Ove vrste alata su posebno korisne u kolaborativni projekti s mnogim saradnicimagdje bi ručno sastavljanje svih promjena bilo nepraktično.
Koji god stek da se odabere, važno je da Alati se prilagođavaju radnom procesu vašeg tima a ne obrnuto. Vrlo moćan sistem, ali onaj koji se doživljava kao stran ili složen, na kraju će se koristiti malo ili loše.
U konačnici, kreiranje i održavanje dobrog dnevnika promjena ne svodi se samo na popisivanje promjena, već na izgraditi jasnu i iskrenu priču o evoluciji proizvodašto pomaže timu da bolje radi, smanji rizike u svakom raspoređivanju i komunicira klijentima i zainteresovanim stranama da je softver aktivan, da se o njemu brine i da se kreće u razumljivom smjeru.
