# Formatting and best practices for creating a changelog

A changelog is a summary of the changes introduced in the application along with their business description. The main goal is to maintain a clear history of the application's development, organized in chronological order (newest first) and grouped into packages. The way to add a changelog to the application is described in: [Application documentation](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/aplikacja-biznesowa/dokumentowanie-aplikacji).

## Syntax and formatting

The changelog should be written in a unified and consistent structure and format based on headings and lists (entries are created using the [Markdown](https://www.markdownguide.org/basic-syntax/)).

Changelog structure:

{% stepper %}
{% step %}
H1 heading (#)

* Changelog title.
* Placed only once at the beginning of the file.
  {% endstep %}

{% step %}
H2 heading (##)

* Package name.
* It should include the application name and the package shipping date.
* Each package is a separate heading.
* Packages should be saved in order from newest to oldest (newest at the top).
  {% endstep %}

{% step %}
H3 heading (###)

* Entry category.
* Within one package, several category headings can be added (the categories are listed further below).
  {% endstep %}

{% step %}
Single change entry

* Placed as a bulleted list under the appropriate category.
* The syntax of a single entry should look as follows:

  * \[Jira number]\(Jira link)\[customer Jira number]\(customer Jira link)\* Change description \[name of the changed artifact(s) and its/their version after the change]

  \*The customer Jira number and link are optional, but it is worth adding them if the change is a response to a customer request.

<figure><img src="https://2112972046-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>Figure 1.</strong> Example changelog fragment in the edit window</em></p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Entry categories

* New features - new elements or functions in the application,
* Modifications - changes in existing functionality,
* Fixes - entries regarding the resolution of reported bugs,
* Configuration - entries with information about configuration parameters.

## Entry language and best practices

A good practice is to use business language and avoid technical details, i.e., describe the change in the context of value for the user. Example: "Fix in the amount formatter" can be described as "Improved credit amount formatting".

Before sending the package, remember to update the shipping date in the changelog. Example: ALXXXXXXXX - XXXX-XX-XX → AL20250101 - 2025-01-01 (format YYYY-MM-DD).

The changelog sent to the customer should reflect the actual state of the package as closely as possible. It should contain all entries related to the added features, modifications, or fixes.

## Example changelog template

Below is an example of the structure and a sample entry. Preserve the formatting and links.

{% code expandable="true" %}

```markdown
# Changelog for the 300plus application
<!--
## EXIMEEYYYYMMDD_300PLUS_APP - YYYY-MM-DD
 
### New features
- 1
- 2
 
### Modifications
- 1
- 2
 
### Fixes
- 1
- 2
-->
 
## EXIMEE20250901_300PLUS_APP - 2025-09-01
 
### Fixes
- [EXIMEE-1234](https://jira.consdata.pl/browse/EXIMEE-1234) Example change description [artifact: 300plus 1.02]
```

{% endcode %}

(The example above serves only as a template — in practice, save the list of packages and entries from newest to oldest, following the rules described.)