Šablona poznámek k vydání: struktura a příklad

1. K čemu jsou poznámky k vydání

Poznámky k vydání (release notes) popisují, co přináší konkrétní verze aplikace. Tedy nové funkce, opravy, odstraněné části a hlavně kroky, které musí udělat uživatel nebo správce. Nečte je jen vývojář, ale i zákazník, podpora a konzultant.

V praxi bývá popis změn rozházený po commitech, pull requestech, Slacku a e-mailech. Podpora pak u nahlášené chyby neví, jestli ji zákazník ve své verzi už má opravenou. Zákazník se k popisu změn většinou nedostane vůbec.

2. Šablona poznámek k vydání

Šablona vychází z kategorií změn, které používá Keep a Changelog. Prázdné sekce klidně vynechte, pořadí ale u každé verze držte stejné. Čtenář si na něj rychle zvykne a najde, co hledá.

# <Název aplikace> <verze>
Datum vydání: RRRR-MM-DD

## Shrnutí
Jedna až dvě věty: co vydání přináší a koho se týká.

## Co musíte udělat
- Kroky před aktualizací nebo po ní (migrace, nové nastavení, restart).

## Nové funkce
- Nová funkce z pohledu uživatele (#číslo úkolu)

## Změny
- Změna chování existující funkce

## Opravy chyb
- Co nefungovalo a v jaké situaci (#číslo úkolu)

## Odstraněno a ukončená podpora
- Co v této verzi skončilo nebo skončí v příští

## Bezpečnost
- Opravené zranitelnosti (bez podrobností, které by šly zneužít)

## Známé problémy
- Co v této verzi zatím nefunguje a jak to obejít

3. Vyplněný příklad

Takhle může šablona vypadat po vyplnění pro menší vydání interní aplikace. Všimněte si, že každá položka popisuje dopad na uživatele, ne to, co se změnilo v kódu.

# Fakturace 2.4.0
Datum vydání: 2026-10-19

## Shrnutí
Hromadný export faktur do PDF a oprava zaokrouhlení DPH u dobropisů.

## Co musíte udělat
- Správce: po aktualizaci spusťte migraci databáze (npm run migrate).

## Nové funkce
- Hromadný export vybraných faktur do jednoho PDF (#412)

## Změny
- Seznam faktur se řadí od nejnovější

## Opravy chyb
- Dobropis s více položkami zaokrouhloval DPH o 0,01 Kč (#398)

## Známé problémy
- Export více než 500 faktur trvá déle než minutu

4. Co do poznámek k vydání patří a co ne

Dobré poznámky k vydání odpovídají na tři otázky. Co se změnilo, týká se to mě a musím něco udělat? Všechno ostatní patří do historie commitů.

5. Poznámky k vydání v Confluence, GitHubu a CI/CD

V Confluence si šablonu uložte jako šablonu stránky a pro každou verzi založte novou stránku. GitHub zase umí automaticky vygenerovat poznámky k vydání ze sloučených pull requestů od předchozího tagu. Jako podklad dobré, do jazyka uživatele je ale stejně musí přepsat člověk.

V CI/CD pipeline můžete poznámky sestavit z commitů mezi dvěma tagy a rovnou je poslat do AboutTheApp. Endpoint GET /integrations/installations/latest navíc vrátí verzi naposledy nasazenou u daného zákazníka a prostředí, takže víte, od které verze změny počítat.

1. 1

   Zjistěte nasazenou verzi

   GET /integrations/installations/latest s aliasem produktu, aliasem zákazníka a prostředím vrátí poslední instalaci.

2. 2

   Sestavte poznámky

   Z commitů nebo pull requestů mezi tagem nasazené verze a novým tagem připravte krátké shrnutí změn.

3. 3

   Odešlete verzi s poznámkami

   POST /integrations/versions s aliasem produktu, číslem verze a polem changelog založí verzi v katalogu produktu. U existující verze poznámky přepíše.

4. 4

   Zapište nasazení

   POST /integrations/installations přiřadí verzi konkrétnímu zákazníkovi a prostředí. CI klíč a hotové příkazy curl najdete v nastavení účtu v AboutTheApp.

6. Kde poznámky k vydání uvidí zákazník

Poznámky k vydání pomůžou, jen když je zákazník najde u verze, kterou sám používá. V AboutTheApp má každá verze v katalogu produktu svůj changelog. About box v aplikaci ukáže aktuální verzi i s jejími poznámkami a na About page je záložka Verze produktu s posledními verzemi. Když About boxu předáte verzi z buildu v atributu version, ukáže poznámky přesně k verzi, která běží. Musí ale existovat v katalogu a být veřejná nebo odemčená.

Provozujete aplikaci pro více zákazníků? Pak zákaznická About page ukazuje v záložce Prostředí a verze historii nasazení u konkrétního zákazníka, včetně poznámek ke každé nasazené verzi. Zákazník tak vidí změny ve své verzi, ne v té nejnovější.

Changelog verze v AboutTheApp podporuje základní Markdown: nadpisy, odrážky, číslované seznamy, tučné písmo, kurzívu, kód a odkazy. Šablonu výše do něj můžete vložit tak, jak je. About box v aplikaci ukáže začátek poznámek a odkaz na celé znění na About page.

Časté otázky