Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 101 additions & 57 deletions specs/Deployment/MSIXPackageVersioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,17 +255,12 @@ version 89 and 92+ are under development.
* Compatible with MSIX
* Does not align with common practices and expectations across the industry

***Recommendation:*** Option B.

Option B provides a stronger degree of compatibility and risk management than Option A (Major
version) while still affording a reasonable way for developers to adopt updates.
***Recommendation:***
For all 1.x, option B was selected, while waiting on tooling to be able to handle the rapid development we want.

Windows App SDK aspires to adopt Option A (Major version) but more tooling and infrastructure is
desired before making that level of guarantee. Option B provides a good balance of rapid
development and compatibility assurance.

Option A can (and will) be adopted in a future release (no sooner than 2.0) once tooling and
infrastructure are ready to embrace it.
## Decision 2.1: Breaking Change for version 2.x
Starting 2.x, option A is selected. This will allow for better stability for external developers. They will
know that as long as they are on the same Major, then things will be compatible.

### 2.2.1. Current practices in Microsoft-authored Framework packges.

Expand All @@ -289,8 +284,10 @@ Windows App SDK 0.5 adds a "-preview" tag to the package Name.

Windows App SDK 1.x adds a -channel# tag (e.g. "-preview1") to the package name.

***Do we need a shorter tag?*** "-preview1" adds 9 characters to package Name. "-experiental1" adds
13 characters. Package Name is restricted to 50 characters maximum.
Windows App SDK 2.x goes back to just a "-preview" tag on the package Name.

***Shorter Tags as needed*** "-preview" adds 8 characters to package Name. "-experiental" adds
12 characters. Package Name is restricted to 50 characters maximum.

**Option A: `-preview`**
**Option B: `-pre`**
Expand Down Expand Up @@ -340,10 +337,12 @@ Examples are provided for the following theoretical versions...
|D|NPPP.E.B.0|8001.154.123<br>2003.364.123<br>17014.3944.123.0|Minor Patch Elapsed Build|Minor max is 64<br>Patch max is 999<br>Build max is 65535|
|E|NPP.E.B.0|801.154.123<br>203.364.123<br>1714.3944.123.0|Minor Patch Elapsed Build|Minor max is 99<br>Patch max is 99<br>Build max is 65535|

***Recommendation:*** Option D with Epoch=January 1, 2021.
***Recommendation:***
For 1.x, Option D was selected.
For 2.x, Option A is selected.

Option A works for a simple release strategy but doesn't work when there's regular
(e.g. daily) builds.
Option A works is the simplest to release and understand. As long as we don't hit 999 Patches for the same Major.Minor,
then we will not run out of space in the DDLM package (more on that in 2.5)

Option B worked for WinUI 2.x and Windows App SDK 0.5 but is too limiting given it can't support
Minor versions beyond 6. It's also a complicated encoding scheme with date injected between Minor
Expand Down Expand Up @@ -397,7 +396,7 @@ following naming patterns release 0.x...

* WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>.<rminor>[-tag]`
* WARmain: `Microsoft.WindowsAppRuntime.Main.<rmajor>.<rminor>[-tag]`
* WARddlm: `Microsoft.WindowsAppRuntime.DDLM.<major>.<minor>.<build>.<revision>-<shortarchitecture>[-shorttag]`
* WARddlm: `Microsoft.WindowsAppRuntime.DDLM.<rmajor>.<rminor>.<build>.<revision>-<shortarchitecture>[-shorttag]`

and release 1.x...

Expand All @@ -406,22 +405,62 @@ and release 1.x...
* WARsingleton: `MicrosoftCorporationII.WinAppRuntime.Singleton[-shorttag]`
* WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<build>.<revision>-<shortarchitecture>[-shorttag]`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be consistent in our language and Semantic Versioning language. This field if the Patch version.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be consistent in our language and Semantic Versioning language. This field if the Patch version.

Yes - when we're discussing Semantic Versioning.

DDLM's package Name includes the MSIX package version, which uses DotQuadNumber terminology (or more specifically, as expressed in PACKAGE_VERSION and PackageVersion) which is a 4 part number with fields named Major, Minor, Build and Revision.

To avoid confusion that's why WARfwk+WARmain package Names including the WinAppSDK release's major+minor fields reference to them as <rmajor> and <rminor>, as defined on line 422

NOTE: rmajor/rminor are the release version, major/minor/build/revision are the MSIX package version


and release 2.x, when Breaking Change Boundary changed to 'Major' version...

* WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>[-tag##]`
* WARmain: `MicrosoftCorporationII.WinAppRuntime.Main.<rmajor>[-shorttag##]`
* WARsingleton: `MicrosoftCorporationII.WinAppRuntime.Singleton[-shorttag##]`
* WARddlm: `Microsoft.WinAppRuntime.DDLM.<rmajor>.<rminor>.<patch>.<revision>-<shortarchitecture>[-shorttag##]`

where

* rmajor = Major version number of the project release, base-10, no leading zeros (e.g. "1" for WindowsAppSDK 1.2)
* rminor = Minor version number of the project release, base-10, no leading zeros (e.g. "2" for WindowsAppSDK 1.2)
* patch = Patch version number of the project release, base-10, no leading zeros
* major = Major version number of the release, base-10, no leading zeros
* minor = Minor version number of the release, base-10, no leading zeros
* build = Build version number, base-10, no leading zeros
* revision = Revision version number, base-10, no leading zeros
* architecture = Allowed values: "x86", "x64", "arm64"
* shortarchitecture = Allowed values: "x8", "x6", "a6"
* tag = Allowed values: "", "preview[#]", "experimental[#]"
* shorttag = Allowed values: "", "p[#]", "e[#]"
* tag = Allowed values: "", "preview", "experimental"
* shorttag = Allowed values: "", "p", "e"
* "##" = the current build bumber for that release type. 2 characters long. Each caharacter could be [a-z,0-9].

**NOTE:** rmajor/rminor are the release version, major/minor/build/revision are the MSIX package
**NOTE:** rmajor/rminor/patch are the release version, major/minor/build/revision are the MSIX package
version (Microsoft.ProjectReunion.0.8-preview had a release version of 0.8
but an MSIX package version of 8000.146.628.0).
but an MSIX package version of 8000.146.628.0). Starting 2.0, these will now be the same numbers. The exception to that is
Singleton, since there is one package covering all releases. That package can't "go back" to Major=2, so we will add a
8000 to the Major for that package.

Since we will now match the release version with the MSIX, it is worth explaining how that is going to increment.
* Major will increase when a stable or preview release contains Breaking Changes from the previous Stable release. This will happen
no more than once per year.
* Minor will increase when a stable release contains new Functionality from the previous Stable release. This will happen no more than once
per month.
* Every potential released build (stable, preview, experimental) will increase the Patch, unless the Major or Minor is increased.
No 2 builds will share the same Major.Minor.Patch version.
If we notice an issue after building a canditate(stable, preview, or experimental), we will choose not to release it, at which
point the patch will bump again.
This means that there will be times when there is a patch number that will not be released at all.
* Note: We see experimental releases as "containing" the closest stable + some experimental stuff, rather than "previewing" what is coming. We
do not bump the Major/Minor for experimental things because the new/breaking things will at least sometimes not be in the next stable release,
and may even be removed before the next experimental release.
* Preview releases are optional if we feel the need to have a preview of nearly stable things without anything currently marked experimental.
This will only happen on the next Major release before making an official stable release.

A simplified example is this:
* 2.0.0 is the first stable release.
* 2.0.1-experimental is the first experimental. (contains 2.0.0 + some exp APIs, and some bug fixes)
* 2.0.2 is the 2nd stable release. (bug fixes moved into 2)
* 2.0.3-experimental is the 2nd experimental. (contains 2.0.1 + some exp APIs, and some more bug fixes)
* 2.0.4-experimental is the 3rd experimental. (contains 2.0.1 + some Breaking Changes, some exp APIs, and some more bug fixes)
* 2.1.0 is the 3rd stable release (some of the exp APIs went stable, and some bug fixes)
* 2.1.1-experimental is the 4th experimental. (contains 2.1.0 + some Breaking Changes, and some more bug fixes)
* 3.0.0-preview is the preview 3 public release
* 3.0.1-experimental (contains 3.0.1-preview + some new APIs not in the preview build)
* 3.0.3 is the first 3 stable release (we made 3.0.2, noticed issues we had not seen in preview, fixed and rebuilt)
* 3.0.4-experimental (contains 3.0.3 + the new APIs from 3.0.1-experimental)

Version's fields have values 0-65535.

Expand All @@ -433,89 +472,94 @@ This leads to package Name length issues even for common cases:

