Should Theme Changelogs Be Required or Recommended?

Published

January 7, 2013

8 Comments

If you’ve ever created a WordPress Theme, a WordPress plugin, or any software application for that matter, then you’ve probably created a changelog of sorts to help users and other interested parties (e.g. developers) understand exactly what was changed since the last version.

For those that aren’t quite sure, here’s a quick definition:

A changelog is a log or record of changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc. Some open source projects include a changelog as one of the top level files in their distribution.

As a programmer myself I know that the changelog has been a vital part of helping me to jump into someone else’s work, assist in development, or simply understand from a top-level perspective what is going on.

But, I’ll admit that I am the worst offender when it comes to updating my own changelogs and making them more than just a notice; that is, making them actually useful and consistent.

So when it was asked on the Make boards whether or not changelogs should be required or recommended I felt a twinge of shame as I know that, generally speaking, changelogs are a very good and necessary thing but if someone had required me to have them I would most likely balk.

Emil Uzelac puts is plainly:

In past months we noticed that Theme Authors either do not have the changelog or the changelog is very poor.

Here are some examples:

Changelog

Version 1.1 – Improvements

Version 1.1 – Minor Menu Changes

Version 1.1 – Font Size Change

Which does not really say anything at all. Or the changelog that was not updated in months.

Luckily for us we have trac, but it would be easier for us and for users to know what is going on when author releases a Theme.

So, what do you think? Should WordPress drop the hammer and require that changelogs be updated better and with more information and require a level of quality or should it simply continue to be a strong recommendation?

Are you guilty of being as bad as I am in terms of changelogs? Don’t leave me hanging as the only one!

There are 8 comments

January 7, 2013 #

Cais

I agree a “changelog” being included is a great idea for both themes and plugins, I am not certain it should even be a recommendation (although I would support it) at this time. There are more useful ideas regarding a changelog ideal that could be implemented than simply adding the file on its own. I made a similar comment on the “Make” site to this effect: http://make.wordpress.org/themes/2013/01/07/changelog-recommendation-or-requirement/#comment-26873
January 7, 2013 #

tsiger

I think changelogs should be required. I mean what other ways are there available to inform the end user about updates, fixes etc?
- January 7, 2013 #
  
  John Saddington
  
  it doesn’t seem to be too much to ask, right? although the issue is probably just as much about quality as it is the simple existence of it. how do you regulate “quality”?
January 7, 2013 #

boogah

I tend to favor plugins & themes that have changelogs. And if they’re dated, all the better. Mostly, I like to be able to tell if something is up-to-date or under active development.

WooThemes does a pretty good job of this on their themes. Take Canvas for example:

http://www.woothemes.com/changelogs/canvas/changelog.txt

I wish some of the other theme shops out there would do the same thing.
January 7, 2013 #

Tom McFarlin

Required. Though the average user won’t care much for them, keeping a log of the various changes – including the files – that have occurred over the course of development is useful.

It’s also handy for those site admins who have a number of sites to update but only want to do so by deploying the needed files without updating the entire theme (or plugin(s)).
January 7, 2013 #

JBrad

I think they should be required. It would also be sweet to possibly see the actual code changes from Github or something like that between releases. I’m also a huge fan when there are dev files of the unminified JavaScript files and LESS or SASS files.
January 8, 2013 #

DrewAPicture

I agree that changelogs should be required but not that they should require a specific level of quality. That is, unless those same requirements are carried over to the plugins repo.

I’d also argue that many users have no idea Themes Trac exists, let alone that changesets and diffs between changesets are available for public viewing. There is no more complete “changelog” for a theme than viewing a diff between release changesets. And I think educating users about those resources rather than requiring some specific level of quality in the changelogs is the better route to take.
January 8, 2013 #

DrewAPicture

.

How do you stay on top of your WordPress game?