Skip to main content

Changelog

Header

Level: Beginner

Keywords: changelog, monitor project changes

The result: implementation of changelog in a project, changelog available in the Lighthouse

Why use changelog in project?​

A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. Changelog is used to make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

How to set up project changelog?​

There are two options of creating and maintaining changelogs on projects. The first one is a bit more technical.

Using sdoc​

Create empty changelog.md file in your project repository, or in the desired packages repository.

Contributing​

The easiest way of adding a new record to the changelog is to run following command: sdoc rn-add -f changelog.md -i –o from the repository, where the changelog file is stored. This will guide you through the process of filling title, issue number and tags. Date and uuid will be filled in automatically. If you want the author to be also automatically filled, you need to add release_notes.author=dajana.snopkova to the .samo-cli file (located under: C:\Users\user.name).

A raw changelog looks like this. The newest record are first, oldest at the bottom of the file.

---note-begin---
uuid: kesjbtrm99aehxvjwbes
date: 2020-06-29
author: dajana.snopkova
title: Fix Water Defect Creation
issues: SAMO-4394
tags: bug-fix
---note-end---

Examples of tags : bug-fix, incompatibility, new, improvement...

If you are satisfied with the result, don't forget to commit and push your changes.

Using simple markdown​

Create empty about_en.md file in your base package repository under dynamic-app/packageName/resources. If you want to create changelog in multiple languages, use according suffix.

Link this file to menu.

Configuration of menu item for project changelog
    {
        "defaultPage": "dashboard",
        "defaultGuestPage": "login",
        "menu": {
            "items": [
            {
                "type": "page",
                "id": "login",
                "title": "Login",
                "icon": "samo-icons-social:person"
            },
            {
                "type": "page",
                "id": "dashboard",
                "icon": "samo-icons-action:dashboard"
            },
            {
                "type": "page",
                "id": "about",
                "title": "About application",
                "icon": "samo-icons-action:info-outline"
            }
            ]
        }
    }
Configuration of page about.json with project changelog
    {
        "title": "About application",
        "containerType": "container-fullwidth",
        "security": {
            "loggedIn": true
        },
        "module": {
            "type": "component:dynamic-app/modules/common/samo-markdown-module",
            "contentResource": "resource:help/about_{lang:}.md" //_{lang:} is used if changelog is written in multiple languages, otherwise simple file name can be used
        }
    }

Contributing​

Contributing to this kind of changelog is done manually by writing release notes as you wish. On GIS&Utility projects we usually follow this agreed structure:

Example of GIS&Utility project release notes
    # About Application

    ---
    ### Current version:
    Project DEMO: **1.14.0**   |   Application components: **8.22.4**   |    Installation date: **21.04.2023**   |

    ---
    # List of changes in information system DEMO

    ## Version 1.14.0
    _Installed:  TEST: 14.04.2023, PROD: 21.04.2023_

    ### General functionality
    - description of changes in dynamic-app

    ### Desktop client (LIDS Explorer)
    - description of changes in LIDS Explorer

    ### Agenda: Cadastre
    - description of changes in specific business agenda

    ...

    ---
    ## Version 1.13.0
    _Installed:  TEST: 14.03.2023, PROD: 21.03.2023_

    ### General functionality
    - description of changes in dynamic-app

    ### Desktop client (LIDS Explorer)
    - description of changes in LIDS Explorer

    ### Agenda: Cadastre
    - description of changes in specific business agenda

    ...