2.0 msix version spec by Dreynor87 · Pull Request #5986 · microsoft/WindowsAppSDK

Dreynor87 · 2025-11-07T18:13:47Z

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 · 2025-11-08T01:03:12Z

+## 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]


See previous comment

DrusTheAxe

Updates needed

codendone · 2025-11-19T23:54:41Z

+* WARddlm: `Microsoft.WinAppRuntime.DDLM.<major>.<minor>.<Patch>.<BuildNumber>-<shortarchitecture>[-shorttag]`
+
+The version will also change:
+<Major>.<Minor>.<Patch>.<BuildNumber>


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

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 · 2025-11-20T00:31:54Z

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

2.0 msix version spec

DrusTheAxe · 2025-11-20T03:23:58Z

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

codendone · 2025-11-25T22:54:17Z

+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)


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 · 2025-11-25T22:57:06Z

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


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.

dotMorten · 2025-12-04T19:02:08Z

+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)


This doesn't make sense to me. 2.0.1 should be the 2nd stable release.

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.1-alpha10
2.0.1-alpha2
2.0.1-beta
2.0.1-experimental (<-- alphabetical order lets htis fit naturally here)
2.0.1-open
2.0.1-rc.2
2.0.1-rc.10
2.0.1-zzz
2.0.1

thomasclaudiushuber · 2025-12-05T07:19:27Z

+***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.


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.

Scottj1s · 2026-01-12T20:14:29Z

-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


Suggested change

***Shorter Tags as needed*** "-preview" adds 8 characters to package Name. "-experiental" adds

***Shorter Tags as needed*** "-preview" adds 8 characters to package Name. "-experimental" adds

DrusTheAxe · 2026-01-20T18:37:15Z

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


Change to "Option A is selected."

