Kto pisze changelog, i kto powinien

Zapytajcie zespół, kto pisze changelog, a szczera odpowiedź to zwykle “ktokolwiek pamięta”, co jest tym samym trybem awarii, który wymuszanie wpisu w changelogu w CI istnieje, by naprawić na poziomie mechanicznym. Ale wymuszenie istnienia wpisu nie decyduje, kto jest wykwalifikowana, by napisać dobry, a zespoły, które pomijają to pytanie, mają tendencję do domyślnego wyboru kogokolwiek najłatwiejszego do zmuszenia, zwykle autorki PR, bez sprawdzania, czy to naprawdę osoba, która potrafi go dobrze napisać.

Dlaczego autorka PR nie jest automatycznie najlepszą autorką changelogu?

Ponieważ zna implementację, niekoniecznie wpływ, a to różne rodzaje wiedzy. Gdzie zatrzymują się conventional commits opisuje tę lukę od strony komunikatu commita: fix(auth): reject expired refresh tokens jest poprawny i nic nie mówi klientce, a osoba, która napisała tę poprawkę, jest często osobą najmniej wyposażoną, by ją przetłumaczyć, ponieważ myślała w kategoriach błędu przez godziny i straciła zewnętrzny widok na to, czego użytkowniczka faktycznie doświadczyła. To ten sam powód, dla którego pisarki techniczne istnieją jako zawód: przetłumaczenie implementacji na wpływ to osobna umiejętność od zbudowania danej rzeczy i wymaga praktyki niezależnie od tego, jak dobra jest programistka w samym kodzie.

Czy to oznacza, że produkt lub wsparcie powinny pisać każdy wpis zamiast tego?

Nie, ponieważ mają odwrotną lukę: wiedzą, co ma znaczenie dla użytkowniczek, ale nie zawsze co faktycznie zostało wydane, co produkuje wpisy czytelne, ale czasem błędne co do zakresu, twierdzenie “teraz wspiera X” dla funkcji wciąż za flagą, lub poprawka opisana jako kompletna, gdy pokrywa tylko jeden z trzech przypadków. Tryb awarii wpisów pisanych przez programistki to nieczytelny-ale-dokładny; tryb awarii wpisów pisanych przez PM-ki to czytelny-ale-niezweryfikowany. Żadna rola nie posiada obu połówek tego, czego potrzebuje dobry wpis.

Jak naprawdę wygląda działający model własności?

Wersja robocza od kogokolwiek najbliższego zmianie, sprawdzona przez kogokolwiek najbliższego użytkowniczce, z jedną nazwaną osobą odpowiedzialną za ostateczne sformułowanie, zamiast wszystkich zakładających, że ktoś inny złapie problemy. Wersja robocza musi istnieć i być dokładna bardziej, niż musi być dobra; surowe zdanie napisane przez programistkę, które poprawnie mówi, co się zmieniło, to lepszy punkt startowy niż wypolerowane, ale niezweryfikowane, ponieważ przepisywanie dla jasności jest łatwiejsze niż przepisywanie dla poprawności. Krok recenzji to miejsce, gdzie PM lub liderka wsparcia czyta wersję roboczą i zadaje jedno pytanie, które łapie lukę czytelności: czy zrozumiałabym to, gdybym nie widziała kodu.

Czy zawsze powinna być ta sama osoba odpowiedzialna, czy to się rotuje?

Nazwana i stabilna wygrywa z rotującą, przynajmniej dla ostatecznego zatwierdzenia. Rotująca właścicielka oznacza, że każdy wpis jest sprawdzany przez kogoś, kto od nowa wyprowadza konwencje zespołu, co jest dokładnie tym, jak głos dryfuje od wpisu do wpisu, a czytelniczka zaczyna zauważać, że changelog został napisany przez komitet. Jedna osoba, lub bardzo małe stabilne grono, gromadzi osądy z czasem, kiedy mówić “ulepszono” a kiedy nazwać konkretną liczbę, kiedy poprawka potrzebuje własnego wpisu a kiedy złożyć ją w partię, i ten osąd jest wart więcej niż równomierne rozłożenie pracy.

