App-configurable compatibility options spec: RuntimeCompatibilityOptions

[codendone]

Spec for app-configurable compatibility options, which can be set via RuntimeCompatibilityOptions APIs or via project properties.

[Scottj1s]

Suggested change

	<WindowsAppSDKRuntimePatchMode>1.7.3</WindowsAppSDKRuntimePatchMode>
	<WindowsAppSDKRuntimePatchMode1>1.7.3</WindowsAppSDKRuntimePatchMode1>

[Scottj1s]

numeric suffixes should be consistent between xml and api

[codendone]

Oops, I forgot to submit my comments from last week.

[DrusTheAxe]

LGTM

[oldnewthing]

I think this text is trying to say "The Windows App Runtime will automatically lock the configuration at some point. Calling Apply also locks. Since you don't really know when the Windows App Runtime locks, you should call Apply as soon as possible, if you intend to call it at all."

[codendone]

Correct.

[oldnewthing]

What is the policy/process for retiring old RuntimeCompatibilityChange values?

is it that when (say) 1.5 goes out of support, then we comment out all the 1.5 compatibility values [but hold their values so they won't get reused]? Or do we leave them in place forever, even though they don't do anything?

What happens if we have

enum RuntimeCompatibilityChange
{
  None = 0,
  // 1.7.1
  ResetPolarityOnWidgetChange, // does specifying this disable the reset?
  WidgetColorLeak, // specifying this restores the leak?

  // 1.8.1
  GadgetCrashWhenShownWhileDisabled,
}

and now we have a 1.7.2 compatibility change. Do we add it at the end, so the numbers go 1.7.1 to 1.8.1 to 1.7.2?

or do we reserve 100 change numbers between 1.7.1 and 1.8.1 so we can insert more 1.7.x values later?

[codendone]

The current plan is that only 1.7.x builds will contain the 1.7.x changes. When moving to 1.8.0, all entries (other than None) will be removed -- apps will need to evaluate compile errors at that time if they were disabling 1.7.x changes. The code for 1.8 will never include any containment checks from 1.7 (those containment checks stay in that version's release branch).

Regarding the numbers, it isn't shown here, but each enum will actually be assigned to the internal ADO ID of the servicing change. (Or some other unique identifier in the future, such as if we choose to ensure there are issues logged on GitHub for all servicing fixes and use those issue numbers.)

[oldnewthing]

Can you give a more realistic example of an enum name?

For example, suppose we made a change to reset the polarity of a widget when it changes. What would we call the enum that suppresses the auto-reset?

Suppose we made a change to fix a crash when a gadget is shown while it is disabled. What would we call the enum that re-enables the crash?

[codendone]

For those examples, I'd propose these names:

• WidgetPolarityReset
• ShowDisabledGadgetCrash

Using the list of fixes in 1.6.4, we might have used these names:

• MultiLineTextBoxSelection
• DDLMPackageInstall
• MissingDetoursExport
• CommandBarMenuPositioning
• OldGraphicsHardwareCrash
• PointerEventWindowCloseCrash
• UIAInitReentrancyCrash
• CompositionCapabilitiesCrash
• ExpandedUnicodeSupportForTextBoxes
• PackageManagerRegisterNewerHandling

We may need a separate discussion on the naming scheme to use.

[oldnewthing]

Would we ever need a third patch level, if somebody wants to run on 3 different versions of the Windows App Runtime?

[codendone]

No, for "A/B Forward" we specifically intend only to support two adjacent versions, such as for an app to move from 1.7 to 1.8.

[oldnewthing]

Why not

<WindowsAppSDKRuntimePatchLevels>1.7.1,1.8.2</WindowsAppSDKRuntimePatchLevels>

?

[codendone]

The intent is to stay close to the API, which could then make the question the same as the question for line 216, where we want to limit to just two versions.