Generate changelog from git commits and integrate with Sphinxdoc


0.00 avg. rating (0% score) - 0 votes

Git logo

For another personal project (that I can’t talk about for the moment ;-)), I wanted to have a Changelog file to get a better following of the infrastructure evolution (configuration management, scripts…all under git). Of course the documentation is very important, but when you do not write it at the same time you’re building the infrastructure, it may be complex to remember each little things you’ve done. That’s why a Changelog can help to understand how the infrastructure has been built step by step.

I’m going to show you how I achieved it. This is not a generic system, but brings you the keys to adapt for your needs.

The goal

That’s why I wanted to have a Changelog up to date. But…have you ever tried to maintain by hand a Changelog? I pretty sure yes and you know this is boring! That’s why I wanted something automatic. More than that, I wanted to have direct links to my ticketing system on hashtags detection.
A few weeks ago, I watched a video on a Meetup about how to level up with git (one of the best practices and why). After adopting and adapting a bit this, I decided to have commits comments format like that:

With this kind of comments, I was able to generate something to help me to build the Changelog. In the same video, they were talking about a custom Ruby script which cloud do the job. However a big part of my tools and infrastructure are written in Python and wanted to have a maintained tool in Python to do it.

The tool

After a little bit of research, I’ve found gitchangelog tool. This is a light Python script installable via pip which will generate a markdown file from git logs. That was exactly what I was searching for. But as you know, it doesn’t work out of the box because I already have decided of the format I wanted.

So I adapted the configuration (.gitchangelog.rc) to make it work with the wished log format. The configuration looks like this:

As you can see, it’s only regex. You can read the full commented lines in the configuration file (shrinked here) for a better understanding of what you can do. Subject is separated from the body, they both have their own regex and a link to the ticketing system is automatically generated with ‘#INF-‘ prefix. I do not wanted the body information appearing in the Changelog, so I substituted the content with nothing.

I was now able to generate markdown by using gitchangelog command. There, I achieved the first step.

Integration with sphinxdoc

To make it better, I wanted to have an integration with Sphinxdoc as I’m using it for the project. I updated so the Makefile to generate the changelog before making the documentation like that:

The result

The result looks like this:


Cool isn’t it? No more manual Changelog to do and it’s nicely integrated in Sphinxdoc 🙂

Avoid mistakes with hook

To get a good Changelog without issues, I also needed to have a hook on the server side to check and validate the subject. The git server I’m using for the project is Stash and I’m using an already existing hook to do the job. This is not perfect but it works with this regex:

You may need to develop a custom hook on other git server.

Hope you’ve enjoyed reading

Author: Deimos

I'm a passionate DevOps. I love transmit my skills and I love working on high availability infrastructures/technologies.


  1. Hi Deimos,

    i am trying to do the same as u, but only with github.
    Any chance u can help me out with some webhooks and formatting sphinx ?
    My mail address is added to the post.

    Kind regards,
    Jelle van Leeuwen

Laisser une réponse