Formatowanie i najlepsze praktyki tworzenia changelogu

Changelog to zestawienie zmian wprowadzonych w aplikacji wraz z ich opisem biznesowym. Głównym celem jest prowadzenie przejrzystej historii rozwoju aplikacji, uporządkowanej według kolejności chronologicznej (od najnowszej) i pogrupowanej na paczki. Sposób dodania changelogu do aplikacji został opisany w: Dokumentacja aplikacji.

Składnia i formatowanie

Changelog powinien być pisany w ujednoliconej i spójnej strukturze oraz formacie opartym na nagłówkach i listach (wpisy tworzymy używając znaczników Markdown).

Struktura changelogu:

1

Nagłówek H1 (#)

• Tytuł changelogu.

• Umieszczony tylko raz na początku pliku.

2

Nagłówek H2 (##)

• Nazwa paczki.

• Powinna uwzględniać nazwę aplikacji oraz datę wysyłki paczki.

• Każda paczka jest osobnym nagłówkiem.

• Paczki należy zapisywać w kolejności od najnowszej do najstarszej (najnowsze na górze).

3

Nagłówek H3 (###)

• Kategoria wpisów.

• W ramach jednej paczki można dodać kilka nagłówków kategorii (kategorie zostały wyszczególnione dalej).

4

Pojedynczy wpis zmiany

• Umieszczony w formie listy punktowanej pod odpowiednią kategorią.

• Składnia pojedynczego wpisu powinna wyglądać następująco:

  • [numer Jiry](link do Jiry)[numer Jiry klienta](link do Jiry klienta)* Opis zmiany [nazwa zmienionego artefaktu/artefaktów i jego/ich wersja po zmianie]

  *Numer oraz link do Jiry klienta są opcjonalne, natomiast warto je dodać, jeśli zmiana jest odpowiedzią na zgłoszenie klienta.

Ilustracja 1. Przykładowy fragment changelogu w oknie edycji

Kategorie wpisów

• Nowe funkcjonalności - nowe elementy bądź funkcje w aplikacji,

• Modyfikacje - zmiany w istniejących funkcjonalnościach,

• Poprawki - wpisy dotyczące rozwiązania zgłoszonych błędów,

• Konfiguracja - wpisy z informacjami o parametrach konfiguracyjnych.

Język wpisów i dobre praktyki

Dobrą praktyką jest stosowanie języka biznesowego oraz unikanie szczegółów technicznych, czyli opisywanie zmiany w kontekście wartości dla użytkownika. Przykład: "Poprawka w formaterze kwoty" może być opisana jako "Poprawa formatowania kwoty kredytu".

Przed wysłaniem paczki należy pamiętać, aby zaktualizować datę wysyłki w changelogu. Przykład: ALXXXXXXXX - XXXX-XX-XX → AL20250101 - 2025-01-01 (format YYYY-MM-DD).

Changelog wysyłany do klienta powinien w jak największym stopniu odzwierciedlać faktyczny stan paczki. Powinny znajdować się tam wszystkie wpisy związane z dodanymi funkcjonalnościami, modyfikacjami lub poprawkami.

Przykładowy szablon changelogu

Poniżej przykład struktury i przykładowego wpisu. Zachowaj formatowanie i linki.

# Changelog dla aplikacji 300plus
<!--
## EXIMEEYYYYMMDD_300PLUS_APP - YYYY-MM-DD
 
### Nowe funkcjonalności
- 1
- 2
 
### Modyfikacje
- 1
- 2
 
### Poprawki
- 1
- 2
-->
 
## EXIMEE20250901_300PLUS_APP - 2025-09-01
 
### Poprawki
- [EXIMEE-1234](https://jira.consdata.pl/browse/EXIMEE-1234) Przykładowy opis zmiany [artefakt: 300plus 1.02]

(Przykład powyżej służy jedynie jako szablon — w praktyce listę paczek i wpisów zapisuj od najnowszej do najstarszej, stosując się do opisanych reguł.)