Formatting and best practices for creating a changelog

Changelog is a summary of 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 releases. The method of adding the changelog to the application is described in: Application documentation.

Syntax and formatting

The changelog should be written in a standardized and consistent structure and format based on headings and lists (entries are created using Markdown).

Changelog structure:

1

Header H1 (#)

• Changelog title.

• Placed only once at the beginning of the file.

2

Header H2 (##)

• Release name.

• Should include the application name and the release date.

• Each release is a separate heading.

• Releases should be recorded from newest to oldest (newest on top).

3

Header H3 (###)

• Category of entries.

• Within a single release you can add several category headings (categories are listed below).

4

Single change entry

• Placed as a bulleted list under the appropriate category.

• The syntax of a single entry should look like this:

  • [Jira number](link to Jira)[client Jira number](link to client Jira)* Description of the change [name of the changed artifact(s) and its/their version after the change]

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

Illustration 1. Example fragment of a changelog in the edit window

Entry categories

• New features - new elements or functions in the application,

• Modifications - changes to existing functionalities,

• Fixes - entries concerning the resolution of reported bugs,

• Configuration - entries with information about configuration parameters.

Language of entries and good 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 formatting of the loan amount."

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

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

Example changelog template

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

# 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 description of the change [artifact: 300plus 1.02]

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