In the course of development, there often arises the question about what was changed during last server update, what tasks were completed and, most importantly, how to track in which commit the given changes were made. If you are doing not a small project and you are the one and only developer - you can always keep the whole structure and changes in mind. But when your project is filled with the variety of functionality and you are working as a part of a team, change logging is necessary. To track the changes in your project Change log is used.

Change log strict structure has no rules as such. Each developer or a group of developers describes it in their own way.

Below we will tell you a story about Change log building for python/django application, about the conclusions the team arrived at in the course of development process and about the advantages which we gained. The initial idea of doing change log was logging the list of changes in rst format while updating staging server. The question of versions naming raised immediately, as well as how to bind the version to repository git condition. As git provides a handy tool for commits tagging there were no problems with it. Tag is a link to a commit, but in a more pleasant format. To put a tag to a commit all you need is one command:

git tag -a <tag_name> <commit hash> -m “<tag message>”

To name the version we have chosen the format of the following structure n1. n2. n3.

n1 - release/production version of an application: thoroughly tested and checked stable version.

n2 - test/staging version of an application: A stable version with a certain set of new features which is sent to QA department for testing;

n3 - minor changes or bug fixing.

For example:


-  Add user models
-  Add login functionality
-  Add registration functionality
-  User login and registration testcase

Benefits which have been obtained with such a keeping of change log:

  • It is always clear which changes have been made from version to version of django application;

  • The ability to switch from version to version to debug particular functional;

  • The ability to change the state of repository to the state which corresponds to an earlier or later version.

How have we come to the given structure and defined the benefits? In the course of development you can very frequently come across the situation when QA is not aware of the latest changes. Of course, if communication in your team is well arranged, you are not going to have such problems, but it would be good to play it safe. A properly kept changelog demonstrates to QA which functional has been updated and what must be tested.

Sometimes in the process of development of a large project some part of the functional stops working properly. Although an application is covered by a big number of tests, some minor defects can still be found by QA department, and if server is often updated, defects not necessarily appeared during last changes.

Due to the fact that in change log every version corresponds to its own pointer of commit (the tag), developer can switch between versions at any moment, define where the problem has emerged, look at diff and find a solution. Also, with such a defect there is an ability to put application to a more stable version on the server. To do this you only need to switch between tags.

In the course of development and change log keeping it was decided to add several positive and useful points. Firstly, it was decided to add a link to the change log commit in the web version of git repository. Secondly, it was a pointer to the task identifier in the issue tracker. It allows to better track changes in development process, and every team member will be able to understand in the context of which task the given changes have been realised.

As you have already understood, change log is the changes journal of your project. You always know what was changed and when. Development process is always transparent for your customer, QA never asks odd questions, developer is always able to find the moment of a critical change, and Devops can always track and change the current version on a production server if needed.

Unfortunately, change log is to be kept manually now. At the moment, automation of change log is being worked on. Given functionality can also be achieved by means of git tag and commit message of a correct structure. One of the variants to use a plugin for Jenkins. Another variant is to write a library to collect commit messages among tags and record them in a file. Both these variants require testing and checking of their usability, but this is the subject for another article.

Useful links

  1. Wikipedia article about changelogs
  2. Good small article about changelog's structure
  3. GNU Project's standard for changelogs