2.0 msix version spec #5986
There are no files selected for viewing
| 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 | ||
|
|
@@ -397,7 +394,7 @@ following naming patterns release 0.x... | |
|
|
||
| * WARfwk: `Microsoft.WindowsAppRuntime.<rmajor>.<rminor>[-tag]` | ||
| * WARmain: `Microsoft.WindowsAppRuntime.Main.<rmajor>.<rminor>[-tag]` | ||
| * WARddlm: `Microsoft.WindowsAppRuntime.DDLM.<rmajor>.<rminor>.<build>.<revision>-<shortarchitecture>[-shorttag]` | ||
|
|
||
| and release 1.x... | ||
|
|
||
|
|
@@ -406,22 +403,55 @@ 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>.<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" | ||
|
|
||
| **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). 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. | ||
| Every potential released build (stable, preview, experimental) will increase the Patch, unless the Major or Minor is increased. | ||
| If we notice an issue after building the canditate, we might choose not to release it, at which point the patch could bump twice. | ||
|
Collaborator
|
||
| Major will increase when a stable or preview release contains Breaking Changes from the previous Stable release. | ||
| Minor will increase when a stable release contains new Functionality from the previous Stable release. | ||
| Experimental releases will always be a patch bump from the last release and based on the most recent stable or preview. The Major.Minor | ||
| will remain the same whether the experimental release contains big fixes, new functionality, or breaking changes. | ||
| Preview is optional if we feel the need to have a preview to split out the current experimental from the next Major release before | ||
| making an official stable release. | ||
|
Collaborator
There was a problem hiding this comment. Suggestion: All of these lines combining as a paragraph is okay, but it might be easier to read/scan to separate the major points in different bullets. There was a problem hiding this comment. Yes, I agree. In the .md file it looks OK and the linebreaks are made at the right places. In the rendering, these linebreaks are gone, and it's hard to digest. So, definitely, putting here bullet points in front of Major, Minor, Experimental, and Preview makes it easier to read. |
||
|
|
||
| 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) | ||
|
Contributor
There was a problem hiding this comment. This doesn't make sense to me. 2.0.1 should be the 2nd stable release. There was a problem hiding this comment. I'm with Morten here. The versions should be incremental in their own band. See NuGet's docs for a widely accepted and understood naming paradigm https://learn.microsoft.com/en-us/nuget/concepts/package-versioning?tabs=semver20sort#pre-release-versions Using the 2.0 sematic versioning it should be 2.0.1-aaa |
||
| 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) | ||
|
Contributor
There was a problem hiding this comment. this should be 2.0.3-experimental2 if it's the experimental version working its way to 2.0.3.
Contributor
Author
There was a problem hiding this comment. I would like to explain how we are thinking about experimentals and why we came to this decision. Then I would love to hear your thought on it. Experimental is not "working towards" the version it is on, it is based on the last public "+ some experimental bits". Those experimental bits might come in the next public, but might sit there for months, then go away. Let me give an example: 2.0.0 (stable) It is fairly clear to people looking at the nugets in semver order the order we built things, and therefore which exp is based on which stable. Since 2.0.2-exp is "lower than" the stable, we need to actually bump the patch for exp builds to get the order right. Had we done it where the new APIs lead to an increase in Minor, and used the # to distinuish 2 exps, we would see: 2.0.0 (stable) That would lead to the following "order" when looking at VS: But 2.0.2 is newer than either of the 2.1 exps, and 2.0.3 exp is also newer than those. To prevent this, we could bump the minor on each stable after an exp had bumped the minor, but now we would be on 2.2 stable when we only had bug fixes. Another way to prevent the drop back in exp is we could always have exp on the next minor(or Major). We considered this aproach, but as mentioned above, 2.0.2 is newer than the 2.1 exps, but VS would make it hard to know that. It is also difficult to keep track of which 2.1 exp is based on which 2.0 stable. There was a problem hiding this comment. Okay, so in the case, if preview means "on top of" instead of "leading up to", then I would expect the version number with the preview flag should be on the (patch or minor) version increment. Continuing with the same example:
I do understand your intent now that you've explained... but if you have to explain it, that means it's not intuitive, leading to confusion (and a renewed sentiment of "why does Windows dev have to do everything different" 😜). Just my 2-cents. I will adapt because I want to, but you should take into consideration that others may not have the same enthusiasm I do and would consider this another Lego they stepped on with windows dev...
Contributor
Author
There was a problem hiding this comment. preview and experimental are different. We do see preview as "leading up to", but we would only give that as a next Major release, letting people know that the next Major is coming soon. And we are bumping the patch when we have the tag, 2.0.0 stable was followed by 2.0.1-exp. There was a problem hiding this comment. Ah, my apologies, I was mixed up due to an earlier comment about number of characters allowed in the version string, and jumped to the conclusion that you were replacing Ultimately, what matters most is how Visual Studio/dotnet package restores packages. It is going to choose them in this order:
As long as the dev knows what version the latest has what they want, then all is good. Alternate Option Let me throw a crazy idea at you... what if you use date version number for the suffix instead?
This is how I avoid mixups in my products. My customers know exactly what they're getting in that version because of when it was released.... and it allows for newer "experimental" version of an already establish major.minor.patch release... making it obvious that it was built on top of that version.
Contributor
Author
There was a problem hiding this comment. We also considered that, but the "-" symbol means "this is a non-stable build", so we don't want that on stable builds. In Semver that really should be in the build metadata with the "+" symbol, but:
|
||
| 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) | ||
|
Collaborator
There was a problem hiding this comment. The example here is good, but the markdown formatting is problematic since all lines get merged like a paragraph. I suggest starting each of these version example lines with "* " to make each line a bullet. |
||
|
|
||
| Version's fields have values 0-65535. | ||
|
|
||
|
|
@@ -433,24 +463,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 +498,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]` | ||
|
|
||
|
|
||
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.