Formatting and best practices for creating a changelog

The changelog is a summary of changes introduced in the application together with their business description. The main goal is to maintain a clear history of the application's development, arranged in chronological order (from newest) and grouped into packages. The way to add the changelog to the application is described in: Application documentation.

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

Changelog structure:

1

H1 heading (#)

• Changelog title.
• Placed only once at the beginning of the file.

2

H2 heading (##)

• Package name.
• It should include the application name and the package send date.
• Each package is a separate heading.
• Packages should be saved from newest to oldest (newest at the top).

3

H3 heading (###)

• Entry category.
• Within one package, several category headings can be added (the categories are listed further below).

4

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

Figure 1. Example fragment of the changelog in the edit window

Entry categories

• New functionalities - new elements or functions in the application,
• Modifications - changes in existing functionalities,
• Fixes - entries concerning 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 terms of value for the user. Example: "Fix in the amount formatter" can be described as "Improved loan amount formatting".

Before sending the package, remember to update the send 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 include all entries related to added functionalities, modifications, or fixes.

Example changelog template

Below is an example of the structure and an example entry. Keep the formatting and links.

# Changelog for the 300plus application
<!--
## EXIMEEYYYYMMDD_300PLUS_APP - YYYY-MM-DD
 
### New functionalities
- 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]

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