Versioning
- What is it: How, where, and who revises versions on PowerToys
- Authors: Clint Rutkas
- Spec Status: Draft - 2020.09.01
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 canidates 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 foward on what branches we use and when / who updates Version.props.
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 build and a pre-release will be where we have something we feel is of good quality and hits a major milestone but not where we can integrate it into a stable release or we feel it needs additional testing/feedback.
Our software includes .NET based softare, 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 major.minor[.build] format where Major will be 0.
Version.props will only be set by the build farm.
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 will 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 befor 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.
- Stable – This is the branch we release our main release from. We will use tags to inform version number to the public which is what we already do currently.
- Pre-release - This will be the branch where we release pre-release variants of PowerToys. Once we hit stability, this will be how we do share prerelease builds to the public so we have a known stable build for everyone.
- We will do a full minor increase. This means if the current major release is
v0.10.0, this would bev0.11.0and the next major release would bev0.12.0 - In GitHub, we'll label these are pre-release software in the release as well so they will not prompt for new versions. Pre-release builds will only prompt for new pre-release builds.
- We will do a full minor increase. This means if the current major release is
- 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 possiblity since we can't leverage the commit hash.