Release notes poprawek błędów: jak pisać użyteczne wpisy

Dobre release notes poprawek błędów opisują to, co użytkownik zobaczył jako błąd, a nie to, co zawiodło w kodzie. Każdy wpis mówi, kogo to dotknęło, od kiedy, czy poprawka jest kompletna i czy czytelnik musi coś zrobić, nawet jeśli to tylko “żadne działanie nie jest potrzebne”.

Większość zespołów kopiuje linię z komunikatu commita. Tabela pokazuje sześć przepisanych wpisów, a sekcje po niej wyjaśniają zasady.

Jak napisać wpis o poprawce błędu w release notes?

Zacznijcie od objawu słowami użytkownika, potem kogo dotknął i od kiedy, potem stan poprawki, potem działanie. Zwykle wystarczą jedno lub dwa zdania. Przyczyna w kodzie należy do pull requesta, gdzie zajrzy do niej inżynier.

Czytelnik szuka jednej rzeczy: “czy to byłem ja?” Cztery części pokrywają prawie każdy wpis:

1. Objaw. Co pojawiło się na ekranie, w odpowiedzi API albo na fakturze. Zacytujcie tekst błędu, jeśli był, bo ludzie go wyszukują.
2. Zakres. Który plan, platforma, wersja API albo kształt danych. “Konta z ponad 50 000 wierszy” da się sprawdzić. “Niektórzy użytkownicy” nie.
3. Okno. Od którego wydania lub daty, żeby czytelnik mógł ocenić, czy wczorajszy dziwny wynik był tym błędem.
4. Działanie. Uruchomić ponownie, zsynchronizować ponownie, zaktualizować, usunąć obejście albo nic.

Jeśli użytkownicy zbudowali obejście, linia z działaniem to miejsce, w którym mówicie im, że mogą je usunąć.

Czym różni się release note od changelogu?

Changelog to kompletny, bieżący rejestr zmian. Release notes to wybrana, przepisana wiadomość o jednym wydaniu dla ludzi, którzy decydują, czy się tym przejmować. W przypadku poprawek błędów changelog wylicza każdą, a notatki prowadzą z tymi, które czytelnik mógł zauważyć.

Literówka w dymku podpowiedzi należy tylko do changelogu. Zły podatek na fakturach należy do obu. Pełny podział jest w changelog vs release notes, a kształt dobrego zestawu notatek w jak pisać release notes.

Keep a Changelog to poręczna konwencja po stronie rejestru. Zachowuje “Fixed” dla wszelkich poprawek błędów i osobny nagłówek “Security” dla luk, czyli ten sam podział, który ten artykuł robi dla czytelnika.

Czy poprawka błędu to aktualizacja?

Tak. Poprawka błędu zmienia produkt, więc jej wydanie jest aktualizacją. W semantic versioning kompatybilna wstecz poprawka to wydanie patch, na przykład 4.2.0 do 4.2.1.

To, czy czytelnik musi cokolwiek zrobić, to osobne pytanie i nota powinna na nie odpowiedzieć. Poprawka, która zmienia to, co obserwuje poprawny wywołujący, jest bliska zmianie łamiącej, a breaking changes wyjaśnia, gdzie leży ta granica.

Kiedy poprawka dostaje własny wpis, a kiedy jest drobną poprawką?

Dajcie poprawce własny wpis, gdy użytkownik mógł zauważyć błąd, stracić na nim czas lub dane albo zbudować wokół niego obejście. Zgrupujcie ją na krótkiej liście “Drobne poprawki”, gdy nikt poza waszym zespołem nie mógł jej zobaczyć. Oceniajcie ją według doświadczenia czytelnika, a nie rozmiaru diffa.

Każda linia w grupie powinna nadal coś mówić: “Naprawiono kilka problemów z interfejsem” to zapychacz.

Jak pisać o regresji?

Nazwijcie wydanie, które ją wprowadziło, nazwijcie ją regresją i podajcie wydanie, które ją naprawia. Ludzie, którzy trafili na błąd, już wiedzą, że coś się zepsuło, więc krótkie, bezpośrednie przyznanie służy im lepiej niż mgliste słowa.

Na przykład: “Wyniki wyszukiwania dla zapytań zawierających myślnik wracały puste w 4.1.0. Jest to naprawione w 4.1.1. Jeśli zmieniliście zapytania, by uniknąć myślników, możecie je przywrócić.”

“Poprawiono niezawodność wyszukiwania” brzmi jak unik dla każdego, kto stracił popołudnie przez ten błąd. Jeśli przyczyna wciąż jest potwierdzana, napiszcie to, jak ujmują to wskazówki o awaryjnych release notes: nota nigdy nie powinna brzmieć pewniej niż zespół.

Jak ogłosić poprawkę bezpieczeństwa?

Powiedzcie wprost, jak poważna jest luka, nazwijcie dotknięte wersje i wersję, która je naprawia, powiedzcie, jak pilna jest aktualizacja, i dołączcie identyfikator CVE, jeśli istnieje. Publikujcie szczegóły dopiero wtedy, gdy użytkownicy mogą zastosować poprawkę, stosując proces skoordynowanego ujawniania, gdy brał w tym udział zgłaszający.

