Specification: UserMessages manifest field by denelon · Pull Request #6201 · microsoft/winget-cli

denelon · 2026-05-03T20:24:28Z

📖 Description

Adds the full specification for the UserMessages manifest field, covering how messages are shown during install, upgrade, uninstall, and download flows. The spec includes the flow behavior matrix, CLI arguments, settings, PowerShell cmdlet integration, and an update to doc/specs/spec-template.md.

Created with GitHub Copilot assistance.

🔗 References

Resolves #3483

🔍 Validation

Specification content reviewed by Trenly.

✅ Checklist

Signed the Contributor License Agreement
Linked to an issue
Updated Release Notes (if applicable)
Updated documentation (if applicable)
Updated Copilot instructions (if build, architecture, or conventions changed)

📋 Issue Type

Bug fix
Feature
Task

Add specification for UserMessages manifest field (microsoft#3483). Includes: - New UserMessages manifest field for displaying messages to users - Flow behavior matrix for install, upgrade, uninstall, and download - CLI arguments for UserMessages settings overrides - Settings object for global UserMessages configuration - PowerShell cmdlet integration details - Deprecation path and schema impact guidance Also updates spec-template.md with Deprecation Path section and settings/arguments guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

JohnMcPMS · 2026-05-04T16:31:47Z

+
+The existing `InstallationNotes` field is a single string displayed after a successful install. Community feedback in [#3483](https://github.com/microsoft/winget-cli/issues/3483) identified several limitations:
+
+1. **No flow specificity.** The same message appears regardless of whether the user is installing, upgrading, or uninstalling. Upgrade and uninstall operations have no mechanism for user-facing notes at all.


Does the same message appear when upgrading/uninstalling, or does no message appear?

JohnMcPMS · 2026-05-04T16:41:50Z

+            "maxLength": 10000,
+            "description": "Message displayed to the user upon completion of a package upgrade."
+        },
+        "PreUninstall": {


Putting anything in the manifest and making it an expectation that this will affect uninstall is complicating to the current architecture. What version of this message affects uninstall? Are we expected to retrieve this messaging even if the package was not installed through winget? Hopefully this spec answers those questions later, but the answer may make the overall cost of implementing higher to set up the infrastructure.

JohnMcPMS · 2026-05-04T16:43:22Z

+
+### Schema Version
+
+This change requires a new manifest schema version (the next minor version after the current release, e.g., 1.13.0). The `UserMessages` field is added to:


I would assume we actually want to jump the schema versions to match the client versions.

JohnMcPMS · 2026-05-04T16:48:36Z

+
+### Existing `InstallationNotes` Field
+
+The existing `InstallationNotes` field is **unchanged** in this schema version. It continues to function as it does today. During the transition period, manifests may include both fields for backward compatibility.


Suggested change

The existing `InstallationNotes` field is **unchanged** in this schema version. It continues to function as it does today. During the transition period, manifests may include both fields for backward compatibility.

The existing `InstallationNotes` field is **unchanged** in this schema version. It continues to function as it does today. During the transition period, manifests should include both fields for backward compatibility.

Otherwise you get no notes in older clients.

JohnMcPMS · 2026-05-04T16:50:25Z

+Do you wish to continue? [Y/n]:
+```
+
+The user is prompted to confirm. Entering `N` cancels the operation. Entering `Y` or pressing Enter proceeds.


This will for sure break some people's automation, but they of course have the tools today to ensure that it wouldn't (disabling interactivity or just using PowerShell).

JohnMcPMS · 2026-05-04T17:15:13Z

+| `--ignore-pre-action-messages` | `install`, `upgrade`, `uninstall`, `repair`, `import` | Suppresses pre-action messages and their prompts for this invocation. Post-action messages are still shown. |
+| `--ignore-post-action-messages` | `install`, `upgrade`, `uninstall`, `repair`, `import` | Suppresses post-action messages for this invocation. Pre-action messages and prompts are still shown. |
+
+**Precedence:** CLI arguments override settings. If a user has `userMessages.disablePreActionMessages` set to `false` in settings but passes `--ignore-pre-action-messages`, the pre-action messages are suppressed for that invocation.


There is no ability to have the setting set to disable messages but then request messages for a specific invocation. I don't know that this is a problem, just calling it out.

JohnMcPMS · 2026-05-04T17:19:42Z

+
+The COM API must surface `UserMessages` in a structured manner for programmatic consumers.
+
+A new `IPackageUserMessages` interface is introduced, and a new versioned interface (e.g., `IPackageCatalogInfo2` or `IPackageVersionInfo2`) exposes a `UserMessages` property that returns this object. This follows the established WinGet pattern for additive COM API changes — new interface versions are introduced rather than modifying existing interfaces, ensuring existing consumers remain compatible.


This should either be vague about the names or extremely specific and accurate about both names and the objects that implement them.

I think it is reasonable to simply state, "The data will be available in the COM API as six strings" without prescribing exactly how. It is also reasonable to prescribe the exact shape and how it is linked. But this half describes something that is definitely not how even this part will look.

JohnMcPMS · 2026-05-04T17:22:30Z

+
+### PowerShell Cmdlets
+
+The WinGet PowerShell module cmdlets consume the COM API and must surface `UserMessages` appropriately.


It feels like we might want to consider exposing the settings via COM so that well behaved callers (like our own PS module) could leverage them to make decisions about the use of these optional data points.

JohnMcPMS · 2026-05-04T17:23:32Z

+| `winget import` | Each package's `Pre*` shown, prompt Y/n per package | Each package's `Post*` shown | Follows the same per-package model |
+| WinGet Configuration (DSC) | Displayed in log output, no prompt | Displayed in log output | Configuration is inherently non-interactive |
+| `winget show` | N/A | N/A | `show` displays `UserMessages` as package metadata (see below) |
+| `winget repair` | `PreInstall` shown, prompt Y/n | `PostInstall` shown | Repair reuses install messages |


Is that appropriate? I suppose it depends on the actual repair action to some degree.

JohnMcPMS · 2026-05-04T17:29:06Z

+
+#### Find-WinGetPackage / Show-WinGetPackage
+
+The `Show-WinGetPackage` (or `Get-WinGetPackage`) cmdlet should include `UserMessages` in its output when displaying package metadata, allowing users to review messages before deciding to install:


🤖 hallucinating? I know that a Show type command has been requested, but we don't have it. And Get doesn't make sense as that is for already installed things.

florelis · 2026-05-04T18:03:51Z

+- **Clients that support `UserMessages`:** Display `UserMessages.PostInstall` and ignore `InstallationNotes`.
+- **Clients that do not support `UserMessages`:** Display `InstallationNotes` (current behavior, unaffected by the unknown field).


Should we require that they be the same text in winget-pkgs?
I can't think of an example, but it seems like having users get different messages may cause issues.

florelis · 2026-05-04T18:14:09Z

+| `winget repair` | `PreInstall` shown, prompt Y/n | `PostInstall` shown | Repair reuses install messages |
+| `winget export` | N/A | N/A | Export captures package list, not messages |
+| Operation failure | `Pre*` shown before attempt | `Post*` NOT shown | Post-messages only appear on success |
+| `disableInstallNotes` setting enabled | `Pre*` still shown (not affected) | `Post*` still shown (controlled by `userMessages` settings, not `disableInstallNotes`) | Legacy setting does not affect new fields |


I would expect this to at least disable post install messages. If I set this at some point, I wouldn't want the messages to start showing up again just because the developers decided to change the name of the field.

florelis · 2026-05-04T18:17:42Z

+
+| Scenario | Pre-message | Post-message | Notes |
+|----------|-------------|--------------|-------|
+| `winget install` | `PreInstall` shown, prompt Y/n | `PostInstall` shown | Standard single-package install |


Nit: Could you standardize the language for the message columns? It's a bit confusing having to reason about it while considering that shown == displayed == still shown and suppressed == not shown

florelis · 2026-05-04T18:27:12Z

+   - Messages do not contain ANSI escape sequences or control characters.
+   - Messages do not contain URLs that appear to be phishing attempts (leveraging existing content moderation if applicable).
+4. **Deprecation warnings:** During the transition period, if a manifest contains `InstallationNotes` but no `UserMessages.PostInstall`, a warning (not an error) may be emitted suggesting the manifest author add the `UserMessages` equivalent.
+5. **Rendering validation:** Validate that pre-messages render cleanly when displayed (no truncation at the 2048-character limit that would break mid-word or mid-sentence).


Wouldn't this fall under schema validation?

## 📖 Description Adds `.github/instructions/specs.instructions.md` for specification authoring guidance and updates `.github/copilot-instructions.md` to reference it. This was split from #6201 to keep the specification content separate from tooling guidance. Created with GitHub Copilot assistance. ## 🔗 References Resolves #6204 ## 🔍 Validation - Reviewed the instruction content and the related Copilot instruction update. ## ✅ Checklist - [x] Signed the [Contributor License Agreement](https://cla.opensource.microsoft.com) - [x] Linked to an issue - [ ] Updated [Release Notes](../doc/ReleaseNotes.md) (if applicable) - [x] Updated documentation (if applicable) - [x] Updated [Copilot instructions](.github/copilot-instructions.md) (if build, architecture, or conventions changed) ## 📋 Issue Type - [ ] Bug fix - [x] Feature - [ ] Task --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

microsoft-github-policy-service Bot added the Issue-Feature This is a feature request for the Windows Package Manager client. label May 3, 2026

This comment has been minimized.

Sign in to view

Trenly reviewed May 3, 2026

View reviewed changes

Comment thread doc/specs/#3483 - UserMessages.md Outdated

Comment thread doc/specs/#3483 - UserMessages.md Outdated

Trenly reviewed May 3, 2026

View reviewed changes

Comment thread .github/instructions/specs.instructions.md Outdated

This comment has been minimized.

Sign in to view

denelon mentioned this pull request May 3, 2026

Make InstallationNotes flow-dependent #3483

Open

denelon marked this pull request as ready for review May 3, 2026 21:33

denelon requested a review from a team as a code owner May 3, 2026 21:33

Trenly force-pushed the denelon/user-messages-spec branch from 9b713bc to 77b3d97 Compare May 3, 2026 23:58

denelon force-pushed the denelon/user-messages-spec branch from 77b3d97 to 8c80355 Compare May 4, 2026 03:19

denelon mentioned this pull request May 4, 2026

Add Copilot instructions for writing specifications #6205

Merged

8 tasks

denelon removed the Issue-Feature This is a feature request for the Windows Package Manager client. label May 4, 2026

microsoft-github-policy-service Bot added the Issue-Feature This is a feature request for the Windows Package Manager client. label May 4, 2026

denelon removed the Issue-Feature This is a feature request for the Windows Package Manager client. label May 4, 2026

microsoft-github-policy-service Bot added the Issue-Feature This is a feature request for the Windows Package Manager client. label May 4, 2026

JohnMcPMS reviewed May 4, 2026

View reviewed changes

florelis reviewed May 4, 2026

View reviewed changes


		The existing `InstallationNotes` field is a single string displayed after a successful install. Community feedback in [#3483](https://github.com/microsoft/winget-cli/issues/3483) identified several limitations:

		1. No flow specificity. The same message appears regardless of whether the user is installing, upgrading, or uninstalling. Upgrade and uninstall operations have no mechanism for user-facing notes at all.


		### Schema Version

		This change requires a new manifest schema version (the next minor version after the current release, e.g., 1.13.0). The `UserMessages` field is added to:


		### Existing `InstallationNotes` Field

		The existing `InstallationNotes` field is unchanged in this schema version. It continues to function as it does today. During the transition period, manifests may include both fields for backward compatibility.


		The COM API must surface `UserMessages` in a structured manner for programmatic consumers.

		A new `IPackageUserMessages` interface is introduced, and a new versioned interface (e.g., `IPackageCatalogInfo2` or `IPackageVersionInfo2`) exposes a `UserMessages` property that returns this object. This follows the established WinGet pattern for additive COM API changes — new interface versions are introduced rather than modifying existing interfaces, ensuring existing consumers remain compatible.


		### PowerShell Cmdlets

		The WinGet PowerShell module cmdlets consume the COM API and must surface `UserMessages` appropriately.


		#### Find-WinGetPackage / Show-WinGetPackage

		The `Show-WinGetPackage` (or `Get-WinGetPackage`) cmdlet should include `UserMessages` in its output when displaying package metadata, allowing users to review messages before deciding to install:

		- Clients that support `UserMessages`: Display `UserMessages.PostInstall` and ignore `InstallationNotes`.
		- Clients that do not support `UserMessages`: Display `InstallationNotes` (current behavior, unaffected by the unknown field).

Conversation

denelon commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📖 Description

🔗 References

🔍 Validation

✅ Checklist

📋 Issue Type

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

denelon commented May 3, 2026 •

edited

Loading