Writing a ChangeWindows changelog

studio384
studio384
Sep 12, 2017 · 5 min read

Almost every week we see a Windows Insider Preview drop and that means that every week, you’ll see a new changelog appear on ChangeWindows. Writing such a changelog is simple, right? Read the blogpost, rephrase it in bullet points, and publish. That’s it. Right?

It’s not that simple, which is why I would like to walk all of you through the process of writing a changelog for ChangeWindows.

Step 1: a build is released

The process starts at the moment Microsoft releases a new build to Insiders. While the installations are running, the first phase of writing a changelog can begin: the first draft. The first draft is solely based on Microsoft’s announcement on the Windows Blog. It may sound simple to put this in some bullet points but it isn’t. Why isn’t it? Because there is one big problem: Microsoft isn’t always honest.

First of all, while subtle, Windows Insider Preview announcements do contain some PR that has no business in a changelog, this kind of nonsense (harsh, but it is what it is) needs to be filtered out. Secondly, Microsoft has a hand in announcing features after they were introduced. Every now and then, a blogpost appears announcing a feature, only for me to scratch my head because I wrote about the same exact thing the week before (they are often minor things). This also happens in reverse.

Third, app updates aren’t part of the OS. Microsoft often announces updates to apps in their blogposts as if it is part of that release. They are not, these app updates often will roll out later or already rolled out prior to the release of the new build. Fourth: sometimes app updates are part of the OS. Because why not. Every now and then an app is actually coupled to a certain build and then we have to write it down.

This isn’t a simple process to go through, especially not for the larger announcements, because it comes with a lot of fact-checking. Is something really new in this release? Is it in the release like Microsoft claims it is? Is this app coupled to this build or not?

While this is going, I usually have some machines, both physical and virtual install the new build while others stick to the one that came before. When I’m done with the blogpost, the first draft gets published. You can recognize drafts by empty headings. Drafts still include all categories that we report for.

Step 2: compare everything

Whether or not something actually is in the release and if an app is coupled to the build Microsoft released is of course not something that can be checked before I have an installation of my own. And that’s step 2: compare everything.

Based on the blogpost I will go through a number of places in Windows to check if it is there or not and figure out how things work (or not). There are also a number of locations I’ll go through no matter what, this includes (but is not limited to) the entire Settings app, Edge, Start, taskbar behavior, Action center and notifications, non-Store in-box apps (Defender, etc.) and the Control Panel.

This is something that takes hours.

This is actually something that has gotten more complex recently with the launch of the Skip Ahead feature as this requires even more installs of Windows.

This often is the start of more detailed changelogs beyond what Microsoft provides. This is the draft that we will release a couple of hours after a build lands.

Step 3: keep an eye on everything

More often than not, that second step doesn’t reveal everything. And where we fail, we can often trust on others to find other additions to Windows. When something pops up, the whole verification process begins again: was this added in the build that got released today? If not, when did it appear first? Is this even new at all? Is it an actual part of Windows?

At this stage, we’ve come to the point where we trust that our changelog is as detailed as possible. We’re now 2 days after the original release of said build. Sometimes another build has already surpassed it (especially late in development). This is the reason why we include this text in our vNext changelogs:

Note that when a new build is released, we usually wait a day or two to make sure we’ve covered everything before adding it to this page.

This is the final step. Remove all unused headers from the changelog, add these final changes and publish the final version. We also update the vNext changelog at this point.

vNext

vNext of course gets some additional attention after a changelog has been completed. We don’t just add the new changes to the bottom of the list. No. Of course not. We also take a look at all past changes. Sometimes one change contradicts another and that needs to be taken into account. Sometimes Microsoft removes a feature in a build that was added earlier in the same release. You don’t want to read “Adds support for <feature>” to read just a couple of lines further “Removes support for <feature>”. That doesn’t make sense. Sometimes Microsoft changes something multiple times, you don’t want to read the same change multiple times over and over again either. These are all small things that need to be taken care of.

And that’s just for new Insider Previews. Once a build moves to the public channels and the vNext changelog thus need no longer to change, we start to reorganize it, put changes to the same features together within their own categories. This too takes a while every time.


There you have it, and this isn’t even the full story. Bottom-line is: writing a changelog for ChangeWindows isn’t just using a template text, filling in the correct build number and quoting the whole announcement Microsoft puts up. There go hours in writing these things down. These changelog may appear fast, but when that first draft goes online, just a fraction of the work on it has been done. This isn’t something we publish after a couple of minutes to never revisit it again, changelogs will change over the course of days. So whenever you see ChangeWindows tweet “Info on build xxxxx for xxxxx is available”, it really is “A draft on build xxxxx for xxxxx is available”.

ChangeWindows

Changing Windows one build at a time

studio384

Written by

studio384

Look at me write stuff. Isn’t that interesting? It isn’t? Indeed. And yeah, I didn’t know what to write here so instead I’m wasting some seconds of your life.

ChangeWindows

Changing Windows one build at a time

More From Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade