Changelogs

What is a changelog and why is it important?

Wikipedia defines a changelog as:

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.

While that explains the what, it does little to explain why it’s important.

Updating software is not an act that happens in isolation. It takes time and bandwidth, and there are no formal assurances that things will work the same way. That “three days later [when I] try to do something the way I’ve always done it [I won’t] be frustrated when it doesn’t work that way anymore.”

Further, a changelog is more than just a record of changes made to a project, a changelog is one of the few artifacts of the software development process that is visible to end users. It bears most of the responsibility to communicate to end users that the software is maturing by responding to changes in requirements and becoming more reliable.

This helps to explain why I was so frustrated with Twitter’s terse changelog above: it gave me no compelling reason to update my software, it gave me no argument as to why I should waste my time and data.

Changelogs for libraries

Changelogs are not only used in the application world, though. Those of us who use software libraries are familiar with relying on a changelog to suss out changes in implementations. Or as a good friend Boris put it:

X changed to Y then everything went to shit

Thoughtbot’s shoulda-matchers changelog is a great example of how wonderful a changelog can be when done correctly: it reliably points out both what has changed and why, clearly showing me the value in new versions of the software and guiding me towards using it correctly.

This kind of log works particularly well for libraries, but I do not believe it works well for applications—specifically web applications (which will be the main focus from this point forward).

Why does a web app need a different log than a library?

Libraries have a single audience: the developers who use their code. Library users have focus when looking at upgrades. They look for:

• What new pieces have been added to the library’s public API that I can begin to use?
• What parts of the public API have changed, requiring me to change my own software in order to upgrade?
• What parts of the public API have been removed, requiring me to find an alternative to the provided features

In contrast, a web application is interacted with by many different people or personas, each of whom have very different focuses when evaluating a changelog:

Internal Developers of the application:

i.e. the people who add to and maintain your codebase. This one’s easy because internal developers can take the same view as library users, viewing the rest of the application as an available public API to use or extend. This means they care about the same trio of “what’s new, what’s changed, what’s been removed” that we’ve already explored.

End Users:

i.e. the people who use your software for its intended application. End users care about:

• Infrastructure changes: improvements to speed, reliability, and scalability of existing functions
• Functional changes: adding or modifying product features
• Interface changes: visual redesigns, interaction changes, information re-architecture.

Operations/CloudOps: Provisioning

i.e. the people who provision the infrastructure/servers you deploy your application to. These folks care about:

• Do any codebase changes require scaling up/down the number of servers needed? e.g. introducing new poor performing code
• Are there new soft/hardware dependencies that need to be accomodated? e.g. a new library/gem/package, new Java/Ruby/Python/etc. version

There are many other personas not enumerated—such as Deployment, Security, Operations, Legal—each with even more disparate concerns. Because of this, I suggest redefining a changelog as

a log or record of changes made to a project, such as a website or software project, of importance to a single persona, usually including such records as bug fixes, new features, etc.

The fallout of this means creating and distributing distinct changelogs for each of the relevant stakeholders of your application. Each of these can be created independently of one another, and each one appropriately focuses on the concerns of one type of user. This prevents my most hated periodic internal debate:

Should I really write this down?

The answer is yes, you should write it down, along with all the other changes relevant to that particular stakeholder. And when you are providing your changelog publicly, such as for the Twitter app in the app store, make sure the changelog is relevant to the user who will be reading it.

This is part 1 of a series rethinking some of the non-development aspects of software engineering. The next one should focus on web app versioning and the subtle changes that this re-examined changelog idea has on it.