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.