2.0 msix version spec

[Dreynor87]

Add information for the MSIXPackage version change for 2.0 into the spec files.

A microsoft employee must use /azp run to validate using the pipelines below.

WARNING:
Comments made by azure-pipelines bot maybe inaccurate.
Please see pipeline link to verify that the build is being ran.

For status checks on the main branch, please use TransportPackage-Foundation-PR
(https://microsoft.visualstudio.com/ProjectReunion/_build?definitionId=81063&_a=summary)
and run the build against your PR branch with the default parameters.

[DrusTheAxe]

SUGGESTION: In 2.0 the MSIX package family changes to the format:

Active voice, not passive voice ('we are', not 'we will', etc)

[DrusTheAxe]

Which MSIX package? WinAppSDK has 4 (Fwk, Main, Singleton, DDLM) and they have different syntax

• Main+Singleton have the prefix MicrosoftCorporationII.WinAppRuntime (not MIcrosoft.WindowsAppRuntime)
• DDLM syntax prefix Microsoft.WinAppRuntime.DDLM, includes <version> (not just major), includes <shortarchitecture> and <shorttag> (not just tag) e.g. Microsoft.WinAppRuntime.DDLM.5000.1105.1506.0-x6-e

See specs\Deployment\MSIXPackages.md for more details.

Are these names changing to match the Framework's syntax? If so doesn't that bump into package Name limits (maxlen=50)? That's what led to the unusual DDLM naming. Main+Singleton got the different prefix 'cause Store reasons; is that no longer an issue and can use same prefix as the Framework?

If those restrictions are still true then line 527 only applies to the Framework package and Main+Singleton+DDLM syntax need to be specified

SUGGESTION: Assuming prefixes and DDLM naming aren't changing to match Framework

Starting in 2.0 the MSIX package family names change to: | Package | Family Name Format | Example | Example Length | |-----------|--------------------------------------------------------------------|-----------------------------------------------|:--------------:| | Framework | MicrosoftWindowsAppRuntime.<rmajor>[-tag] | MicrosoftWindowsAppRuntime.2-experimental | 41 | | Main | MicrosoftCorporationII.WinAppRuntime.Main.<rmajor>[-shorttag] | MicrosoftCorporationII.WinAppRuntime.Main.2-e | 45 | | Singleton | MicrosoftCorporationII.WinAppRuntime.Singleton.<rmajor>[-shorttag] | MicrosoftWindowsAppRuntime.2-e | 30 | | DDLM | Microsoft.WinAppRuntime.DDLM.<version>-<shortarch>[-shorttag] | Microsoft.WinAppRuntime.DDLM.2.4.6.8-x6-e | 41 | 

This fits, but note the tag/shorttag have no numeric suffix. Is that the intention?
(Today 'tag' is channel[#] ie. channel name with an optional digit)

And more importantly, the DDLM version number's the minimum possible length 1.2.3.4 = 7chars. The max possible length is +16 chars (65535.65535.65535.65535) making a package Name length of 57 characters which isn't valid.

This is one of the reasons why 1.x MSIX package names dictated version field restrictions e.g.

* Major version <= 99 * Minor version <= 999 * Build number <= 9999 * Revision (security update) <= 99 

See specs\Deployment\MSIXPackageVersioning.md for more details.

Will the version be similarly restricted to ensure the DDLM's package Name is valid?
If not what format will the DDLM use?

NOTE: The DDLM package is obsolete on Windows >= 24H2 (Ge). Unless WinAppSDK drops support for older releases (and hard to say given RS5 LTSC, 21H2 LTSC and 22H2 are supported into 2029 and 2032). See https://en.wikipedia.org/wiki/Windows_10_version_history#Channels for one of the support timeframe cheatsheets.

[DrusTheAxe]

See previous comment

[DrusTheAxe]

Updates needed

[codendone]

Why these limits? I'm guessing they are from the comment from @DrusTheAxe. I'm wonderinf if those are just examples, since it seems like Major/Minor/Patch will each be limited to 65535 (minus 8000 for Major, given singleton).

(Also note these lines all show up as one line when viewing the formatted md.)

[DrusTheAxe]

It's a DotQuadNumber ie UINT64 expressed as UINT16[4] -- major=array[0], minor=array[1], patch=array[2], build=array[3]. Thus each part can be 0-65535

DDLM naming requires name prefix ("Microsoft.WindowsAppRuntime.DDLM." in 1.x) plus architecture (fixed 2chars in1.x e.g. "x6") plus version (a.b.c.d). That means the DDLM package Name length in 1.x could have ranged from

• Min length = Microsoft.WindowsAppRuntime.DDLM.0.0.0.0-x6-e == 45 chars
• Max length = Microsoft.WindowsAppRuntime.DDLM.65535.65535.65535.65535-x6-e == 62 chars

MSIX package Name maxlength=50

So those major/minor/patch/build max values restricted the max Name to

Microsoft.WindowsAppRuntime.DDLM.99.999.9999.99-x6-e = 52chars

but in practice we never expected to need such large minor and patch (e.g. 10.100.1000.10) for non-stable (experimental, preview, ...) as we expected to roll over to the next minor (resetting patch to 0) or major (resetting minor to 0) before needing >50 chars. Even with 3 builds a day you can go ~3yrs before needing a 4digit patch number (way more than we'd ever need). Stable's has no channel suffix (eg -e) so even worst case was always fine. To top if off, we expected 4 or maybe 3 releases a year so the caps were theoretical and way beyond anything we'd ever bump into.

For the new rules we don't necessarily need those caps, but we do need a design and associated rules, policies and expectations to guarantee we won't have a problem.

P.S. Increasing MSIX package Name maxlength could solve this (maybe, if the reasons we chose 50 were also addressed...). But changing MSIX identity rules is exceedingly high for new Windows releases, and downlevel makes that look trivial by comparison. TL;DR impractical, so we must work within the world that is.

[codendone]

BuildNumber

What value does BuildNumber bring? "Patch" will be incremented with each build, making BuildNumber unnecessary, right?

[Dreynor87]

I agree it should not ever get above 0, since each full build will give a new Patch. I am including that here in case that ever were to change to have some way of doing security update changes without updating the patch.

[Dreynor87]

I did just think of one place we might actually want to use this number...

We don't want every PR build to bump the patch, or we might actually reach the max for the patch. We could have a counter for PR (and nightly if we only want official to bump the patch) that will use the same Patch version until the next bump from an official build, and the "security update" field could distinguish 2 pr builds from each other.

[DrusTheAxe]

Have you considered using different channel for PR builds?

Could use '-dev' for PR/CI builds, and perhaps -dev# so it doesn't affect the patch value

We've named SemVer -prerelease per our channels (-experimental, -preview). PR/CI could use its own -VersionTag that alphabetically sorts before -e[xperimental].

We've considered -d[ev] for if/when we do (public) dev/nightly builds as -d[ev] < -e[xperimental]

If we wanted to preserve -d[ev] for potential future public use something -a, -b or -c would work (-a[lpha] ?)

[codendone]

I agree PR builds should not update the Patch for official builds. I think it would be fine they use their own counter with an appropriate tag/whatever to put them in separate package families.

I similarly hope Nightly builds don't update the Patch for official builds. The Patch for official builds should only be for runs of the Official pipeline (which might still have multiple runs before we've selected the next build to release).

[codendone]

Given "MSIX version's 4th field (Revision) is reserved for security updates", I think we could just list this as "0".

[DrusTheAxe]

Only way you could list this as "0" is if the DDLM will never (and can never) need an update leveraging this.

If you engrave that in stone then Revision needs to support a non-zero value, even if rarely (hopefully never?) used.

Even if you declare "Revision can only be 1 digit (0-9) the DDLM package Name's max length is still too big with just this restriction. See the math above for more details

[codendone]

VersionTag

What will the VersionTag be for experimental builds in 2.x? Do we continue with the "e1", "e2", etc. counter? That currently requires manual updates for each experimental, and if 2.x continues with regular monthly experimentals, that would mean more manual updates. Also, will there be any problems when we get to the tenth experimental and need another digit for "e10"?

[codendone]

Answering my last question, the removal of "." from the package family name will leave room for double-digit experimental numbers in the version tag.

[DrusTheAxe]

e.g. Microsoft.WindowsAppRuntime2-Experimental23 ?

"VersionTag" was spelled out e.g. Experimental2. "ShortVersionTag" ("VersionShortTag"?) was the 1letter + optional number, as DDLM's Name couldn't fit anything longer. Are we planning to change the tag to always use short form? Microsoft.WindowsAppRuntime2-e1 rather than Microsoft.WindowsAppRuntime2-experimental1 ?

[Dreynor87]

We are removing the # from the tag (short and long). Updating in spec.

[codendone]

The # is required to prevent a newer experimental from overtaking a previous experimental instead of being side-by-side. (Same for previews.) We want to keep these side-by-side to ensure that an app which works on experimental1 isn't suddenly broken when experimental2 gets installed even though the app is still trying to use experimental1.

If the ever-increasing "patch" number were somehow incorporated instead (only for experimental and previous releases), that could be an alternative to the #.

[Dreynor87]

We expect the number of experimentals in a given Major to be much more than we have had in the past(particularly when we only did a few before the next 1.X release). Having too many could lead to the Max Character issue getting hit by that, which means we would need a solution for when that rolls over. I did forsee that when you are using the experimental if the package updates, then you just get it/deal with it. Since this is developers, who actually would have had to request a newer experimental, I didn't think it would be a big deal.

[codendone]

I have many test apps for various versions sitting around on my machine. It is never fun when I go back to an old test app and find it no longer working for some reason.

How many characters do we have to work with? Do we have 2 characters, such that we can do [A-Z0-9] for each character, giving us 36*36 experimentals per Major version? If we release 12 experimentals per year, that gives us 108 years of experimentals, or nearly 25 years if we release an experimental every week.

[codendone]

tag

Is a nightly or pr build called out in the tag (or in some other way) to avoid conflicting with official builds? The old versioning scheme made it easier to avoid version issues since both official and night/pr builds used the same counters with the Elapsed/Build parts of the MSIX versioning making it easier to have a newer version. If nightly/pr now run with their own 'patch' counter, how do those avoid conflicts?

[Dreynor87]

-ni and -pr are the tags for nightly and pr builds.

[codendone]

Are these written down somewhere?

[Dreynor87]

In the Aggregator Repo PR:

Each Repo can decide what to do for their <-label?> section, though there should be a label for non-release
builds. For the Aggregator Repo, the label would contain the following:
<pr/ni?><experimental?>
If a build was triggered for nightly or pull request, then the pr/ni would be part of the label.
If a build was triggered for experimental, then the experimental would be part of the label.
Since a Nightly build can still also be experimental, both can happen, at which point a "."
would be put between the 2, for easier reading.

I did not show this here. I can add it.

[codendone]

I propose updating the title of this PR to something like:

2.0 msix version spec 

[DrusTheAxe]

I propose updating the title of this PR to something like:

2.0 msix version spec 

Or rename the current files ...-1.x.md

Or my preference, move the existing files with their old 0.x/1.x information into a new specs\Deployment\obsolete directory and write new content here with just the 2.0+ rules.

P.S. Alternatively we could move 'obsolete' content under a new specs\obsolete\Deployment directory but I prefer keeping related content together e.g. Deployment\* and Deployment\obsolete\*. Makes it easier for the content owner to manage, (and eventually delete obsolete information).

[RDMacLachlan]

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

[DrusTheAxe]

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

[codendone]

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.

[codendone]

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.

[codendone]

could bump twice

could bump twice

suggest "again" instead of "twice", since this situation could repeat multiple times before a build is selected for release.