|Package|Average|AverageLength|
| --- | :--- | :---: |
|WARfwk |Microsoft.WindowsAppRuntime.1.15-preview1|41|
|WARmain|Microsoft.WindowsAppRuntime.Main.1.15-preview1|46|
|WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview1|46|
|WARddlm|Microsoft.WinAppRuntime.DDLM.1.15.12345.24680-arm64-preview1|**<span style="color:red">64</span>**|
|WARfwk |Microsoft.WindowsAppRuntime.2-preview00|39|
|WARmain|Microsoft.WindowsAppRuntime.Main.2-preview00|44|
|WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview00|47|
|WARddlm|Microsoft.WinAppRuntime.DDLM.1.15.12345.24680-arm64-preview00|**<span style="color:red">61</span>**|

|Package|Min|MinLength|
| --- | :--- | :---: |
|WARfwk |Microsoft.WindowsAppRuntime.1.0-preview1|40|
|WARmain|Microsoft.WindowsAppRuntime.Main.1.0-preview1|45|
|WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview1|46|
|WARddlm|Microsoft.WinAppRuntime.DDLM.1.0.0.0-arm64-preview1|**<span style="color:red">52</span>**|
|WARfwk |Microsoft.WindowsAppRuntime.2-preview00|39|
|WARmain|Microsoft.WindowsAppRuntime.Main.1-preview00|44|
|WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview00|47|
|WARddlm|Microsoft.WinAppRuntime.DDLM.1.0.0.0-arm64-preview00|**<span style="color:red">52</span>**|

|Package|Max|MaxLength|
| --- | :--- | :---: |
|WARfwk |Microsoft.WindowsAppRuntime.65535.65535-preview1|48|
|WARmain|Microsoft.WindowsAppRuntime.Main.65535.65535-preview1|53|
|WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview1|46|
|WARddlm|Microsoft.WinAppRuntime.DDLM.65535.65535.65535.65535-arm64-preview1|**<span style="color:red">71</span>**|
|WARfwk |Microsoft.WindowsAppRuntime.65535-preview00|43|
|WARmain|Microsoft.WindowsAppRuntime.Main.65535-preview00|48|
|WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview00|47|
|WARddlm|Microsoft.WinAppRuntime.DDLM.65535.65535.65535.65535-arm64-preview00|**<span style="color:red">68</span>**|

Possible options we can use to shorten package Name:

* Change the Name constant/prefix to a shorter string e.g. change "Microsoft.WindowsAppRuntime.Main" to "Microsoft.WinAppRuntime.Main", etc
* Dictate max values e.g. Major=0-99
* Encode values as base-16
* Replace -channel with a shorter string e.g. replace "-preview" with "-pre", "-p", "p"
* Encode the channel name in the delimiter between name+version e.g. Microsoft.WinAppRuntime.DDLM<span style="color:red; font-size:xx-large"><b>.preview1</b></span>.1.0.0.0-arm64
* Encode tag in the delimiter between version+architecture e.g. Microsoft.WinAppRuntime.DDLM.1.0.0.0<span style="color:red"><b>p1</b></span>arm64 using P1 for Preview1, E1=Experimental1, ...
* Name WARddlm differently from WARfwk and WARmain e.g. use "-p1" for WARddlm regardless if WARfwk and WARmain use "-preview1"
* ???
* Encode the channel name in the delimiter between name+version e.g. Microsoft.WinAppRuntime.DDLM<span style="color:red; font-size:xx-large"><b>.preview01</b></span>.1.0.0.0-arm64
* Encode tag in the delimiter between version+architecture e.g. Microsoft.WinAppRuntime.DDLM.1.0.0.0<span style="color:red"><b>p1</b></span>arm64 using P01 for Preview1, E01=Experimental1, ...
* Name WARddlm differently from WARfwk and WARmain e.g. use "-p01" for WARddlm regardless if WARfwk and WARmain use "-preview01"

WARddlm is needed until Dynamic Dependencies is 100% based on OS DynDep.

Best case (!) WARddlm exists until the minimum supported Windows release is Cobalt.

***Recommendation:*** The general package naming syntax is
`Microsoft.ProjectReunion[.SubName]-<rmajor>.<rminor>[-tag]`. WARddlm and WARsingleton are
`Microsoft.ProjectReunion[.SubName]-<rmajor>[-tag]`. WARddlm and WARsingleton are
exceptions to the rule (see below).

Windows App SDK 0.8 will use package Names of...
Windows App SDK 2.0 will use package Names of...

* WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>.<rminor>[-tag]`
* WARmain: `Microsoft.WindowsAppRuntime.Main.<rmajor>.<rminor>[-tag]`
* WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>[-tag]`
* WARmain: `Microsoft.WindowsAppRuntime.Main.<rmajor>[-tag]`
* WARsingleton: `Microsoft.WindowsAppRuntime.Singleton[-tag]`
* WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<build>.<revision>-<shortarchitecture>[-shorttag]`
* WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<patch>.<revision>-<shortarchitecture>[-shorttag]`

