How to keep a proper changelog

Developing a WordPress plugin? Nice. You’ve probably already read about how to find a hook, the importance of WordPress coding standards and how you can make sure your plugin’s performance is top notch (If you haven’t, you should). But do you have a good changelog? Having a good changelog is important and will not only benefit others but you as well.

A good changelog should be/have:

Clear and complete

Your changelog should be a highly organized file. Use bulletpoints for your changes, group them between features and bugfixes. Make it clear what you’ve changed, one change per line. And finally make sure your changelog is complete. It’s easy to forget to put a change or bug fix in your changelog. Therefor be sure to update the changelog everytime you commit a change to the repository.

Small related side note, did you fix a security issue? Be sure to include this in your changelog! It sucks that you had a vulnerability in your code but it’s very important that you let people know you fixed it and what release includes the fix!

Include dates

Include release date for each release you do. People like to know when a release was done.

List releases in reverse-chronological order

Make sure your latest release is at the top of your changelog.

Publicly available

Your changelog should be publicly available. If you’re hosting your plugin in the WordPress.org repository it already is. But if you’re selling a WordPress plugin from your own website, the changelog file will be in a zip that’s only accessible to clients. In this case you should have a page up on your website that includes the changelog and obviously, keep it up to date.

Markdown to HTML

One of the things that annoyed me with my premium plugins is every time I released an update I had to update the changelog page on my website. My changelog is a markdown file and my online page is a HTML page. I want the page on my website to have at least some default formatting so I had to copy and paste each markdown line to a HTML list item. And I had to do this every release. Boring repetitive work, so about time I (semi) automated that process. The snippet below will format your changelog to HTML. From now on I can simply open that script and copy the output in my WordPress editor. Makes me a happy developer, done in seconds and no more boring copy-pasting.

Changelog format

Because my script was build for my changelog, it will only work if you keep the same changelog format as me. So format your changelog as the snippet below or feel free to modify the script to make it work for your own changelog formatting.

Be sure to click the ‘view raw’ link as GitHub uses markdown format to make it look pretty.

viewraw

The script

This is the script I’ve put in the root of my development WordPress install. Feel free to modify it to your needs.

Please, don’t put this script on live websites.

Make sure you’ve got a good changelog, you’ll thank yourself for it later. I hope this helps any one out reading this. Missing something? Found a problem? Have an improvement? Please let me know in the comments below.

Related Posts

Powered By Related Posts for WordPress
Click Here to Learn More About Related Posts for WordPress

2 thoughts on “How to keep a proper changelog

  1. Well, better than nothing indeed. But the common format for changelog headers is “1.2.3-rc1 (2015-04-30)\n” or alternatively square brackets etc. Local date formats are very 90s.

Leave a Reply

Your email address will not be published. Required fields are marked *