# 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](https://docs.eximee.com/budowanie-aplikacji/aplikacja-biznesowa/dokumentowanie-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](https://www.markdownguide.org/basic-syntax/)).

Struktura changelogu:

{% stepper %}
{% step %}
Nagłówek H1 (#)

* Tytuł changelogu.
* Umieszczony tylko raz na początku pliku.
  {% endstep %}

{% step %}
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).
  {% endstep %}

{% step %}
Nagłówek H3 (###)

* Kategoria wpisów.
* W ramach jednej paczki można dodać kilka nagłówków kategorii (kategorie zostały wyszczególnione dalej).
  {% endstep %}

{% step %}
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.

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2FV1FDOCaceVfUKne5gpe9%2Fimage2025-9-3_11-23-41.png?alt=media&#x26;token=3017dd53-f806-4667-b47b-b07a14e0da76" alt=""><figcaption><p><em><strong>Ilustracja 1.</strong> Przykładowy fragment changelogu w oknie edycji</em></p></figcaption></figure>
{% endstep %}
{% endstepper %}

## 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.

{% code expandable="true" %}

```markdown
# 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]
```

{% endcode %}

(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ł.)