Kolejność ma znaczenie: zgłaszający mówi wam prywatnie, wy wydajecie poprawkę, a nota publiczna wychodzi, gdy użytkownicy mogą się zabezpieczyć. Proces skoordynowanego ujawniania podatności CISA koordynuje zgłaszanie, analizę i publiczne ujawnianie podatności. Zasady CVE Numbering Authority regulują, jak rekordy CVE są przyznawane i publikowane, a na GitHubie repository security advisory pozwala przygotować komunikat prywatnie i poprosić o identyfikator.

Wpis o bezpieczeństwie zwykle niesie cztery fakty:

• Co mógłby zrobić atakujący, w jednym zdaniu i bez proof of concept.
• Dotknięte wersje i wersję, która to naprawia.
• Jak pilne to jest: “zaktualizuj dziś” albo “zaktualizuj przy następnym wydaniu”.
• Czy widzieliście wykorzystanie luki, i podziękowanie dla zgłaszającego, jeśli się zgodził.

Pomińcie kroki exploita.

Co powinna powiedzieć nota o poprawce utraty danych?

Powiedzcie, jakie dane zostały dotknięte, jak sprawdzić, czy to dotyczy waszych, i czy da się je odzyskać. “Żadne działanie nie jest potrzebne” rzadko jest tu prawdą, a pierwsze pytanie czytelnika brzmi “czy moje dane przepadły”.

Użyteczny wpis podaje warunek, który gubił dane (“usunięcie folderu podczas trwającej synchronizacji”), okno, w którym to było możliwe, sposób sprawdzenia (“otwórz Kosz i poszukaj elementów z datą od 3 do 9 września”) oraz ścieżkę odzyskania. Jeśli danych nie da się odzyskać, powiedzcie to. Skontaktujcie się też bezpośrednio z dotkniętymi klientami, bo release note nie powinna być jedynym miejscem, w którym ktoś dowiaduje się, że jego dane ucierpiały.

Dlaczego “Poprawki błędów i usprawnienia wydajności” to słaba nota?

Nie daje czytelnikowi nic do działania i ukrywa poprawki, na które ktoś czekał. Klient, który zgłosił awarię, nie wie, czy jest naprawiona, a klient z obejściem nie wie, czy je usunąć.

Są dwie uczciwe alternatywy. Jeśli wydanie nie ma nic, co czytelnik mógłby zauważyć, nie publikujcie dla niego notatek i zostawcie zapis changelogowi. Jeśli ma poprawki, wylistujcie je w kategoriach czytelnika:

Przed:
  Poprawki błędów i usprawnienia wydajności.

Po:
  Naprawiono: eksport CSV nie działał dla projektów bez tagów.
  Naprawiono: tryb ciemny ukrywał kursor w polu komentarza.
  Szybciej: panel otwiera się szybciej dla przestrzeni
  z ponad 100 projektami.

Skąd biorą się noty o poprawkach błędów?

Biorą się z pull requesta, który naprawił błąd, i ze zgłoszenia, które go wywołało. Jeśli słowa zgłaszającego podróżują razem z poprawką, połowa objawu jest już napisana.

Prośba o funkcję czy błąd wyjaśnia, dlaczego prawidłowe oznaczenie zgłoszenia decyduje o tym, kto je przejmuje. W Changeloop błąd zgłoszony przez widget staje się issue na GitHubie z etykietą bug, a wpis changelogu powstaje jako szkic ze scalonego pull requesta i czeka na zatwierdzenie przez człowieka, zanim zostanie opublikowany. Szablon release notes daje ten sam kształt wpisu do pisania ręcznego: objaw, zakres, okno, działanie.

FAQ

Co powinny zawierać release notes poprawek błędów? Każdy wpis powinien nazywać objaw, który widział użytkownik, kogo to dotknęło, od którego wydania lub daty, czy poprawka jest kompletna i co czytelnik ma zrobić, łącznie z “nic”.

Czy każda poprawka błędu powinna być w release notes? Nie. Wylistujcie te, które użytkownik mógł zauważyć, stracić na nich czas albo je obejść, a kosmetyczne lub wewnętrzne zgrupujcie na krótkiej liście “Drobne poprawki”. Changelog trzyma każdą poprawkę dla każdego, kto musi jej poszukać.

Jak napisać release notes o błędzie, który sami wprowadziliśmy? Powiedzcie, że to była regresja, nazwijcie wydanie, które ją wprowadziło, i wydanie, które ją naprawia, i powiedzcie czytelnikom, czy mogą usunąć obejścia. Proste stwierdzenie czyta się lepiej niż złagodzone słowa.

Jak sprawdzić release notes produktu, którego używam? Poszukajcie strony changelogu lub release notes podlinkowanej z menu pomocy, stopki albo dokumentacji produktu, a w projektach open source w zakładce wydań repozytorium.

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: Szablon notatek wydania