Making a changelog work for you

In our most recent meeting we had an open floor. The subject of a changelog and standardizing the readme file was brought up. There have been several themes that are using changelogs but there are also several that are not.

What is a changelog

A changelog is a log or record of all the changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc.

As a theme author, a theme reviewer, or even a contributor to a theme this should matter because it gives you an idea of how the theme has changed and where things have changed as well. A well-cared and maintained changelog can be a very useful thing.

With that in mind what constitutes for a good changelog? Is it a novel explaining why certain changes were made? Or is it like a mobile app that simply says, “minor bug fixes” when you read the notes? There are a few things that will help in making a better changelog. They are:

• Listing versions in reverse-chronological order ( newest on top )
• One sub-section per version
• Group changes made per version
• Don’t dump commit logs ( if using version control )
• Emphasize deprecations

So let us take a look at a sample changelog:

== 1.2.3
* Added `trt_column_classes()` to better handle layout options
* Added `trt_sections()` to extend template parts
* Fixed CSS header height when there was no image set
* DEPRECATED `trt_body_styles()` in favor of `trt_body_clases`

== 1.2.2
* Fixed PHP array literal declaration for PHP5.4 and below
* Added `clearfix` to gallery rows 
* Changed phrasing of post byline for better context

== 1.2.1
* Added `trt.isFlickrStream()` to `main.js` to validate if input is a Flickr account or not
* REMOVED `content-welcome.php` as it was not being used

As you can see the above format is a great starting point and is taken from a combination of keepachangelog.com and the plugin’s readme standard.