Saturday, November 18, 2017

Keep a Changelog

Over the years developers have utilized several methods to keep user updated on the changes occurring with each application release. One approach is to email users upon each application update, this is intrusive and annoying for users. Another is to dump the git commits into a changelog.  Git commits aren't for user consumption :) The best approach is make the changelog an integral part of your application. The single source of truth that's ever present within the application.

Most developers are familiar with Markdown, as most of our repositories contain a readme.md file. Markdown is great at using minimal syntax to describe document layout. This makes it an ideal format to use for changelogs as well.

In a recent project we decided to follow the guiding principles from http://keepachangelog.com/en/1.0.0/. There are a variety of libraries in NuGet that can convert markdown to html, I utilized CommonMark. With a few lines of code I added an easy to follow changelog to my project.

Here is the core code. Note: the changelog.txt should be a changelog.md, but Github converts markdown to html, making it render in this post as html. In your code, this file would be a .md file not .txt.

No comments:

Post a Comment