Skip to content

2.0 msix version spec #5986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Dreynor87 wants to merge 7 commits into
base: main
Choose a base branch
from
+865 −69
Open

2.0 msix version spec #5986

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
41317ba
Add a note to the MSIXPackageVersioning spec about the changes for 2.0
Nov 7, 2025
f77e58f
Add a note to the MSIXPackages.md file as well
Nov 7, 2025
44030c2
Change to say component packages
Nov 7, 2025
ca1651a
Update the spec
Nov 17, 2025
c75c85a
Move old to deprecated, and edit the existing in place for 2.0 design
Nov 20, 2025
299ffb9
Add more specifics about version and experimental stuff
Nov 25, 2025
c81fbcb
Clarify things, and add tag build bumbers
Dec 9, 2025
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
17 changes: 17 additions & 0 deletions specs/Deployment/MSIXPackageVersioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -520,3 +520,20 @@ length constraints. The specific packages Names in Windows App SDK 1.0:
* WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<build>.<revision>-<shortarchitecture>[-shorttag]`

See [2.5. Decision 5: Package Names](#25-decision-5-package-names) for more details.


## Version Starting 2.0
In 2.0, we will be switching the family name of the MSIX package. The new style will be:
Copy link
Member

@DrusTheAxe DrusTheAxe Nov 8, 2025

Choose a reason for hiding this comment

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

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

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

Copy link
Member

@DrusTheAxe DrusTheAxe Nov 8, 2025

Choose a reason for hiding this comment

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

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.

`Microsoft.WindowsAppRuntime[.SubName].<rmajor>[-tag]` - translated to the individual names as above.

The version will also change:
<Major>.<Minor>.<Patch>.<securityupdate>

The Major, Minor, and Patch versions are all in a centralized Repo. All Repos that create
Component packages will use the same centralized versions. When a full build of WindowsAppRuntime
is completed, the Patch version will automatically update. When Major or Minor are manually updated
the Patch will be reset to 0 at that point.

This change will make it easier for people to know what version they are on. We will be keeping compatibility
for all previous Minor versions within the same Major version. Developers also won't have to Manually upgrade to get
the new Minor Version.
5 changes: 5 additions & 0 deletions specs/Deployment/MSIXPackages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,11 @@ where
* 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

## Change for 2.0

In 2.0, all MSIX names will change to remove the Minor version as follows:
* Name = Microsoft.WindowsAppRuntime[.SubName].\<Major\>[-VersionTag]
Copy link
Member

@DrusTheAxe DrusTheAxe Nov 8, 2025

Choose a reason for hiding this comment

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

See previous comment

Copy link
Collaborator

@codendone codendone Nov 19, 2025

Choose a reason for hiding this comment

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

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"?

Copy link
Collaborator

@codendone codendone Nov 20, 2025

Choose a reason for hiding this comment

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

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

Copy link
Member

@DrusTheAxe DrusTheAxe Nov 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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 ?

Copy link
Contributor Author

@Dreynor87 Dreynor87 Nov 20, 2025

Choose a reason for hiding this comment

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

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

Copy link
Collaborator

@codendone codendone Nov 20, 2025

Choose a reason for hiding this comment

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

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 #.

Copy link
Contributor Author

@Dreynor87 Dreynor87 Nov 20, 2025

Choose a reason for hiding this comment

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

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.

Copy link
Collaborator

@codendone codendone Nov 21, 2025

Choose a reason for hiding this comment

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

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.


## 3.1. Package Naming - SubName

The following SubName values are used:
Expand Down