Szablon notatek wydania

Szablon

Wszystko w nawiasach kwadratowych to symbol zastępczy. Reszta jest warta zachowania, w tym kolejność: użytkownicy szukają rzeczy, która ich dotyczy, więc zmiany łamiące kompatybilność są pierwsze, a praca wewnętrzna w ogóle się nie pojawia.

## [Produkt] [wersja] - [data]

[Jedno zdanie mówiące, do czego służy to wydanie. Pomiń dla rutynowych wydań.]

### Zmiany łamiące kompatybilność
- [Co się zepsuło, co zmienić i do kiedy. Podlinkuj kroki migracji.]

### Nowe
- [Funkcja, opisana jako rezultat. "Przypnij filtr i użyj go ponownie",
  nie "dodano model SavedView".]

### Ulepszone
- [Co jest szybsze, jaśniejsze lub bardziej niezawodne, i mniej więcej o ile.]

### Naprawione
- [Objaw widziany przez użytkownika, nie przyczyna w kodzie.]

Jeśli sekcja jest pusta, usuń nagłówek. Pusta sekcja Naprawione czyta się tak, jakby nic nie naprawiono, a nagłówek bez niczego pod nim sprawia, że czytelnicy myślą, że strona się nie załadowała.

Ten sam szablon, wypełniony

Tak wygląda z prawdziwą treścią. Zauważ, że żaden wpis nie wspomina o pliku, gałęzi, numerze ticketu ani osobie, a zmiana łamiąca kompatybilność zaczyna się od akcji, którą czytelnik musi podjąć.

## Acme API 4.2 - 20 sierpnia 2026

Paginacja jest teraz oparta na kursorze na wszystkich endpointach list.

### Zmiany łamiące kompatybilność
- `?page=` zostało usunięte na wszystkich endpointach list. Użyj
  wartości `nextCursor` z poprzedniej odpowiedzi. `?page=` zwraca
  400 po 1 października 2026. Kroki migracji:
  acme.example/docs/pagination

### Nowe
- Zapisane widoki w skrzynce odbiorczej. Przypnij filtr raz i użyj
  go ponownie z paska bocznego.
- Webhooki mogą teraz być ograniczone do jednego projektu.

### Ulepszone
- Endpointy list odpowiadają około czterokrotnie szybciej na
  dużych kontach.
- Zadanie eksportu zgłasza teraz postęp zamiast wyglądać na
  zawieszone.

### Naprawione
- Zaproszeni członkowie nie widzą już pustego panelu przed
  pierwszym logowaniem.
- Znaczniki czasu w eksportach uwzględniają teraz strefę czasową
  konta.

Co wchodzi do każdej sekcji

Zmiany łamiące kompatybilność

Jedyna sekcja z terminem w środku. Powiedz, co przestaje działać, co zrobić zamiast tego, i datę, kiedy przestaje. Jeśli jeszcze nie zdecydowałeś daty, nie publikuj jeszcze tej sekcji: zmiana łamiąca kompatybilność bez daty jest odczytywana jako pilna, a strumień fałszywej pilności to sposób, w jaki ludzie uczą się ignorować Twoje notatki wydania.

Nowe

Opisz rezultat, nie obiekt, który zbudowałeś. Test polega na tym, czy linia ma sens dla kogoś, kto nigdy nie widział Twojego kodu. "Zapisane widoki w skrzynce odbiorczej" przechodzi. "Dodano model SavedView i jego migrację" nie przechodzi.

Ulepszone

Kwantyfikuj tam, gdzie możesz uczciwie. "Szybciej" jest warte prawie nic i czytelnicy to dyskontują; "około czterokrotnie szybciej na dużych kontach" jest warte przeczytania i tworzy oczekiwanie, z którego możesz zostać rozliczony. Jeśli nie możesz tego zmierzyć, powiedz, co jest lepsze, w sposób możliwy do obalenia.

Naprawione

Napisz objaw, nie przyczynę. Użytkownicy szukają w tych notatkach rzeczy, która im się przydarzyła, więc "zaproszeni członkowie lądowali na pustym panelu" jest odnajdywalne, a "naprawiono wyścig w cache członkostwa" nie jest.

Warianty

Cztery sekcje obowiązują dla większości wydań. Trzy przypadki wymagają zmiany:

