Do release notes make sense with continuous deployment?

Most likely, only some of your deployments will be worthy of an entry in the release notes. And I think that's perfectly reasonable.

I got an interesting question today from Peter Morloin, and wanted to answer it here. Shared with permission, and edited slightly for brevity and clarity.

Hi Jonathan! Hope you are doing well.

I work on several projects, but always try to create some form of changelog, release notes. As an independent freelancer, I may leave at a certain point in time, so it’s important to document these things (also for myself sometimes).

When the client’s context allows me to, I release/deploy regularly. So let’s say you work constantly on a project and want to (and can) release daily or even hourly. You split up the work into small changes and it works (no need to convince me this is possible).

Do you then still create release notes or a changelog? Does it still make sense to do so?

So I’m boiling this down to: Does it make sense to create release notes or a changelog if you’re doing continuous deployment? Specifically, if you’re an independent contractor, possibly working on several projects at once.

Now, I’m not sure that continuous deployment really makes much difference to the question of whether or not to write release notes.

I suspect the reason it feels like it’s relevant is that when doing less frequent, big-bang deployments, there’s virtually always something “interesting” to say about every deployment. So it just feels natural to write relelase notes for every deployment.

When deploying every small change, many of those changes will be completely invisible to the end-user, and would only overwhelm and/or confuse them if they read a release notes document for every “Renamed a variable” or “Added a column to a database table for later use” type of change.

So where I think this leaves us is with a more fundamental question:

Do we need release notes?

If the answer to this is “Yes” for infrequent releases, it’s probably also true for frequent releases. But then that leads to what’s probably the more interesting question, that I think gets to the heart of what Peter is asking:

Who are these relese notes for?

There can be many answers to this question. Sometimes on the same project. But this is ultimately what I believe should inform the question of release notes.

Are these release notes read by the end users? By sales or marketing folks within the company? Or is it a sort of FYI for internal stakeholders? Or does it just sit in the corner gathering dust?

Depending on which (if any) of these groups of people read the release notes, you can tailor your approach for that audience.

Most likely, only some of your deployments will be worthy of an entry in the release notes. And I think that’s perfectly reasonable.

If you have highly technical users, who truly want to know about every release, cosnider letting them see the git history (either directly, or copy the git log to a text file or web page).

Share this