Versioning
- What is it: How, where, and who revises versions on PowerToys
- Authors: Clint Rutkas
- Spec Status: Draft - 2020.11.16
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.
We will stick to terminology used by both GitHub and what the APIs provide.
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.
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
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)
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.
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.37.5 and v0.37.5-Beta.
This would be a breakdown of the 0.37 to 0.39 release and defining code around it.
| Channel | GitHub release type | Tag | Example tag | Defining attribute | Releases on GitHub | Branch |
|---|---|---|---|---|---|---|
| Stable | Release | none | v0.37.5 | What is currently in production. Note how it is a higher build number than Beta. Any fix would be either cherry picked from the main branch or pushed back into main. | Yes | Stable |
| Beta | Pre-release | Beta | v0.37.2-Beta | This is a release candidate for stable. This branch will be the base for Stable. Any fix would be either cherry picked from the main branch or pushed back into main. | 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.0.373-Experimental or v0.0.373-AwesomeNewFeature | Testing out a concept we don't fully know if it will make it into PowerToys | Yes | Feature/AwesomeNewFeature |
You can see from the Experimental branches would be easily be identified what release they are based off of but cannot be mistaken for a main release.
Version.props will only be set by the build farm. This work is done.
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.
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.
- 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.