Wersja robocza (programistka, z PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Sprawdzona (właścicielka changelogu, zweryfikowana z prawdziwym PR):
"Naprawiono: eksporty posortowane według daty mogły
zwracać wyniki nie w kolejności poza pierwszą stroną.
Teraz spójne na wszystkich stronach."

Czy mały zespół potrzebuje aż tyle procesu dla jednej linijki tekstu?

Nie ról jako osobnych osób, ale dwa kroki wciąż się liczą nawet solo. Zespół jednoosobowy jest zarówno programistką, jak i recenzentką, a dyscyplina, która przetrwa na tę skalę, to zrobienie recenzji jako osobnego przejścia mentalnego, nie skakanie prosto od napisania poprawki do publikacji jej opisu w tym samym oddechu. Pułapka na małą skalę to całkowite pominięcie drugiego przejścia, nie brak drugiej osoby, ponieważ nikt zewnętrzny go nie wymusza, a luka dokładności, którą to przejście istnieje, by złapać, nie znika tylko dlatego, że ta sama osoba mogłaby teoretycznie zauważyć własny martwy punkt.

Co się dzieje, gdy nikt nie jest odpowiedzialny za ostateczny wpis?

Changelog degraduje się nierówno zamiast zawieść jawnie, co jest gorsze, ponieważ nikt tego nie zauważa, dopóki czytelniczka na to nie wskaże. Niektóre wpisy pozostają ostre, ponieważ ktokolwiek je napisał, dbał o to; inne stają się mgliste, “różne ulepszenia i poprawki błędów”, ponieważ ktokolwiek je napisał, poruszał się szybko i nikt tego nie złapał przed publikacją. Ograniczenia formatu Keep a Changelog łapią dryf strukturalny, brakujące daty, złe kategorie, ale nic w szablonie nie łapie mglistego wpisu, który jest technicznie dobrze sformatowany, co jest dokładnie luką, którą nazwana właścicielka jest tam, by zamknąć.

FAQ

Czy właścicielka changelogu powinna być rolą inżynieryjną czy produktową? Obie mogą zadziałać, jeśli osoba ma zarówno techniczną biegłość, by zweryfikować zakres, jak i wystarczający dystans od implementacji, by pisać dla zewnętrznej czytelniczki; tytuł liczy się mniej niż to, czy potrafi zrobić obie połówki, lub wie, kogo zapytać o połówkę, której nie potrafi.

Czy rotujący harmonogram w stylu dyżuru jest kiedykolwiek odpowiedni dla własności changelogu? Dla wolumenu czasami, jeśli zespół jest zbyt mały, by jedna osoba sprawdzała wszystko; dla głosu i osądu nie, ponieważ to dokładnie to, co erodowuje rotacja. Rotacja, która dzieli obciążenie pisaniem wersji roboczych, zachowując stabilną recenzentkę, dostaje korzyść bez dryfu.

Jaki jest najszybszy znak, że coś jest nie tak z obecną konfiguracją własności? Wpisy, które są dokładne, ale nieczytelne, lub czytelne, ale błędne co do zakresu, w wzorcu, który podąża za tym, kto je napisał. Jeśli jakość koreluje z autorką zamiast pozostawać spójna, własność jest luką, nie umiejętność pisania.

Czy automatyzacja zmniejsza, jak bardzo liczy się własność? Zmniejsza, ile pisania jest potrzebne, nie ile osądu jest potrzebne. Automatyzacja changelogu opisuje, co pipeline może bezpiecznie wygenerować, formatowanie, publikację, cross-posting; sformułowanie, grupowanie i to, co liczy się jako warte wzmianki, pozostają decyzjami ludzkimi niezależnie od tego, ile z pipeline’u jest zautomatyzowane.

A jeśli autorka PR i recenzentka nie zgadzają się co do sformułowania? Decyduje recenzentka, bo pytanie, na które odpowiada, czy zewnętrzna czytelniczka by to zrozumiała, to właśnie to, które ta rola istnieje, by chronić. To nie czyni oceny programistki bezwartościową: jeśli spór dotyczy dokładności, a nie sformułowania, recenzentka ustępuje, bo zakres to połowa, za którą odpowiada autorka. Rozdzielenie tych dwóch rodzajów sporu, sformułowania od dokładności, powstrzymuje większość z nich przed przerodzeniem się w impas.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Porównanie narzędzi do changeloga, Generator changeloga