• Wydania aplikacji mobilnych. Sklepy z aplikacjami pokazują krótkie pole nowości, więc zacznij od jednego zdania, które można przeczytać na liście sklepu, a potem podlinkuj do pełnych notatek. Recenzja sklepu może też wstrzymać build na dni, więc datuj notatki datą wydania, nie datą mergowania.
• Wydania API. Wersjonuj notatki tak samo jak wersjonujesz API, i umieść okno deprecacji w samych notatkach, a nie tylko w dokumentacji. Konsument API czyta notatki właśnie po to, by dowiedzieć się, ile czasu mu zostało.
• Narzędzia wewnętrzne lub administracyjne. Usuń sekcję Ulepszone i połącz ją z Naprawione. Użytkownikom wewnętrznym zależy na tym, czy ich workflow się zmienił, a długa sekcja Ulepszone to grzebie.

Cztery zasady, które utrzymują to czytelnym

1. Pisz dla kogoś, kto nie zna Twojego kodu. Bez nazw plików, nazw gałęzi, identyfikatorów ticketów, nazw usług, wewnętrznych kryptonimów.
2. Pomiń wszystko bez widocznego dla użytkownika efektu. Aktualizacje zależności, refaktoryzacje, zmiany CI i poprawki literówek należą do historii commitów, nie do notatek wydania. Najczęstszym sposobem, w jaki umierają notatki wydania, jest wypełnianie ich pracą, której nikt spoza zespołu nie widzi.
3. Jeden wpis, jedna zmiana. Jeśli linia potrzebuje słowa "i" dwa razy, to prawdopodobnie są dwa wpisy.
4. Publikuj w rytmie, na którym ludzie mogą polegać, nawet jeśli rytmem jest "kiedy tylko wydajemy". Notatki, które pojawiają się cztery razy w tygodniu, a potem nie przez dwa miesiące, są traktowane jako szum.

Format notatek wydania: części, w kolejności

Format ma mniejsze znaczenie niż kolejność. Niezależnie od stylu nagłówków, czytelnik przeglądający notatki wydania chce tych samych czterech rzeczy w tej samej kolejności, a każdy popularny format notatek wydania jest tego wariantem.

1. Nagłówek mówiący, co się zmieniło dla czytelnika, nie numer wersji. Wersja idzie w mniejszej linii poniżej, z datą w formacie ISO (2026-08-29), by czytała się tak samo w każdym lokalu.
2. Zmiany łamiące kompatybilność i wszystko z terminem, najpierw, nawet jeśli małe. Jeśli czytelnik przestaje czytać po jednym akapicie, to jest akapit, którego potrzebował.
3. Co jest nowe, jeden element na akapit, z rezultatem w pierwszym zdaniu i wymaganą akcją, w tym "nie wymaga akcji", podaną za każdym razem.
4. Naprawy i ulepszenia, potem wszystko inne jako jednoliniowa lista na dole. Aktualizacje zależności i zmiany wewnętrzne zostają, bo jedna osoba, która ich szuka, naprawdę ich potrzebuje.

W Markdown to nagłówek H2, przygaszona linia wersji i daty, potem sekcje H3 dla Łamiących, Nowych, Ulepszonych i Naprawionych. W e-mailu to ta sama kolejność z nagłówkiem jako tematem. W widgecie changeloga to nagłówek i pierwszy akapit, z resztą za linkiem. Szablon powyżej to ten kształt zapisany w całości.

O samym pisaniu, a nie kształcie, przeczytaj jak pisać notatki wydania, które ludzie naprawdę czytają i dobre praktyki notatek wydania warte zachowania na blogu.

Częste pytania

Jak długie powinny być notatki wydania?

Tak długie, jak wymagają tego zmiany wpływające na użytkowników, i nie dłużej. Wydanie z jedną poprawką błędu dostaje dwie linie. Rozdmuchiwanie małego wydania, by wyglądało na znaczące, uczy ludzi pomijać wzrokiem te duże.

Jaka jest różnica między notatkami wydania a changelogiem?

W praktyce te terminy są używane zamiennie. Tam, gdzie zespoły je rozróżniają, notatki wydania opisują pojedyncze wydanie i są pisane dla użytkowników, podczas gdy changelog to bieżąca lista każdego wydania w czasie. Ten szablon obejmuje jedno wydanie; changelog to to, co dostajesz, układając je od najnowszego.

Czy notatki wydania powinny mieć numer wersji?

Tylko jeśli Twoi użytkownicy mogą go zobaczyć. Numery wersji są przydatne dla API, bibliotek i zainstalowanego oprogramowania, gdzie czytelnik musi wiedzieć, na jakiej jest wersji. Dla ciągle wdrażanej aplikacji webowej data jest bardziej przydatna, ponieważ to jest to, co użytkownik może dopasować do swojego doświadczenia.

Kto powinien je pisać?

Ktokolwiek wie, co się zmieniło, co zwykle oznacza inżyniera, który zmergował zmianę, edytowane przez kogoś, kto zna głos marki. Trybem awarii oddania ich całkowicie komuś spoza pracy są notatki opisujące ticket zamiast zmiany.