Using Decision 5: Version Encoding = Option D (NPPP.E.B.0) WARddlm's maximum package Name length is
`Microsoft.WinAppRuntime.DDLM.1714.3944.123.24680-arm64-p3` = 58 characters. This can be reduced
Using Decision 5: Version Encoding = Option D (M.N.P.0) WARddlm's maximum package Name length is
`Microsoft.WinAppRuntime.DDLM.12345.12345.12345.12345-arm64-p01` = 62 characters. This can be reduced
with the following rules:

* Major version <= 99
* Major version <= 999
* Minor version <= 999
* Build number <= 9999
* Patch number <= 999
* Revision (security update) <= 99
* Architecture = 2 characters (x8=x86, x6=x64, a6=arm64)

This produces a worst case for WARddlm in Windows App SDK 99.888.7777.66 ARM64 Preview 3 to the following identifiers:
In the unlikely event that Minor or Patch reach these limits, then the Major (for the Minor)
or Minor (for the Patch) will bump for all packages in order to keep these restrictions. If\When we reach Major version 1000, then
the Major version will be the Actual Major %1000. This works, since the Major is also included in the name.

This produces a worst case for WARddlm in Windows App SDK 99.888.777.66 ARM64 Preview 3 to the following identifiers:

* Package Name = `Microsoft.WinAppRuntime.DDLM.99.888.7777.66-a6-p3` = 49 characters
* PackageFullName = `"Microsoft.WinAppRuntime.DDLM.99.888.7777.66-a6-p3_99.888.7777.66_arm64__8wekyb3d8bbwe"`
* PackageFamilyName = `"Microsoft.WinAppRuntime.DDLM.99.888.7777.66-a6-p3_8wekyb3d8bbwe"`
* PACKAGE_VERSION struct = `99.888.7777.66`
* PACKAGE_VERSION uint64 = `0x006303781E610042`
* Package Name = `Microsoft.WinAppRuntime.DDLM.999.888.777.66-a6-p03` = 50 characters
* PackageFullName = `"Microsoft.WinAppRuntime.DDLM.999.888.777.66-a6-p03_999.888.7777.66_arm64__8wekyb3d8bbwe"`
* PackageFamilyName = `"Microsoft.WinAppRuntime.DDLM.999.888.777.66-a6-p03_8wekyb3d8bbwe"`
* PACKAGE_VERSION struct = `999.888.777.66`
* PACKAGE_VERSION uint64 = `0x03E7037803090042`

# 3. Conclusions

**Decision 1:** Windows App SDK version 0.* encodes `Major.Minor` into MSIX package Names starting with version 0.8.0.0.

**Decision 2:** Windows App SDK version 1.* encodes `Major.Minor` into MSIX package Names.

**Decision 2.1:** Windows App SDK version 2.* encodes `Major` into MSIX package Names.

**Decision 3:** Windows App SDK supports an optional 'tag' to indicate a non-Stable channel.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there are 2 Decision 3's, renumber

A 'tag' comes in long and short (1-2 character) forms e.g. `-preview` and `-p`,
or `-preview1` and `-p1` (the digit suffix is optional).

