Jeśli pracujesz nad produktem cyfrowym, prędzej czy później przyjdzie czas, aby zadać sobie pytanie Jak pisać przydatne rejestry zmian, które ułatwią pracę zespołowi A przy okazji, aby Twoi klienci mogli łatwo zrozumieć, co się zmieniło. Wiele zespołów zaczyna od notatek o wydaniach, które zaginęły w centrum pomocy lub są ukryte w commitach Gita, dopóki nie zorientują się, że nikt ich nie czyta ani nie używa.
Dobrą wiadomością jest to, że stosując jakąś metodę, ten chaos można przekształcić w system, który przyczynia się Przejrzystość, transparentność i rzeczywista wartość dla rozwoju, biznesu, klientów, inwestorów i wsparcia.Zobaczmy krok po kroku, jak zaprojektować dziennik zmian, który będzie działał na co dzień, wykorzystując najlepsze praktyki techniczne (Git, automatyzacja, szablony...) i bardziej ludzki aspekt zarządzania zmianą w organizacji.
Czym jest dziennik zmian i dlaczego jest tak ważny?
Rejestr zmian to w zasadzie: chronologiczny zapis istotnych zmian wprowadzonych do produktuNowe funkcje, udoskonalenia, poprawki, głębokie zmiany techniczne, wycofania, eksperymenty… Byłby to „dziennik ewolucji” Twojego oprogramowania, napisany w taki sposób, aby każdy mógł śledzić, co wydarzyło się pomiędzy jedną wersją a kolejną.
W praktyce zazwyczaj pojawiają się dwa główne typy changelogów, które należy rozróżnić już na początku, ponieważ Ton, głębia i odbiorcy są inni w każdej sprawie:
- Wydania biznesoweSą to notatki przeznaczone dla użytkowników nietechnicznych i profili biznesowych. W prosty sposób wyjaśniają, co nowego, co zostało ulepszone i jakie problemy zostały rozwiązane, zawsze koncentrując się na korzyściach i przypadkach użycia.
- Dziennik zmian technicznychKoncentruje się na szczegółach implementacji: zmianach w bazie danych, refaktoryzacjach, migracjach, wersjach zależności, wykonanych skryptach… Pomaga zespołowi zrozumieć, co się stało, bez konieczności zagłębiania się w szczegóły każdego zatwierdzenia.
Oba typy rekordów są ważne, ponieważ Służą różnym, ale uzupełniającym się celomWewnętrznie zapewniają kontekst i kontrolę; zewnętrznie pokazują postęp, budują zaufanie i pomagają komunikować wartości.
Rzeczywiste korzyści z prowadzenia dobrego rejestru zmian
Dobrze prowadzony rejestr zmian to nie tylko „profesjonalny wygląd”, ale także bardzo konkretne korzyści dla zespołu, firmy i użytkownikówTo nie jest tylko ładna dokumentacja: to narzędzie pracy.
Po pierwsze, staje się kluczowym elementem rozwiązywać incydenty i analizować regresjeW przypadku wystąpienia błędu produkcyjnego możliwość szybkiego przejrzenia tego, co wydano danego dnia (komponenty, wersje, migracje, wykonane skrypty) pozwala zaoszczędzić wiele godzin na dochodzenie i skrócić średni czas rozwiązania problemu.
Po drugie, przejrzysty, publiczny rejestr zmian jest skutecznym sposobem na wykaż się przejrzystością i wzmocnij zaufanie do produktuKlienci i interesariusze widzą, że produkt się rozwija, że problemy są rozwiązywane i że istnieje żywa mapa drogowa, zamiast postrzegać go jako „czarną skrzynkę”, która zmienia się bez wyjaśnienia.
Ponadto w przypadku profili biznesowych, marketingowych lub inwestorskich rejestr zmian służy jako prezentacja dostarczonej wartości: Pokazuje ewolucję produktu na przestrzeni czasu.Pomaga śledzić priorytety i pozwala ocenić, czy tempo ulepszeń jest zgodne z celami firmy.
Nie powinniśmy też zapominać o wewnętrznej użyteczności: dla programistów, działu produkcji, działu zapewnienia jakości lub wsparcia dobrze zorganizowany rejestr pozwala odświeżyć pamięć o tym, co wydarzyło się w sprincie lub wydaniu bez konieczności śledzenia dziesiątek gałęzi i scaleń w Gicie. A dla wsparcia technicznego służy jako skrypt do odpowiadania klientom na pytania o nowości lub ostatnio rozwiązane problemy.
Ma również istotny komponent motywacyjny: zobaczenie zorganizowanej historii zmian pomaga wizualizować wspólną pracę wykonaną w czasieCoś, co często gubi się wśród zgłoszeń i potwierdzeń, a co teraz, gdy to widzimy, wzmacnia dumę z zespołu.
Prywatny dziennik zmian: wewnętrzny dziennik, w którym przechowywane są wszystkie zmiany
Większość produktów wymaga co najmniej jednego prywatny, techniczny i dość szczegółowy dziennik zmianTo dokument stanowiący podstawę audytów, diagnostyki i koordynacji między zespołami. Chociaż później możesz opublikować uproszczoną wersję dla klientów, to jest to „oryginalny” dokument, na którym opiera się wszystko inne.
W wielu systemach rekord ten ma formę tabeli lub ustrukturyzowanego dokumentu, w którym dla każdego wydania lub wersji produkcyjnej gromadzone są pola takie jak poniższe: Dotknięty moduł lub komponent, rodzaj wprowadzonej zmiany, poprzednie i nowe wersje, uwagi specjalne, informacje techniczne i linki do testów (na przykład w przypadku testów, dowodów lub procesów CI).
Gdy zmiana ma wpływ na bazę danych, szczególnie przydatne jest jej udokumentowanie. szczegóły wykonanych operacji i odniesienie do konkretnego skryptu Wprowadzone do produkcji. W ten sposób, jeśli miesiące później zespół będzie musiał dokładnie przeanalizować, co zostało zrobione, nie będzie musiał ręcznie rekonstruować historii.
Ten prywatny dziennik zmian może być rejestrowany dla każdego wdrożenia (każdego „uruchomienia produkcyjnego”) lub dla każdej wersji aplikacji. W produktach o wysokim stopniu personalizacji można go również uporządkować. według przypadku użycia lub klienta, wskazując jak każdy scenariusz ewoluował w czasie.
Najlepsze praktyki dotyczące prywatnych rejestrów zmian
Aby zapobiec temu, by wewnętrzny zapis stał się martwym dokumentem, kluczowe jest, aby: być hostowane w miejscu, które jest dostępne, bezpieczne i łatwe do edycji dla zespołu.Może to być przestrzeń w firmowej wiki, dobrze ustrukturyzowany współdzielony dokument lub dane przechowywane bezpośrednio w repozytorium (na przykład jako wewnętrzny DZIENNIK ZMIAN).
Zaleca się również, aby wybrany system umożliwiał Utrzymywanie wymagań bezpieczeństwa i kontroli dostępu konieczne w projekcie, zwłaszcza jeśli uwzględnia on wrażliwe szczegóły techniczne lub dane infrastrukturalne.
Kluczem jest uczynienie procesu aktualizacji wystarczająco elastycznym, aby zespół nie postrzegał go jako dodatkowego, niemożliwego do utrzymania obciążenia, ponieważ Nieaktualny rejestr zmian jest prawie gorszy niż jego brak.Podaje fałszywe informacje dotyczące bezpieczeństwa i zmusza do weryfikowania wszystkiego innymi sposobami.
Dziennik zmian publicznych: jak przekazać tę samą wiadomość, nie przytłaczając jej
Na podstawie tego szczegółowego wewnętrznego zapisu można zbudować publiczny dziennik zmian, znacznie bardziej przyjazny dla użytkownika i ukierunkowany na użytkownika końcowegoTechniczne „jak” nie jest tutaj tak ważne jak „co” i „dlaczego”: jaki problem został rozwiązany, co ulepszyło doświadczenie, co można zrobić teraz, czego nie można było zrobić wcześniej.
Mimo że podstawowa treść jest taka sama jak w wersji wewnętrznej, komunikat zmienia się radykalnie: usuwane są szczegóły implementacji, a zmiany są tłumaczone na język biznesowy, przypadki użycia i konkretne korzyściPowszechnie grupuje się je w sekcje, takie jak „Nowe funkcje” oraz „Poprawki i udoskonalenia”.
Możesz pójść o krok dalej, dodając mały blok z funkcje nadchodzące lub będące w fazie rozwojuDzięki temu użytkownicy wiedzą, co przyniesie przyszłość w perspektywie krótkoterminowej i średnioterminowej. Pomaga to zarządzać oczekiwaniami i pokazuje, że istnieje dynamiczna mapa drogowa.
To również dobre miejsce na dodanie wiadomości z podziękowaniami, zawiadomieniami lub przeprosinami Gdy zdarzały się istotne incydenty, wykorzystywaliśmy rejestr zmian jako uczciwy kanał komunikacji z użytkownikami.
Niektóre produkty są opatrzone wpisami w publicznym dzienniku zmian zrzuty ekranu lub animowane pliki GIF Prezentują nową funkcję w działaniu, podobnie jak znane narzędzia w ekosystemie programistycznym. Wizualnie, znacznie ułatwia to użytkownikom zrozumienie zmiany bez konieczności czytania długich akapitów.
Wskazówki dotyczące sporządzania dokumentacji publicznej
Złota zasada tutaj jest taka: Pisząc, myśl o osobie, która będzie używać narzędzia, a nie o osobie, która je stworzyła.Oznacza to unikanie zbędnego żargonu technicznego, wyjaśnianie wpływu („teraz możesz zrobić X szybciej”) i priorytetyzowanie tego, co naprawdę wpływa na codzienne życie użytkowników.
Wskazane jest zachowanie rozpoznawalnej struktury w kolejnych wersjach, aby czytelnik mógł szybko odnaleźć to, co istotne. sekcje, które Cię najbardziej interesują (Na przykład najpierw nowe funkcje, potem ulepszenia, a na końcu poprawki błędów). Spójność ułatwia wyrobienie nawyku czytania rejestru zmian.
Na koniec ważne jest, aby wpisy były na tyle przejrzyste, aby umożliwić wsparcie... Łatwe kopiowanie i dostosowywanie tekstów dziennika zmian Jeśli odpowiadasz na zgłoszenia lub przygotowujesz komunikaty i tekst jest pomocny w wyjaśnieniu zmian klientowi, jesteś na dobrej drodze.
Prawidłowe zrozumienie dzienników zmian, Gita i automatyzacji
Jeśli używasz Gita jako systemu kontroli wersji (co jest obecnie najpowszechniejszą praktyką), dysponujesz kopalnią informacji, którą możesz wykorzystać do generować rejestry zmian w sposób bardziej systematyczny i mniej podatny na zapomnienieNależy jednak postępować rozważnie.
Pierwszym krokiem jest utrzymanie dyscypliny w zatwierdzaniu zmian: opisowe, spójne komunikaty, a jeśli to możliwe, oparte na standardzie takie jak konwencjonalne commity. Pozwala to na automatyczne klasyfikowanie zmian według typów (wyczyn, poprawka, dokumentacja, refaktoryzacja…), co następnie przekłada się na sekcje rejestru zmian.
Na tej podstawie narzędzia takie jak: konwencjonalny dziennik zmian, dziennik zmian git lub generatory wbudowane w platformy takie jak GitHub lub GitLab aby wyodrębnić zmiany pomiędzy tagami lub wydaniami i zapisać je w pliku CHANGELOG uporządkowanym według wersji.
Typowy przepływ pracy wyglądałby następująco: zainicjowanie repozytorium, praca nad gałęziami z dobrze napisanymi zatwierdzeniami, oznaczenie wersji, a następnie Generuj dziennik zmian automatycznie lub półautomatycznie z historiina przykład poprzez zintegrowanie go z Proces CI/CD z akcjami GitHubNastępnie jest ona sprawdzana, język dopracowywany, a wersja publiczna, jeśli jest to stosowne, jest publikowana.
Automatyzacja ta nie zastępuje osądu ludzkiego, ale pomaga aby zapobiec nieudokumentowaniu zmian Utrzymywanie dziennika zmian na bieżąco wymaga mniej wysiłku. Jednak jeśli standardy są porzucane w komunikatach zatwierdzających, użyteczność systemu gwałtownie spada.
Kluczowe kroki tworzenia solidnego rejestru zmian
Oprócz konkretnych narzędzi, pomocne jest myślenie o projektowaniu rejestru zmian jako o małym, wieloetapowym procesie, który jest powtarzany wersja po wersji i pozwala aby utrzymać jakość i użyteczność rekordu.
Pierwszy etap składa się z Zidentyfikuj wszystkie istotne aktualizacje od czasu ostatniej wersji.Nie chodzi o zebranie wszystkich drobnych zmian, ale o zebranie funkcji, poprawek i udoskonaleń, które mają zauważalny wpływ na produkt.
Wtedy musisz zorganizuj te zmiany według wersji, a w obrębie każdej wersji według kategoriiPowszechną praktyką jest grupowanie ich w bloki, takie jak „Dodano/Nowe”, „Ulepszone/Zmienione”, „Naprawione”, „Wycofane” itp., dzięki czemu można łatwo zlokalizować, jaki typ zmiany nastąpił.
Następnie następuje część pisemna: opisanie każdej zmiany językiem jasnym i precyzyjnym. Idealnie, Wyjaśnij, co zostało zrobione i dlaczego jest to istotneunikając pustych frazesów w rodzaju „kilka drobnych usprawnień”, które nikomu nie przynoszą korzyści.
Po zdefiniowaniu wersji, kategorii i opisów zaleca się przyjęcie standardowy i spójny format Ułatwia to zarówno czytanie, jak i integrację z narzędziami zewnętrznymi (generatorami, skryptami publikacyjnymi), jeśli chodzi o nagłówki, kolejność, styl zdań, użycie linków itp.
Wreszcie, każda nowa wersja powinna być opatrzona aktualizowanie rejestru zmian i przekazywanie go odpowiednim zespołomczy to za pośrednictwem samej platformy kodu (publikacje na GitHub/GitLab), witryny produktu, centrum pomocy czy kampanii e-mailowych i w mediach społecznościowych.
Jak zarządzać dziennikiem zmian i go utrzymywać w czasie
Prawdziwą trudnością nie jest otwarcie pliku CHANGELOG, ale aby utrzymać go przy życiu i niezawodności przez cały okres trwania projektuDlatego należy traktować to po prostu jako kolejny element procesu pracy, a nie jako coś, co wypełnia się pospiesznie na końcu, „jeśli wystarczy czasu”.
Na początek bardzo pomocne jest zdefiniowanie tego od początku. przejrzysta struktura, kompatybilna z narzędziami zewnętrznymi i łatwa do naśladowaniaKlasycznym sposobem jest wypisywanie wersji w odwrotnej kolejności (najnowsza na początku), a w obrębie każdej z nich umieszczanie sekcji z krótkimi listami zmian.
Ważne jest również, aby wybrany format był czytelny dla człowieka i łatwy do edycji: Markdown i zwykły HTML to zazwyczaj dobre opcje, ponieważ Dobrze integrują się z repozytoriami i systemami zarządzania dokumentami i są łatwe do przetworzenia przez skrypty.
Jeśli chodzi o treść, najlepiej skupić się na istotnych zmianach (nowych funkcjach, istotnych poprawkach błędów, decyzjach architektonicznych, zmianach w działaniu) i unikać nadmiernego wdawania się w szczegóły. Rejestr zmian przepełniony szumem informacyjnym sprawia, że... Istotne informacje gubią się wśród dziesiątek drobnych notatek.
Kluczem jest również to, aby nie obarczać całej odpowiedzialności jedną osobą: w idealnym przypadku Cały zespół czuje się częścią utrzymania rekorduKażda osoba może dodać projekty na podstawie swoich zgłoszeń lub historii użytkowników, które następnie są sprawdzane i konsolidowane przez osobę z globalną wizją.
Wreszcie, bardzo praktyczne jest połączenie rejestru zmian z samymi narzędziami do zarządzania pracą (zgłoszeniami, zadaniami, incydentami). W wielu środowiskach wykorzystuje się w tym celu tagi i odsyłacze. Powiąż każdy wpis w dzienniku zmian z odpowiadającym mu problemem lub żądaniem ściągnięcia.ułatwiając śledzenie, gdyby zaszła potrzeba przeprowadzenia dalszych badań.
Narzędzia i zasoby do profesjonalizacji rejestru zmian
Gdy fundamenty zostaną już położone, nadszedł dobry moment, aby skorzystać z narzędzi, które ułatwią zadanie i pozwolą automatyzuj części procesu bez utraty kontroli o końcowym wyniku.
Z jednej strony istnieją narzędzia, które generują notatki o wydaniach z tagów i komunikatów zatwierdzających, takie jak: Generatory notatek o wydaniach Git lub skrypty oparte na konwencjach wiadomości. Zazwyczaj pozwalają one dostosować format wyjściowy do szablonów.
Platformy hostujące kod same w sobie oferują przydatne funkcje, na przykład: Wydania GitHub lub mechanizmy wydań GitLab Umożliwiają one tworzenie wersji oznaczonych tagami i zapisywanie powiązanego z nimi rejestru zmian, który następnie można zsynchronizować z publiczną dokumentacją.
Istnieją również standardowe przewodniki i szablony, takie jak znana inicjatywa „Prowadź dziennik zmian”, która proponuje standardowa struktura sekcji i konwencje nazewnictwaZastosowanie takiego rozwiązania ułatwi każdemu zaznajomionemu z tym standardem poruszanie się po rejestrze.
Wreszcie, istnieją generatory online, które umożliwiają porównywanie tagów w repozytorium i generowanie projektu rejestru zmian między nimi. Tego typu narzędzia są szczególnie przydatne w projekty współpracy z wieloma współpracownikamigdzie ręczne kompilowanie wszystkich zmian byłoby niepraktyczne.
Niezależnie od tego, jaki stos wybierzesz, najważniejsze jest to, że Narzędzia dostosowują się do przepływu pracy Twojego zespołu a nie odwrotnie. Bardzo potężny system, ale postrzegany jako obcy lub skomplikowany, ostatecznie będzie wykorzystywany rzadko lub niewłaściwie.
Ostatecznie tworzenie i prowadzenie dobrego rejestru zmian nie polega tylko na wypisywaniu zmian, ale na stworzyć jasną i uczciwą narrację dotyczącą ewolucji produktuco pomaga zespołowi pracować lepiej, ograniczać ryzyko przy każdym wdrożeniu oraz przekazywać klientom i interesariuszom informację, że oprogramowanie jest żywe, zadbane i rozwija się w zrozumiałym kierunku.
