Do You Really Need a Changelog?

Although we are true believers in the changelog here at Formcake, there are definitely questions you should ask yourself before implementing one. Though it's probably the right decision - there's a chance it might not be.

That being said, if you answer yes to any of those questions, fire up a changelog feed.

Are you developing a mobile app?

If you're developing a mobile app, you need to consider the manual update user scenario, where your users are vetting new versions of the app (a great practice) before deciding to upgrade. This is especially important if you're offering a sensitive app in something like messaging or finance - it's big that your userbase understands how the feature set and development of the app is evolving.

Do you have application SDKs?

Do you provide client-side libraries for interacting with your APIs? That's a great use case for keeping a changelog that keeps your users in-the-know about deprecated functionality and upcoming additions, without relying on stuff like in-terminal messages or update window dialogues, which are OK ad-hoc but should be done in addition to a more comprehensive changelog document (as reference).

Do you provide infrastructure APIs?

Here at Formcake we're very aware that people have embedded us deep into their own business workflows, sometimes in ways that can make changes difficult. In addition to keeping as stable a public API as possible, we know users rely on timely communication about any possible changes (communicated well ahead of time). The changelog, along with emails and in-app notifications, is an essential communication channel for this.

The Fundamental Question

Hopefully these questions have made you either reconsider offering a changelog or have you feeling even more certain in your decision to / not to.

What are some examples where maybe you don't need a changelog? Maybe you have a web application GUI where people convert JSON files to some other format - a changelog would be nice to show you're actively developing the product, but not essential. Or perhaps you're developing software that allows people to create generative art, which you're sharing on github: The changelog again could be helpful, but not required.

One of the fundamental questions to ask is: Does something depend on this?. Will something break somewhere if it isn't updated in step with how the software has changed? In the JSON file converter example, not really. The button could shift or there could be an extra step, but as long as you could perform the same fundamental action via the site you can adapt. But when someone else's code can break, there's more of a duty on your end to communicate (not just to provide a changelog, but at least that). A good indication: If you feel the need to use Semantic Versioning, you should probably have a changelog.

If you'd like an example of formatting, or what sorts of things to include, check out our own humble changelog. It's simple, but we like it.