Did you know that YOU can also submit a blog entry,..after all, we are open source

Usually these blog entries review the PRs from last week. However, I’d like to talk about an important aspect of our ManageIQ repos,..and that is, changelogs. According to keepachangelog.com, “A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.”

Here at ManageIQ we follow the guiding principles and format as described at keepachangelog.com. This is no easy task and takes a concerted effort,…but the end result is meant to help you, the community user of ManageIQ.

The next line says this: “Unreleased - as of Sprint 67 ending 2017-08-21”
At the end of each Sprint Review, a PR is submitted that has updates for the end of sprint, in this case, work done in Sprint 67.

Taking a look back at the changelog, we see under the Sprint 67 header, a list of work that was Added, Changed, and Fixed. Under the Added sub-heading we see that the work is further broken down by team (or function). In this case; Platform, Providers, Reporting, REST API, and Services.

In each breakdown, we find the actual PRs that comprise the work done over the past 2-week Sprint period. As an example, under Added/Platform, you’ll find PR15819

An important (and highly stressed) component to the PR’s description is that it should be user-readable and not developer-speak. PR15819’s description says: “Don’t use secure sessions in containers”. A clear description is needed because you, as the community user, shouldn’t have to drill down into the PR to try and understand what is actually going on.

(Squirrel Moment) Let me take a minute to showcase the fine (no pun intended) work of our development team. If you take a look at PR15819, you’ll see we use multiple labels, have multiple reviewers, and use Sprint markers to define which sprint this enhancement came into.

Now back to our changelog. Further work is done on the changelogs once we have a release of ManageIQ,…such as the recent Fine-3 release. Once a release is announced, we go back into the changelog and now add a header for the Fine-3 release, as well as define which fixes are Released.

I do have a caveat. If you review our repos, you’ll find that most do not have a CHANGELOG.md file as just described. “But John, you just said…“,…I know, I know,…bear with us, we’re on a journey to get our changelogs up to snuff.

There’s really a lot more to say about this subject,..however, you can read all about it at,..you guessed it, keepachangelog.com