Šablona poznámek k vydání

Šablona

Vše v hranatých závorkách je zástupný symbol. Vše ostatní stojí za zachování, včetně pořadí: uživatelé hledají věc, která se jich týká, takže zásadní změny jdou první a interní práce se neobjevuje vůbec.

## [Produkt] [verze] - [datum]

[Jedna věta o tom, k čemu toto vydání slouží. Vynech u rutinních
vydání.]

### Zásadní změny
- [Co se rozbilo, co místo toho udělat a do kdy. Odkaž na kroky
  migrace.]

### Nové
- [Funkce, popsaná jako výsledek. „Připni filtr a znovu ho použij“,
  ne „přidán model SavedView“.]

### Vylepšeno
- [Co je rychlejší, jasnější nebo spolehlivější, a přibližně o kolik.]

### Opraveno
- [Symptom, který viděl uživatel, ne příčina v kódu.]

Pokud je sekce prázdná, smaž nadpis. Prázdná sekce Opraveno vyznívá, jako by nic nebylo opraveno, a nadpis bez ničeho pod ním nutí čtenáře myslet si, že se stránka nenačetla.

Stejná šablona, vyplněná

Takto vypadá se skutečným obsahem. Všimni si, že žádný záznam nezmiňuje soubor, větev, číslo tiketu ani osobu, a zásadní změna začíná akcí, kterou musí čtenář podniknout.

## Acme API 4.2 - 20. srpna 2026

Stránkování je nyní ve všech endpointech seznamů založeno na kurzoru.

### Zásadní změny
- `?page=` byl odstraněn ve všech endpointech seznamů. Použij
  hodnotu `nextCursor` z předchozí odpovědi. `?page=` vrací 400
  po 1. říjnu 2026. Kroky migrace:
  acme.example/docs/pagination

### Nové
- Uložená zobrazení v inboxu. Připni filtr jednou a znovu ho
  použij z bočního panelu.
- Webhooky lze nyní omezit na jeden projekt.

### Vylepšeno
- Endpointy seznamů odpovídají přibližně čtyřikrát rychleji na
  velkých účtech.
- Úloha exportu nyní hlásí postup místo toho, aby vypadala
  zaseknutá.

### Opraveno
- Pozvaní členové už nevidí prázdný přehled před prvním
  přihlášením.
- Časová razítka v exportech nyní respektují časové pásmo účtu.

Co patří do každé sekce

Zásadní změny

Jediná sekce s termínem uvnitř. Řekni, co přestává fungovat, co dělat místo toho, a datum, kdy to přestane. Pokud jsi ještě nerozhodl datum, sekci ještě nepublikuj: zásadní změna bez data je čtena jako naléhavá, a proud falešné naléhavosti je způsob, jak se lidé naučí ignorovat tvé poznámky k vydání.

Nové

Popiš výsledek, ne objekt, který jsi postavil. Test spočívá v tom, jestli řádek stále dává smysl někomu, kdo nikdy neviděl tvůj kód. „Uložená zobrazení v inboxu“ projde. „Přidán model SavedView a jeho migrace“ neprojde.

Vylepšeno

Kvantifikuj tam, kde to poctivě umíš. „Rychlejší“ má hodnotu skoro nulovou a čtenáři to slevují; „přibližně čtyřikrát rychlejší na velkých účtech“ stojí za přečtení a stanovuje očekávání, ze kterého se dá dovolat odpovědnosti. Pokud to nemůžeš změřit, řekni, co je lepší, způsobem, který lze vyvrátit.

Opraveno

Piš symptom, ne příčinu. Uživatelé hledají v těchto poznámkách věc, která se jim stala, takže „pozvaní členové přistávali na prázdném přehledu“ je dohledatelné a „opravena souběžnost v cache členství“ není.

Varianty

Čtyři sekce platí pro většinu vydání. Tři případy vyžadují změnu:

• Vydání mobilních aplikací. Obchody s aplikacemi zobrazují krátké pole novinek, takže začni jednou větou, kterou lze přečíst v seznamu obchodu, pak odkaž na plné poznámky. Recenze obchodu může také zdržet build o dny, takže poznámky datuj podle data vydání, ne podle data sloučení.
• API vydání. Verzuj poznámky stejně, jako verzuješ API, a umísti okno zastarání přímo do poznámek, ne jen do dokumentace. Konzument API čte poznámky přesně proto, aby zjistil, kolik času mu zbývá.
• Interní nebo administrátorské nástroje. Odstraň sekci Vylepšeno a slouč ji s Opraveno. Interním uživatelům záleží na tom, zda se změnil jejich pracovní postup, a dlouhá sekce Vylepšeno to zahrabává.

