Skip to content

Versioning

Clint Rutkas edited this page Dec 7, 2020 · 12 revisions

Versioning in PowerToys

  • What is it: How, where, and who revises versions on PowerToys
  • Authors: Clint Rutkas
  • Spec Status: Draft - 2020.11.16

Build process, Versioning and crash reports

Right now we have a few different spots we build from and we always increase version numbers in the source tree. When we try to look at crash reports, at times, what we see are actually test candidates and development builds since their version overlaps with a production version number. This leads to pains when we start trying to figure out what failed and how. To correct this, we will shift moving forward on what branches we use and when / who updates Version.props.

This document will also start addressing how we handle experimental and release candidates builds.

Terminology

We will stick to terminology used by both GitHub and what the APIs provide.

Release definition

GitHub uses the term Release and Pre-release. A release build is deemed what we are calling a stable quality build while pre-release will suite experimental and release candidate work.

Release Channel

A release channel is typically a feature or stability staged release. Microsoft Edge for example does canary, dev, beta, stable.

For PowerToys, we'll break it down in to stable, beta, dev, and experimental features.

Depending on your channel, that is what software updates you'll get. If you are running beta, you'll get prompted for beta updates. If you are on experimental, you'll get those

Tagging

GitHub does allow each release to be tagged. This can follow a pre-defined format that we can use to aid us in doing different release channels. Example v0.0.1-VideoConference could represent the Video conference experimental feature.

This tag will also be appended to the title and systray of PowerToys. (This work has not been done yet)

Version number definition

Our software includes .NET based software, we need to adhere to the versioning construct there. Version numbers consist of two to four components: major, minor, build, and revision. The major and minor components are required; the build and revision components are optional, but the build component is required if the revision component is defined. All defined components must be integers greater than or equal to 0. The format of the version number is as follows (optional components are shown in square brackets ([ and ]): This is from docs.microsoft.com

major.minor[.build[.revision]]

Property Value
Major 0
Minor 0
Build undefined (-1)
Revision undefined (-1)

PowerToys will follow the 0.minor[.build] format currently.

Suggested versioning structure

Once the update train code is able to parse the tags, we will be able to do more complex releases styles.

  • Experimental branches will be versioned based on the release they were based off of.
  • At no time can two releases ever have the same release number. Example v0.29.5 and v0.29.5-AwesomeNewFeature.

Matrix

This would be a breakdown of the 0.29 release and defining code around it.

Channel GitHub release type Tag Example tag Defining attribute Releases on GitHub Branch
Stable Release none v0.29.5 What is currently in production. Note how it is a higher build number than Beta. Yes Stable
Beta Pre-release Beta v0.29.2-Beta This is a release candidate for stable. This branch will be the base for Stable. Planned Beta
Dev none none v0.0.1 Active main development branch. This branch will be the base for Beta. No Master
Experimental Feature Pre-release Experimental v0.28.3-Experiemental or v0.28.3-AwesomeNewFeature Testing out a concept we don't fully know if it will make it into PowerToys Yes Feature/AwesomeNewFeature

Setting Versions.prop

Version.props will only be set by the build farm. This work is done.

Local / Development build versions

The application version will be v0.0.1 for local development. PowerToys will not actively check for a new version if it is v0.0.1 on start to not cause unneeded notifications.

Building Signed versions

We build the main development branch every day at noon. This will allow us to know if we have a build breaking issue. These since these will continue to be built against v0.0.1, even when we test a build, it won't impact our ability to see crashes for a public release. We can test against these internally without an issue and won't cause any issue for what build is what. When have a confirmed commit we want a signed build from, we will bring have the Stable branch based against this and set the variable in the pipeline to have a pre-build event actually set the version number in Versions.prop. This will make the only item able to set the file be on the farm.

We will increase the build number for any hot fix that goes into Stable, including if that is before a public release. This directly implies we could release a v0.15.2 without the public ever seeing a v0.15.0 or v0.15.1 due to finding a last minute critical bug.

We will only release signed builds to the channels.

Open questions

  • It would be nice to somehow validate the commit or timestamp the version number in. We could repurpose Revision as a timestamp. It would be [YY][DayOfTheYear][# build of the day] as a possibility since we can't leverage the commit hash. This would require additional work in the C++ area.