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 purpose is to maintain a clear history of the application's development, ordered chronologically (from newest) and grouped into release packages. The method of adding the changelog to the application is described in: Application documentation.
Syntax and formatting
The changelog should be written in a consistent and uniform structure and format based on headings and lists (entries are created using Markdown).
Changelog structure:
Header H1 (#)
Changelog title.
Placed only once at the beginning of the file.
Header H2 (##)
Package name.
It should include the application name and the package release date.
Each package is a separate header.
Packages should be recorded in order from newest to oldest (newest on top).
Header H3 (###)
Category of entries.
Within one package you can add several category headers (categories are detailed further).
Single change entry
Placed as a bulleted list under the appropriate category.
The syntax of a single entry should look as follows:
[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.
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 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 formatting of the loan amount."
Before sending the package, remember to update the package 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 package as much as possible. It should contain all entries related to added functionalities, modifications, or fixes.
Sample changelog template
Below is an example of the structure and a sample entry. Keep the formatting and links.
(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.)
Last updated
Was this helpful?