Čtyři pravidla, která je udržují čitelnými

1. Piš pro někoho, kdo nezná tvůj kód. Žádné názvy souborů, názvy větví, ID tiketů, názvy služeb, interní kódová jména.
2. Vynech cokoliv bez viditelného dopadu pro uživatele. Aktualizace závislostí, refaktoringy, změny CI a opravy překlepů patří do historie commitů, ne do poznámek k vydání. Nejčastější způsob, jak poznámky k vydání umírají, je zaplnění prací, kterou nikdo mimo tým nevidí.
3. Jeden záznam, jedna změna. Pokud řádek potřebuje slovo „a“ dvakrát, jsou to pravděpodobně dva záznamy.
4. Publikuj v rytmu, na který se lidé mohou spolehnout, i když rytmus je „kdykoliv vydáme“. Poznámky, které se objeví čtyřikrát za týden a pak dva měsíce vůbec, jsou brány jako šum.

Formát poznámek k vydání: části v pořadí

Formát je méně důležitý než pořadí. Ať používáš jakýkoliv styl nadpisů, čtenář procházející poznámky k vydání chce stejné čtyři věci ve stejném pořadí, a každý oblíbený formát poznámek k vydání je variací na to.

1. Nadpis, který říká, co se pro čtenáře změnilo, ne číslo verze. Verze jde menším řádkem pod ním, s datem v ISO tvaru (2026-08-29), aby se v každé lokalizaci četlo stejně.
2. Zásadní změny a cokoliv s termínem, první, i když je to malé. Pokud čtenář přestane číst po jednom odstavci, toto je odstavec, který potřeboval.
3. Co je nové, jedna položka na odstavec, s výsledkem v první větě a požadovanou akcí, včetně „žádná akce není potřeba“, uvedenou pokaždé.
4. Opravy a vylepšení, pak vše ostatní jako jednořádkový seznam dole. Aktualizace závislostí a interní změny zůstávají, protože jediná osoba, která je hledá, je opravdu potřebuje.

V Markdownu je to nadpis H2, tlumený řádek s verzí a datem, pak sekce H3 pro Zásadní, Nové, Vylepšeno a Opraveno. V e-mailu je to stejné pořadí s nadpisem jako předmětem. Ve widgetu changelogu je to nadpis a první odstavec, se zbytkem za odkazem. Šablona výše je tento tvar vypsaný celý.

Pro samotné psaní, ne tvar, se podívej na jak psát poznámky k vydání, které lidé skutečně čtou a osvědčené postupy poznámek k vydání, které stojí za zachování na blogu.

Časté otázky

Jak dlouhé by měly být poznámky k vydání?

Tak dlouhé, jak vyžadují změny ovlivňující uživatele, a ne delší. Vydání s jednou opravou chyby dostane dva řádky. Nafouknutí malého vydání, aby vypadalo podstatně, učí lidi přeskakovat ty velké.

Jaký je rozdíl mezi poznámkami k vydání a changelogem?

V praxi se tyto termíny používají zaměnitelně. Tam, kde je týmy rozlišují, poznámky k vydání popisují jedno vydání a jsou psané pro uživatele, zatímco changelog je průběžný seznam všech vydání v čase. Tato šablona pokrývá jedno vydání; changelog je to, co dostaneš, když je naskládáš od nejnovějšího.

Měly by mít poznámky k vydání číslo verze?

Jen pokud ho tvoji uživatelé mohou vidět. Čísla verzí jsou užitečná pro API, knihovny a instalovaný software, kde čtenář potřebuje vědět, na jaké verzi je. Pro nepřetržitě nasazovanou webovou aplikaci je datum užitečnější, protože to je to, co uživatel může porovnat s tím, co zažil.

Kdo by je měl psát?

Kdokoliv, kdo ví, co se změnilo, což obvykle znamená inženýra, který změnu sloučil, upraveno tím, kdo vlastní tón hlasu. Selhání jejich úplného předání někomu mimo práci jsou poznámky popisující tiket místo změny.