Continuous delivery of release notes

In Mews, on our journey towards continuous product delivery, we faced an unanticipated, but really important issue for our customers; promptly informing them about updates and new features of the system, also known as “release notes”. Solving this became a precondition for us going full steam ahead  with continuous delivery.

With a few deployments a week, it used to be pretty easy for the technical writing team to monitor deployments and manually publish the customer-facing release notes as required. However, since the majority of our products have already switched to continuous delivery (deployment per closed issue) it is no longer a simple task to manually publish and maintain release notes. Especially if a deployment happens at 2 AM 😫. Our customers are often pretty demanding, they want to know about updates to the system as soon as possible. We have even had a request to inform them in advance when we’re going to deploy a bug 🙈.

We decided that we’d like to automate this process as much as possible, our requirements were as follows:

• Technical writers should be able to prepare customer facing release notes in advance.
• If something hasn’t been deployed yet and has a release note, the release note should be publicly visible as “Soon to be deployed”.
• As soon as something gets deployed, we’d like to automatically publish the associated release note (move it from “Soon to be deployed” to “Deployed”).

The process

Our solution to this problem is to treat deployments and release notes just like any other entity in the system, and make it possible to manage them either automatically via API or manually from the admin area of our system. The page responsible for showing the release notes can be a simple, single-page application consuming the release notes from their API. In summary, the whole process works like this:

1. A developer moves issue X-123 to the stage In Review, while opening a pull request for it.
2. Based on this event, our issue tracker workflow generates a task for the technical writing team to create associated customer facing release note for issue X-123.
3. Technical writing team decides if the issue is worthy of a public release note. If it is, they will use the admin area of the system and prepare a suitable release note that our customers can understand, referencing issue X-123.
4. At this point, the release note appears on the public release notes page as “Soon to be deployed”.
5. Pull request is merged, triggering the integration server’s deployment workflow. This can happen while technical writing team is otherwise engaged, e.g. sleeping 😴.
6. Integration server performs the deployment and creates a new Deployment entity in the system via the API, with notes based on the commit messages. This deployment note also contains a reference to X-123.
7. Based on the deployment note, the release note is identified, marked as published and linked to the newly created deployment.
8. From that moment, the release note is visible on the public release notes page as “Deployed” with the associated deployment date and time.

Since our system holds all the data, it is straightforward to have an advanced release note page for all our products; with filters, categories and all the other bells and whistles. For our internal purposes, we have a separate page with all the deployments and their deployment notes (besides a Slack channel where it is also reported).

For some of our products, the deployment process is not 100% automated yet. Step 6 is therefore performed manually by the responsible engineer (they manually create the Deployment entity within admin area of our system).

Anyway, with the new workflow, life becomes much more easier for our technical writers, they seem to be very excited about it:

Reactive vs. proactive

If you’ve read the above carefully, you’ll see that there are no notifications to our users baked into the process. This is by design, the release note page is a reactive part of the whole picture. We first wanted to ensure that it’s working as expected and always up-to-date. The second part of the story, the proactive notifications to our users, will be the next step. After we figure out how to do that intelligently (we don’t want to bother users with many notifications daily for example), you can expect an explanatory follow up article 🙏.