Przykłady release notes na każdy rodzaj zmiany

Najlepsze przykłady release notes są krótkie, wskazują, kogo dotyczą, i mówią, co robić dalej. Poniżej jest jeden przykład na każdy rodzaj zmiany, który wydacie, razem z powodem, dla którego działa, żebyście mogli skopiować kształt i podstawić własne fakty.

Każdy przykład jest zmyślony, dla fikcyjnej aplikacji do fakturowania o nazwie Tidepool.

Co łączy dobre przykłady release notes?

Mówią użytkownikom, co się zmieniło i co, jeśli cokolwiek, mają z tym zrobić, ich słowami. Każdy rodzaj zmiany ma inne zadanie, więc kształt wpisu zmienia się między nimi.

Jak wygląda dobra nota o nowej funkcji?

Dobra nota o funkcji zaczyna się od tego, co czytelnik może teraz zrobić, i wskazuje plany lub role, które ją dostają. Pomija implementację.

Wysyłaj faktury w języku klienta. Możesz teraz wybrać język dla każdego klienta, a jego faktury, przypomnienia i strona płatności będą go używać. Francuski, niemiecki, hiszpański i portugalski są dostępne we wszystkich planach. Ustawisz to na stronie klienta w sekcji Preferencje rozliczeń.

Nagłówek to fraza, którą czytelnik powiedziałby na głos, a treść podaje zakres i miejsce. Czytelnik, który przejrzy tylko pogrubioną linię, i tak wie, co zostało wydane. Szersza metoda jest w jak pisać release notes.

Jak wygląda dobra nota o usprawnieniu?

Nota o usprawnieniu opisuje zmianę, którą czytelnik poczuje, i podaje zmierzoną liczbę, gdy taka istnieje. Bez liczby powiedzcie, czego czytelnik już nie musi robić.

Lista faktur ładuje się około trzy razy szybciej. Konta z ponad 5000 faktur czekały na listę około dziewięciu sekund. Teraz otwiera się w około trzy. Żadne działanie nie jest potrzebne.

“Usprawnienia wydajności” nie mówi czytelnikowi nic, a dziewięć sekund wobec trzech to twierdzenie, które da się sprawdzić w poniedziałek rano. Zamykające “Żadne działanie nie jest potrzebne” odpowiada na pytanie, które ma każdy czytelnik.

Jak wygląda dobra nota o poprawce błędu?

Nota o poprawce błędu opisuje objaw, który widział użytkownik, a nie przyczynę w kodzie, i mówi, czy musi cokolwiek powtórzyć. Poprawki, których nikt nie zauważył, mogą trafić na listę na dole.

Naprawiono: e-maile z przypomnieniem wysyłane dwa razy w dniu terminu. Niektórzy klienci dostawali dwa identyczne przypomnienia, jeśli termin faktury wypadał w ostatnim dniu miesiąca. To jest naprawione. Przypomnienia już wysłane nie są dotknięte i nikt nie musi niczego wysyłać ponownie.

Nagłówek zaczyna się od “Naprawiono”, żeby ktoś przeglądający mógł od razu sortować, a prawdziwy warunek (ostatni dzień miesiąca) następuje natychmiast po nim.

Jak napisać release notes o zmianie łamiącej?

Nota o zmianie łamiącej zaczyna się od daty i dotkniętej grupy, a potem w tym samym wpisie podaje migrację. Idzie na początek release notes, bo to jedyny wpis, którego czytelnik nie może przeoczyć.

Podpisy webhooków staną się wymagane 1 grudnia 2026. Od tej daty Tidepool przestaje wysyłać niepodpisane payloady webhooków. Dotyczy to każdego, kto odbiera webhooki bez sprawdzania nagłówka Tidepool-Signature. Aby przeprowadzić migrację, zweryfikuj nagłówek za pomocą sekretu w Ustawienia, Deweloperzy. Jeśli już weryfikujesz podpisy, żadne działanie nie jest potrzebne.

Data jest w nagłówku, więc przeżywa przeglądanie. Dotknięta grupa jest nazwana przez to, co robi, a ostatnie zdanie zwalnia ludzi, którzy już są w porządku, co zmniejsza obciążenie wsparcia. Poradnik o zmianach łamiących opisuje, jak zdecydować, czy zmiana się kwalifikuje.

Jak wygląda nota o poprawce bezpieczeństwa?

Nota o bezpieczeństwie mówi, co było ujawnione, czy ktoś to wykorzystał, kogo to dotyczy i co muszą zrobić. Trzymajcie ją rzeczową i spokojną.

Bezpieczeństwo: linki do resetu hasła mogły być użyte ponownie. Między 3 a 17 września 2026 link do resetu hasła pozostawał ważny po jednokrotnym użyciu. Nie znaleźliśmy śladów wykorzystania tej luki. Jest naprawiona, a wszystkie nieużyte linki do resetu zostały unieważnione. Jeśli prosiłeś o reset w tym okresie, poproś o nowy link.

Dokładne okno pozwala czytelnikowi ocenić własne narażenie, a zdanie o wykorzystaniu odpowiada na pierwsze pytanie, jakie każdy zadaje. “Potencjalny problem” brzmi jak zatajenie, więc napiszcie to, co wiecie.

