Pipelines should warn against incorrect inclusion / exclusion of DisplayVersion

[mdanish-kh]

Description of the new feature/enhancement

The general advice (as of writing this issue) regarding AppsAndFeaturesEntries: DisplayVersion & version range issues arising from it is:

• If a single manifest requires inclusion of DisplayVersion, then all manifests of that PackageIdentifier should contain DisplayVersion
• DisplayVersion should not be used when it's equal to PackageVersion field

This context is easy to miss when contributing package manifests. The pipelines should warn PR authors when:

• They include DisplayVersion in a manifest update when previous manifests don't have this field
• They exclude DisplayVersion in a manifest update when all previous manifests have this field
• Some manifests of the package have DisplayVersion field while others don't
• DisplayVersion being used in the manifest is equal to the PackageVersion
• DisplayVersion differs from PackageVersion by trailing .0s or in a similar fashion where it would make no difference matching wise to the CLI

The most prominent issues caused by failing to adhere to these guidelines:

• "Infinite upgrade" problem seen in [Package Issue]: Amazon.SAM-CLI #127319 (comment), voidtools.Everything.Lite updated to latest version but winget keeps showing update available #88726
• Making the index inconsistent, thereby breaking publish pipelines (Reduce client mapping code and to avoid future auto-update issue #181438)

Proposed technical implementation details (optional)

No response

[stephengillie]

This is essential for matching, which drives upgrades.

Implementation thoughts:

Since the validation pipeline performs a package install, this data should be available in validation VM just afterwards, then become emitted in the logs as a pipeline message or warning - maybe DisplayVersion Mismatch - the DisplayVersion from the manifest does not match data in Windows Registry or similar. And have a PR label attached. From there, various PR automation could transport the error into the PR comments.

Ideally, this message wouldn't block the rest of the validation pipeline process - similar to the "needs manual review" type of output, this would emit into logs, and our existing PR automation would add the appropriate label.

[mdanish-kh]

Since the validation pipeline performs a package install, this data should be available in validation VM just afterwards, then become emitted in the logs as a pipeline message or warning - maybe DisplayVersion Mismatch - the DisplayVersion from the manifest does not match data in Windows Registry or similar. And have a PR label attached. From there, various PR automation could transport the error into the PR comments.

I think the implementation detail above is relevant to issues like:

• Check that version number in "Add/Remove programs" matches manifest version during manifest validation #13620
• [New Feature]: Validate all AppsAndFeaturesEntries fields #118948

This issue focuses more on checking the state of previous manifests in a given PackageIdentifier and determining whether including / excluding AppsAndFeaturesEntries: DisplayVersion would cause version range issues or not. Even if the DisplayVersion correctly matches whatever is written to ARP, including it in the manifest may not always be a good idea. There are many cases where having a valid PackageVersion field that matches ARP suffices; using DisplayVersion in these cases causes unnecessary version mapping, and leads to the "infinite upgrade" scenario.

[mdanish-kh]

For this the implementation details can be:

Query all manifests of a given PackageIdentifier:

• If the immediate previous manifest contains DisplayVersion:

  • Verify that the new manifest also contains DisplayVersion
  • Verify that DisplayVersion != PackageVersion field in the manifest

• If the immediate previous manifest does not include DisplayVersion:

  • Verify the newer manifest does NOT include it

• Throw a warning if inconsistencies are found i.e., some manifests include DisplayVersion and some don't

[stephengillie]

For this the implementation details can be:

Query all manifests of a given PackageIdentifier:

• If the immediate previous manifest contains DisplayVersion:

  • Verify that the new manifest also contains DisplayVersion
  • Verify that DisplayVersion != PackageVersion field in the manifest

• If the immediate previous manifest does not include DisplayVersion:

  • Verify the newer manifest does NOT include it

• Throw a warning if inconsistencies are found i.e., some manifests include DisplayVersion and some don't

Oh yes,, these checks should also be performed. Maybe during manifest validation, which happens earlier in the process, before the package install into a VM.

Currently, a reduced form of this check (only checking against 1 previous manifest) is performed during validation. Shifting this check forward in the process would be beneficial. For best user experience, all errors should be presented at once and early in the process, allowing them all to be fixed in one remediation cycle.

• Right now, users can encounter a manifest error, an installer error, and a validation error, and have to come back and fix their PR 3 times or more. Moving this check forward in the pipeline process will help reduce that number closer to 1.

This check (sanity check DisplayVersion against previous manifest versions) couples nicely to the other check (verify installed DisplayVersion matches manifest DisplayVersion) to help ensure matching.