DrusTheAxe · 2026-01-20T18:41:01Z

 * 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]`


Should be <rpatch> given it's the same as the release (SemVer lingo, Major.Minor.Patch)

DrusTheAxe · 2026-01-20T20:03:48Z


 **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 1 2 2.1 - little weird

SUGGESTION: Renumber to 1 2 3 4... Or remove info <2.0 -- cut Decision 1+2 and rename Decision 2.1... to Decision 1...version >=2.0 encodes...

codendone · 2026-01-20T19:32:02Z

 * 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).


Based on the examples above, it looks like ShortVersionTag also still combines the letter with potentially a couple of digits (e00 in the example for an -experimental00) release.

Co-authored-by: Mike Crider <45052236+codendone@users.noreply.github.com>

DrusTheAxe · 2026-03-18T00:29:03Z

Is the spec review complete / signed off?

Are all comments addressed?

Dreynor87 · 2026-03-18T01:44:05Z

Is the spec review complete / signed off?

Are all comments addressed?

Yes. I didnt complete this yet, partly cause I forgot, but mostly because the aggregator repo PR that describes more internals is not in yet, because that has not been approved by everyone we wanted.
And you are listed as "requesting changes"
I will double check that everything is correct tomorrow, then get it in
I did double check things, and I think they are good. @DrusTheAxe, once I get your approval, I can get this in.

Dreynor87 · 2026-03-19T18:11:59Z

/azp run

azure-pipelines · 2026-03-19T18:12:24Z

Azure Pipelines successfully started running 1 pipeline(s).

Dreynor87 · 2026-03-19T21:48:27Z

/azp run

azure-pipelines · 2026-03-19T21:48:50Z

Azure Pipelines successfully started running 1 pipeline(s).

Chris Wall (WIN SDE) added 2 commits November 7, 2025 11:03

Add a note to the MSIXPackageVersioning spec about the changes for 2.0

41317ba

Add a note to the MSIXPackages.md file as well

f77e58f

Dreynor87 requested review from DrusTheAxe, RDMacLachlan and Scottj1s November 7, 2025 18:13

Dreynor87 self-assigned this Nov 7, 2025

microsoft-github-policy-service Bot added the needs-triage label Nov 7, 2025

Change to say component packages

44030c2

DrusTheAxe requested changes Nov 8, 2025

View reviewed changes

DrusTheAxe requested changes Nov 17, 2025

View reviewed changes

Update the spec

ca1651a

codendone reviewed Nov 19, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

codendone reviewed Nov 19, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

codendone reviewed Nov 19, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackages.md Outdated

codendone reviewed Nov 20, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

Dreynor87 changed the title ~~User/chriwall/msix version spec~~ 2.0 msix version spec Nov 20, 2025

Move old to deprecated, and edit the existing in place for 2.0 design

c75c85a

RDMacLachlan reviewed Nov 21, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

Add more specifics about version and experimental stuff

299ffb9

codendone reviewed Nov 25, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

codendone reviewed Nov 25, 2025

View reviewed changes

ChrisGuzak reviewed Dec 1, 2025

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

dotMorten reviewed Dec 4, 2025

View reviewed changes

thomasclaudiushuber reviewed Dec 5, 2025

View reviewed changes

Clarify things, and add tag build bumbers

c81fbcb

Scottj1s reviewed Jan 12, 2026

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

Chris Wall (WIN SDE) added 2 commits January 12, 2026 14:07

Minor spelling and formatting

aefde20

Change how preview numbering works

d677ce2

Scottj1s approved these changes Jan 20, 2026

View reviewed changes

DrusTheAxe requested changes Jan 20, 2026

View reviewed changes

DrusTheAxe reviewed Jan 20, 2026

View reviewed changes

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

codendone approved these changes Jan 20, 2026

View reviewed changes

Respond to newest comments

e3d05ad

codendone approved these changes Jan 21, 2026

View reviewed changes

Comment thread specs/Deployment/WindowsAppSDKVersioning.md Outdated

Comment thread specs/Deployment/WindowsAppSDKVersioning.md Outdated

Comment thread specs/Deployment/MSIXPackageVersioning.md Outdated

Dreynor87 and others added 3 commits January 21, 2026 12:26

Update specs/Deployment/WindowsAppSDKVersioning.md

2d94bb8

Co-authored-by: Mike Crider <45052236+codendone@users.noreply.github.com>

Update specs/Deployment/WindowsAppSDKVersioning.md

f07f1f8

Co-authored-by: Mike Crider <45052236+codendone@users.noreply.github.com>

Update specs/Deployment/MSIXPackageVersioning.md

c5247ec

Co-authored-by: Mike Crider <45052236+codendone@users.noreply.github.com>

Merge branch 'main' into user/chriwall/MSIXVersionSpec

c5275a8

Merge branch 'main' into user/chriwall/MSIXVersionSpec

557d953

DrusTheAxe self-requested a review March 19, 2026 22:13

DrusTheAxe approved these changes Mar 19, 2026

View reviewed changes

Dreynor87 enabled auto-merge (squash) March 19, 2026 22:27

Dreynor87 merged commit 0038c23 into main Mar 19, 2026
49 checks passed

Dreynor87 deleted the user/chriwall/MSIXVersionSpec branch March 19, 2026 23:52

	*Shorter Tags as needed* "-preview" adds 8 characters to package Name. "-experiental" adds
	*Shorter Tags as needed* "-preview" adds 8 characters to package Name. "-experimental" adds


		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.

Conversation

Dreynor87 commented Nov 7, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DrusTheAxe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codendone commented Nov 20, 2025

Uh oh!

DrusTheAxe commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DrusTheAxe Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DrusTheAxe commented Mar 18, 2026

Uh oh!

Dreynor87 commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Dreynor87 commented Mar 19, 2026

Uh oh!

azure-pipelines Bot commented Mar 19, 2026

Uh oh!

Dreynor87 commented Mar 19, 2026

Uh oh!

azure-pipelines Bot commented Mar 19, 2026

Uh oh!

Uh oh!

DrusTheAxe commented Nov 20, 2025 •

edited

Loading

DrusTheAxe Jan 20, 2026 •

edited

Loading

Dreynor87 commented Mar 18, 2026 •

edited

Loading