Every software release needs to have release notes. End users need to be able to understand what it is that they are upgrading to and any associated risks, or risks mitigated by upgrading and receiving bug fixes. Across the board proprietary and open source software projects either hit or miss on delivering decent release notes. During MidCamp I decided to help fix that problem for Drupal.org projects.

What makes good release notes?

Probably the first question is: what makes good release notes? It depends on the audience of the product and scale of the product. As an Android user, I'm used to my perpetual weekly "Bug fixes and improvements" message. As a developer that kills me because I want to know. But for my wife, she probably doesn't care or read the reason why there is an update, she just lets the auto-updater run.

Take a look at Spotify versus Buffer, for instance.

Spotify, being a music app, has a more general audience and has a larger user base. Buffer is for social media savvy and marketing oriented users, it's base is also more niche. Release notes should educate the end-user about what they are getting into and what problems will be fixed. Maybe your end audience does not care that much (Shopify) so you just maintain your internal release logs and keep an eternal generic release notes message up. Or you make a blend, like Buffer. Or you go all out with technical details and documentation like Drupal, WordPress, and others.

Making better Drupal module release notes

When a module rolls out a new release and the contents are just "some bugs fixed" or no content, I get sad inside. I know most of us are maintaining Drupal modules on the side without true sponsorship or business-oriented motivation. But, as maintainers, or job is to ship dependable software. Dependable software doesn't mean just committing bugs and release fixes. It means communicating those to our end users.

If you look at the Drupal 8.5.0 release notes, you see a lot of detail. There has to be! It's Drupal core! Drupal core has release managers and product managers that can work to generate these notes that communicate important updates, major bugs fixed or any features added, and any known issues. This allows for proper evaluation of an incoming release and the impact it will make on operations. It's a large product with a technical and management level audience.

Now, let's look at another module that has nearly 150,000 sites using it - Superfish. The 8.x-1.2 and 8.x-1.1 release notes look like a quick manual copy and paste grab from the commit log. Since most module maintainers follow the standard commit message practices, I could have just reviewed the commit log and reviewed for my self. I have no context on what those issues were for or if they are bugs or features. Please note: this is no knock on the maintainer mehrpadin. I am just making an observation and stating my motivation. Release notes take time to curate, and most open source maintainers use their spare time to manager issue queues. It's why we have a documentation problem as well, and a whole other topic.

Next let's check out the Drupal Commerce release notes, which has had two format changes since 2.2. If you look at the 8.x-2.2 release notes, we did the same as Superfish - a blob of text which was our commit log and requires manual work to learn more about the included changes. In 8.x-2.4 there was a change. Changes link to their proper issue queue and we link to the users who helped. There's a tool for this, and I'll cover that next. In 8.x-2.5 we have an even better format, in my opinion. Not only are issues linked, but they are grouped by the type of fix: bug, feature, task. An end user of Drupal Commerce can quickly evaluate if the release is mostly features or bug fixes and determine possible impact. There's a tool for this, too. The one I worked on at MidCamp.

There are tools for that

Through means now lost to memory, I came across the Git Release Notes for Drush project. It takes the commit log of a Drupal.org module and turns it into release notes which automatically link to the issue and users. The drush rn module was used to generate the Drupal Commerce 8.x-2.4 release notes. I also use it heavily on all of my other modules. However, after a few years of use, I wanted something a little bit more. I didn't want to keep using a Drush command (especially since this pre-Drush 9 command, back in Drupal 6 days.) 

I have a Drupal.org CLI tool that I use for my day to day maintainership and contribution items. While at MidCamp I hacked on a drupalorg maintainer:release-notes command. It's heavily based off of the GRN Drush command. It compares tags, takes the commits, does some processing, makes pretty release notes.

The command provides some additional features. I want to thank Mike Lutz who gave some ideas! Having issues broken apart by their issue type makes it more readable and understandable. I also wanted to call out our contributors, because they are essential to our project.

The end result provides a nice release note summary. I would like to find even more improvements that give Drupal.org project maintainers the ability to create insightful release notes without the management overhead.

You can find the project at https://github.com/mglaman/drupalorg-cli. Currently, it's only available via a global Composer install, which can cause conflicts with Drush. I'm working on providing a Phar for download.