Release process and communication about software changes

Hi again, so alongside of looking at great examples of software release/change comms, @sauloperez and @Rachel and I also spoke about how we do the release process and the launch/communication to users needs we have alongside of the technical release process we have.

Here’s what came out of that discussion:


When communicating about changes we use a cascading approach, where the software team communicates to the instance managers (currently via the release notes), who then communicate to their users (via whichever channel, social media or newsletter or whatever).


There are 3 “types” of releases that we have (or would like to have):

  1. Small releases (small changes, bug fixes and tweaks) - version n.n.n
  2. Feature releases (beta or full, the launch of a feature e.g. subs beta) - version n.n
  3. New versions (like Spree 2.0 or a complete overhaul of something) - version n.0


We believe that each of these types require a different level of communication. They all should have release notes (is the theory), however:

  • Small releases only require a notification in Slack (channel TBD) announcing that it has gone live and linking to release notes.

  • Feature releases are worthy of a global blog post, talking about what has been launched, how it works, what the benefit for the user is, and even how we want to evolve it next (if there is additional functionality already slated for delivery in the pipe).

  • New versions require a project management-style approach, where there is a comms plan in place that determines how and when instance managers are involved/communicated to, and how the changes will be communicated to users. Likely this will include blog posts, but in the case were there are staggered rollouts the comms should be designed around this.


Here’s how we think our processes need to change to allow for this release communication:

  1. We start doing frequent, small releases. We don’t wait for things, we work like a release train were each week (as a suggestion of time) we will release the changes we’ve made regardless of size. If you miss the train this week you get on the one next week. <-- @sauloperez will look to implement this, and discuss with devs.

  2. For any feature release there must be a dev (the release manager) and a comms person assigned to create the blog post about the feature. That way the comms person understands what is being released, how it works, and how it benefits the users through the representative of the team who built it, and the message is crafted in a way that is user-friendly and well written. The comms person role can be shared across the comms/product team so that it’s not always @Jen having to write it. And instance managers can then use their own communication channels to broadcast the blog post (or translate it) to their users.

  3. We look at our project management process for large pieces of work like spree, ensuring that things like a comms plan and rollout plan are designed well in advance, that stakeholders are included in these plans and aware of their roles, and that it’s a simple thing to then implement the plan. The key point in here is that we do this at the beginning of the process so that implementation and launch is considered at the same time as we think about design of solution and build process.

OK, so that’s it. We’d like to implement this process, so please reply on here with your thoughts/worries/joy/inputs.

Ping @luisramos0 @maikel @lin_d_hop @Kirsten @Jen @Rachel @MyriamBoure @matt @kristinalim @EmilyRogers @lauriewayne1 @nick @MSFutureFarm for your thoughts.

Happy train


Looks great to me team :slight_smile: It would be excellent to work towards incorporating videos along with blogs, but that’s a nice-to-have/translation option for now.

I like that we’re just highlighting feature releases in this way - I think communicating bug fixes to the layperson is dangerous as they just see lots of bugs :bug:

1 Like

Love it!! just to add onto what @danielle perfectly explained is that in order to improve we will need to review our assumptions and processes around the delivery of software. key point: everything small!

Quite related: Brainstorming release notes to be better

Love it all. As an instance manager where there is no dev I have an additional request. It would be good to know when the train is coming. Even if its just a day ahead via a slack post? I regularly have users asking, “is it fixed yet?” with regards to bugs, and I’d like to be able to tell them without continually trying the thing out. And - I don’t know the solution to this but - one of the problems I have is that I don’t understand the release notes. They are often very technical (or at least more technical that me or other users), and I don’t understand the implications of the release. Is there a way to put a users perspective to them? ie - ‘this means that you will now be able to delete products without implications for creating new products’ or ‘this means you will be able to edit shopping carts again with errors’ … LOVE this plan.

1 Like

That’s very useful feedback @tschumilas. Right there is a success criteria for this: you spent less time dealing with repetitive testing tasks and you can better communicate improvements to your users :muscle:

@tschumilas We struggle with a similar problem of communicating the right bits to the right people. I believe that Sally hat some kind of spreadsheet where she tracked which user had which issue. And if you reference the issue number there, then you can check on Github if the issue is closed and in which release it’s included. The last step is a bit tricky. I recorded a little video how you find the release to a given issue.

  • visit the issue
  • go to the associated pull request
  • choose the last commit of that pull request
  • and find that little box telling you the version number if it’s included in a release

@maikel @tschumilas in France we deal with it as part of our support tool (which is how I’ve mostly done it in my previous companies). Here is how it works:

  • A user send an email about e.g. a bug
  • I answer to him and label the email “Bug in progress” thanks to the tool we use
  • Once the bug is fixed I transfer the status to “waiting next release” (but that is optional sometimes I’m lazy to do it :grin: it is a good practice however if you want the tool to calculate an SLA you want to communicate. But IMO we are not there yet with OFN, and I’m not even sure this is something we want)
  • Then, once our server has been upgraded, I just have to review all the request that have been tag in the tool with these two tags and I can send an email to the users to tell them it is fixed.

The rest of the user will only have the general communication Danni’s presented.

So this to me is not related to how to communicate “broadly” but how we deal with user requests on a 1to1 relationship. This is support :slight_smile: So we might need another topic for that.

1 Like