2.0 msix version spec #5986
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -255,17 +255,10 @@ version 89 and 92+ are under development. | |
| * Compatible with MSIX | ||
| * Does not align with common practices and expectations across the industry | ||
|
|
||
| ***Recommendation:*** | ||
| For all 1.x, option B was selected, while waiting on tooling to be able to handle the rapid development we want. | ||
| 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 should be compatible. | ||
|
|
||
| ### 2.2.1. Current practices in Microsoft-authored Framework packges. | ||
|
|
||
|
|
@@ -289,8 +282,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. | ||
|
|
||
| Windows App SDK 2.x goes back to just a "-preview" tag on the package Name. | ||
|
|
||
| ***Do we need a shorter tag?*** "-preview" adds 8 characters to package Name. "-experiental" adds | ||
| 12 characters. Package Name is restricted to 50 characters maximum. | ||
|
|
||
| **Option A: `-preview`** | ||
|
Comment on lines
+285
to
290
Contributor
There was a problem hiding this comment. In a spec why are the discussion topics and options? Shouldn't the spec instead be "this is what we're doing" ? I feel like it makes the spec confusing and not clear There was a problem hiding this comment. I agree, in my opinion, this question should be a separate issue and not in this markdown file. |
||
| **Option B: `-pre`** | ||
|
|
@@ -340,10 +335,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:*** | ||
| For 1.x, Option D was selected. | ||
| For 2.x, Option A is selected. | ||
|
|
||
| Option A works is the simplest to release and understand. As long as we don't hit 9999 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 | ||
|
|
@@ -406,6 +403,13 @@ and release 1.x... | |
| * WARsingleton: `MicrosoftCorporationII.WinAppRuntime.Singleton[-shorttag]` | ||
| * WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<build>.<revision>-<shortarchitecture>[-shorttag]` | ||
|
Member
There was a problem hiding this comment. We should be consistent in our language and Semantic Versioning language. This field if the
Member
There was a problem hiding this comment.
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 To avoid confusion that's why WARfwk+WARmain package Names including the WinAppSDK release's major+minor fields reference to them as
|
||
|
|
||
| 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>.<build>.<revision>-<shortarchitecture>[-shorttag]` | ||
|
|
||
| where | ||
|
|
||
| * rmajor = Major version number of the project release, base-10, no leading zeros (e.g. "1" for WindowsAppSDK 1.2) | ||
|
|
@@ -416,12 +420,14 @@ where | |
| * 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" | ||
|
|
||
| **NOTE:** rmajor/rminor are the release version, major/minor/patch/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). 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. | ||
|
|
||
| Version's fields have values 0-65535. | ||
|
|
||
|
|
@@ -433,24 +439,24 @@ This leads to package Name length issues even for common cases: | |
|
|
||
| |Package|Average|AverageLength| | ||
| | --- | :--- | :---: | | ||
| |WARfwk |Microsoft.WindowsAppRuntime.2-preview|37| | ||
| |WARmain|Microsoft.WindowsAppRuntime.Main.2-preview|42| | ||
| |WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview|45| | ||
| |WARddlm|Microsoft.WinAppRuntime.DDLM.1.15.12345.24680-arm64-preview|**<span style="color:red">59</span>**| | ||
|
|
||
| |Package|Min|MinLength| | ||
| | --- | :--- | :---: | | ||
| |WARfwk |Microsoft.WindowsAppRuntime.2-preview|37| | ||
| |WARmain|Microsoft.WindowsAppRuntime.Main.1-preview|42| | ||
| |WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview|45| | ||
| |WARddlm|Microsoft.WinAppRuntime.DDLM.1.0.0.0-arm64-preview|**<span style="color:red">50</span>**| | ||
|
|
||
| |Package|Max|MaxLength| | ||
| | --- | :--- | :---: | | ||
| |WARfwk |Microsoft.WindowsAppRuntime.65535-preview|41| | ||
| |WARmain|Microsoft.WindowsAppRuntime.Main.65535-preview|46| | ||
| |WARsingleton|Microsoft.WindowsAppRuntime.Singleton-preview|45| | ||
| |WARddlm|Microsoft.WinAppRuntime.DDLM.65535.65535.65535.65535-arm64-preview|**<span style="color:red">66</span>**| | ||
|
|
||
| Possible options we can use to shorten package Name: | ||
|
|
||
|
|
@@ -468,54 +474,60 @@ 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>[-tag]`. WARddlm and WARsingleton are | ||
| exceptions to the rule (see below). | ||
|
|
||
| Windows App SDK 2.0 will use package Names of... | ||
|
|
||
| * WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>[-tag]` | ||
| * WARmain: `Microsoft.WindowsAppRuntime.Main.<rmajor>[-tag]` | ||
| * WARsingleton: `Microsoft.WindowsAppRuntime.Singleton[-tag]` | ||
| * WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<patch>.<revision>-<shortarchitecture>[-shorttag]` | ||
|
|
||
| Using Decision 5: Version Encoding = Option D (M.N.P.0) WARddlm's maximum package Name length is | ||
| `Microsoft.WinAppRuntime.DDLM.1714.3944.123.24680-arm64-p` = 58 characters. This can be reduced | ||
| with the following rules: | ||
|
|
||
| * Major version <= 999 | ||
| * Minor version <= 999 | ||
| * Patch number <= 9999 | ||
| * Revision (security update) <= 99 | ||
| * Architecture = 2 characters (x8=x86, x6=x64, a6=arm64) | ||
|
|
||
| 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.7777.66 ARM64 Preview 3 to the following identifiers: | ||
|
|
||
| * Package Name = `Microsoft.WinAppRuntime.DDLM.999.888.7777.66-a6-p` = 49 characters | ||
| * PackageFullName = `"Microsoft.WinAppRuntime.DDLM.999.888.7777.66-a6-p_999.888.7777.66_arm64__8wekyb3d8bbwe"` | ||
| * PackageFamilyName = `"Microsoft.WinAppRuntime.DDLM.999.888.7777.66-a6-p_8wekyb3d8bbwe"` | ||
| * PACKAGE_VERSION struct = `999.888.7777.66` | ||
| * PACKAGE_VERSION uint64 = `0x03E703781E610042` | ||
|
|
||
| # 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 3:** 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. | ||
|
Member
There was a problem hiding this comment. there are 2 |
||
| 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 `<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>[-tag]`. WARddlm is an exception due to Name | ||
| length constraints. The specific packages Names in Windows App SDK 2.0: | ||
|
|
||
| * 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]` | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good. I would consider writing here then things will be compatible, instead of then things should be compatible, as it should really be the exception if something on the same Major is not compatible. Of course, if there are exceptions, someone can pin-point to this. But anyway, the "should be" sounds to me like soft target. If it's really a serious goal of making the Major the incompatibility boundary, then I would make the wording here also a bit stronger.