Jak napisać zawiadomienie o deprecacji?

Zawiadomienie o deprecacji nazywa to, co jest usuwane, podaje twardą datę końca i wskazuje zamiennik.

Endpoint faktur v1 jest zdeprecjonowany i kończy działanie 1 marca 2027. GET /v1/invoices działa do 1 marca 2027, a potem zwraca 410 Gone. Użyj GET /v2/invoices, który zwraca te same pola plus currency. Odpowiedzi z v1 zawierają teraz nagłówek Sunset z datą końca. Przewodnik migracji porównujący obie wersje jest w dokumentacji.

Nazwa endpointu jest w nagłówku, bo dotknięci ludzie jej szukają, a zamiennik stoi obok usunięcia. Nagłówek Sunset mówi deweloperom, które wywołania nadal używają starej wersji. Dłuższe omówienie jest w deprecacji API.

Jak wygląda nota w sklepie z aplikacjami?

Nota w sklepie to dwa lub trzy proste zdania, bo większość ludzi czyta tylko pierwszą linię. Zacznijcie od zmiany, którą użytkownik zauważy.

Zeskanuj papierowy paragon, a Tidepool uzupełni kwotę, datę i sprzedawcę. Tryb ciemny podąża teraz za ustawieniem telefonu. Naprawiliśmy też awarię przy otwieraniu faktury z powiadomienia.

Najużyteczniejsza zmiana jest pierwsza, a poprawka wskazuje sytuację, w której aplikacja się zawieszała. Nie ma numeru wersji ani “poprawek błędów i usprawnień”. Release notes aplikacji mobilnych opisują zasady specyficzne dla sklepów.

Co powinna zawierać wewnętrzna nota wydania?

Nota wewnętrzna to wersja dla wsparcia i sprzedaży. Dodaje to, co pomija nota publiczna: co mówić i czego nie obiecywać.

Faktury wielojęzyczne wydane dziś (wszystkie plany). Wsparcie: klienci ustawiają język w Preferencjach rozliczeń, a istniejące faktury zachowują pierwotny język. Włoski jeszcze nie jest dostępny. Sprzedaż: funkcja jest otwarta dla każdego planu, więc nie przedstawiajcie jej jako powodu do przejścia na wyższy plan.

Każdy odbiorca ma własną opisaną linię, a nota wyznacza granicę (“Włoski jeszcze nie jest dostępny”), zanim klient o nią zapyta. Artykuł o wewnętrznych notatkach wydania opisuje format i kanały.

Jak wygląda zła nota wydania, przepisana?

Zła nota wydania wylicza, co zrobił zespół, zamiast tego, co dostaje czytelnik. Naprawia się ją, przenosząc rezultat na początek i usuwając wewnętrzne słownictwo.

Przed:

v3.8.1 Zrefaktoryzowano scheduler przypomnień. Naprawiono race condition w ReminderJob. Zaktualizowano bull do 4.12. Różne usprawnienia.

Po:

E-maile z przypomnieniem nie wychodzą już dwa razy. Klienci z fakturą z terminem w ostatnim dniu miesiąca mogli dostać dwa przypomnienia. To jest naprawione, a przypomnień już wysłanych nie trzeba wysyłać ponownie. Żadne działanie nie jest potrzebne.

Także w 3.8.1: zaktualizowano bull do 4.12.

Aktualizacja zależności spadła do linii w stopce, a race condition stał się objawem, który klient rozpozna.

Jak zachować spójność release notes między wydaniami?

Szkicujcie każdy wpis, gdy zmiana jest scalana, i niech człowiek zatwierdza go przed wydaniem.

Changeloop działa w ten sposób: tworzy szkic wpisu z każdego scalonego pull requesta za pomocą AI i wstrzymuje go do zatwierdzenia przez człowieka. Krok zatwierdzenia to miejsce, w którym redaktor stosuje powyższe reguły. Żeby najpierw ustalić format, zacznijcie od szablonu release notes, a to, jak wyglądają gotowe strony, zobaczycie w przykładach changelogów.

FAQ

Czym są nowe release notes? Nowe release notes to wiadomość publikowana razem z najnowszym wydaniem produktu, opisująca, co się zmieniło i co użytkownicy mają zrobić. Obejmują funkcje, usprawnienia, poprawki i zmiany łamiące.

Czym różni się release note od changelogu? Changelog zachowuje wszystko, dla każdego, kto chce pełnej historii. Release note wybiera z niego jedno wydanie, pisane dla czytelników, którzy rozstrzygają, czy ich dotyczy. Pełniejsze porównanie jest w changelog vs release notes.

Co oznaczają release notes? Release notes mówią użytkownikom, co zmieniło się w wydaniu. Wyrażenie obejmuje wszystko, co wyjaśnia, co zostało wydane, od tekstu “Co nowego” w sklepie z aplikacjami po stronę na witrynie firmy.

Jak długi powinien być każdy wpis release notes? Od dwóch do czterech zdań wystarcza dla większości wpisów: rezultat, kogo dotyczy i co zrobić. Zmiana łamiąca albo poprawka bezpieczeństwa może być dłuższa, bo potrzebuje daty lub migracji.

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, Przykłady changeloga