**Decision 4:** Windows App SDK encodes version as `<minor><patch>.<epoch>.<build>.<securityupdate>`
i.e. format encoding `NPPP.E.B.0`. See
**Decision 4:** Windows App SDK encodes version as `<major>.<minor>.<patch>.<securityupdate>`
i.e. format encoding `M.N.P.0`. See
[2.4. Decision 4: Version Encoding](#24-decision-4-version-encoding) for more details.

**Decision 5:** MSIX package Names use the format
`Microsoft.WindowsAppRuntime[.SubName]-<rmajor>.<rminor>[-tag]`. WARddlm is an exception due to Name
length constraints. The specific packages Names in Windows App SDK 1.0:
`Microsoft.WindowsAppRuntime[.SubName]-<rmajor>[-tag]`. WARddlm is an exception due to Name
length constraints. The specific packages Names in Windows App SDK 2.0:

* WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>.<rminor>[-tag]`
* WARmain: `MicrosoftCorporationII.WinAppRuntime.Main.<rmajor>.<rminor>[-shorttag]`
* WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>[-tag]`
* WARmain: `MicrosoftCorporationII.WinAppRuntime.Main.<rmajor>[-shorttag]`
* WARsingleton: `MicrosoftCorporationII.WinAppRuntime.Singleton[-shorttag]`
* WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<build>.<revision>-<shortarchitecture>[-shorttag]`

Expand Down
23 changes: 11 additions & 12 deletions specs/Deployment/MSIXPackages.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,10 +110,10 @@ SDK 1.0, 1.1 and 2.0 (Stable) are installed on an x86 system, the user will have

* Microsoft.WindowsAppRuntime.1.0
* Microsoft.WindowsAppRuntime.1.1
* Microsoft.WindowsAppRuntime.2.0
* Microsoft.WindowsAppRuntime.2
* MicrosoftCorporationII.WinAppRuntime.Main.1.0
* MicrosoftCorporationII.WinAppRuntime.Main.1.1
* MicrosoftCorporationII.WinAppRuntime.Main.2.0
* MicrosoftCorporationII.WinAppRuntime.Main.2
* MicrosoftCorporationII.WinAppRuntime.Singleton (version 2.0)
* Microsoft.WinAppRuntime.DDLM.0.146.711.0-x8
* Microsoft.WinAppRuntime.DDLM.1000.328.1510.0-x8
Expand Down Expand Up @@ -143,36 +143,35 @@ for more details.

Windows App SDK's MSIX packages use the following naming rules for package identity:

* Name = Microsoft.WindowsAppRuntime[.SubName].\<Major\>.\<Minor\>[-VersionTag]
* Name = Microsoft.WindowsAppRuntime[.SubName].\<Major\>[-VersionTag]
* Publisher = "CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US"

where

* SubName -- optional package sub-name. Use to distinguish amongst the different packages
* Major -- major version of the release, e.g. "1" for Windows App SDK 1.0
* Minor -- minor version of the release, e.g. "0" for Windows App SDK 1.0
* VersionTag -- optional version tag to distinguish amongst channels and releases of a channel, e.g. "-preview2" for Windows App SDK 1.0 Preview 2
* VersionTag -- optional version tag to distinguish amongst channels, e.g. "-preview" for Windows App SDK Preview

## 3.1. Package Naming - SubName

The following SubName values are used:

| SubName | Package | Example |
|-|-|-|
| | Framework | Microsoft.WindowsAppRuntime.1.0-experimental1 |
| Main | Main | MicrosoftCorporationII.WinAppRuntime.Main.1.0-e1 |
| Singleton | Singleton | MicrosoftCorporationII.WinAppRuntime.Singleton-e1 |
| DDLM | Dynamic Dependency Lifetime Manager (DDLM) | Microsoft.WinAppRuntime.DDLM.0.146.711.0-x6-e1 |
| | Framework | Microsoft.WindowsAppRuntime.2-experimental00 |
| Main | Main | MicrosoftCorporationII.WinAppRuntime.Main.2-e00 |
| Singleton | Singleton | MicrosoftCorporationII.WinAppRuntime.Singleton-e00 |
| DDLM | Dynamic Dependency Lifetime Manager (DDLM) | Microsoft.WinAppRuntime.DDLM.2.3.11.0-x6-e00 |

## 3.2. Package Naming - Main

The Main package follows a different naming scheme

* Name = MicrosoftCcorporationII.WinAppRuntime.Main.\<ReleaseMajorMinor\>[-ShortVersionTag]
* Name = MicrosoftCcorporationII.WinAppRuntime.Main.\<ReleaseMajor\>[-ShortVersionTag]

where

* ReleaseMajorMinor = project release major.minor version number. See the [MSIX Package Versioning](https://github.com/microsoft/WindowsAppSDK/blob/main/specs/deployment/MSIXPackageVersioning.md) for more details.
* ReleaseMajor = project release major version number. See the [MSIX Package Versioning](https://github.com/microsoft/WindowsAppSDK/blob/main/specs/deployment/MSIXPackageVersioning.md) for more details.
* ShortVersionTag = short form of the VersionTag

ShortVersionTag is derived from a VersionTag by combining the 1st letter and the last digit (if any) for non-Stable channels (ShortVeresionTag is blank for the Stable channel, just like VersionTag).
Expand Down Expand Up @@ -202,7 +201,7 @@ where
* ShortArchitecture = short form of the Architecture (x6=x64, x8=x86, a6=arm64)
* ShortVersionTag = short form of the VersionTag

ShortVersionTag is derived from a VersionTag by combining the 1st letter and the last digit (if any) for non-Stable channels (ShortVeresionTag is blank for the Stable channel, just like VersionTag).
ShortVersionTag is derived from a VersionTag by using the 1st letter for non-Stable channels (ShortVeresionTag is blank for the Stable channel, just like VersionTag).

```C#
string ToShortVersionTag(string versionTag)
Expand Down
Loading