Built-in support for unsupported packages

[mthalman]

Description of the new feature / enhancement

To avoid being exposed to security vulnerabilities, the importance of running on the latest versions of software is clear. Winget provides an upgrade command to help with this effort. However, it only has knowledge of new versions of a specific package ID. In some cases, a software vendor offers multiple package IDs for different versions. Examples of this:

• Microsoft.DotNet.SDK.5, Microsoft.DotNet.SDK.6
• Oracle.JDK.17, Oracle.JDK.18
• Python.Python.2, Python.Python.3

Upgrades are limited to the versions available for a given package ID. There's no built-in winget experience to upgrade from one package ID to another. For example, winget doesn't provide an experience to upgrade from Microsoft.DotNet.SDK.5 to Microsoft.DotNet.SDK.6. I'm not suggesting it should provide an experience in this proposal. But I do think there are aspects of versioning that winget can improve upon, specifically when the software associated with such package IDs become unsupported.

Let's use Microsoft.DotNet.SDK.5 as an example. This version of the .NET SDK has been out of support since May 2022. But it still shows up in the default search experience with winget:

> winget search Microsoft.DotNet.SDK
Name                           Id                           Version                   Source
---------------------------------------------------------------------------------------------
Microsoft .NET SDK 7.0 Preview Microsoft.DotNet.SDK.Preview 7.0.100-preview.7.22377.5 winget
Microsoft .NET SDK 6.0         Microsoft.DotNet.SDK.6       6.0.400                   winget
Microsoft .NET SDK 5.0         Microsoft.DotNet.SDK.5       5.0.408                   winget
Microsoft .NET SDK 3.1         Microsoft.DotNet.SDK.3_1     3.1.422                   winget

That's not great. There's nothing here that indicates to the user that this is an unsupported product. And having the software vendor simply delete the unsupported package ID from the winget-pkgs repo doesn't provide a great experience for those still dependent on the package. It unilaterally breaks them without providing a path to a supported product.

The proposal is to provide a better experience for users of winget so that they...

1. avoid installing unsupported products without being made aware of that fact.
2. have the necessary information to upgrade/migrate to a supported product.

This would consist of multiple facets:

• Provide a means for package authors to indicate when their package is no longer supported.
• Provide a means for package authors to include an out of support message for users that provides them with the information to move off the unsupported package.
• The default winget search should only show supported packages. Unsupported packages are made visible through the use of an explicit option.
• If a user executes winget install on an unsupported package, the package's "out of support" message should be displayed.
• If a user executes winget upgrade when they have an unsupported package installed, they should be presented with information indicating that they have unsupported packages installed.

Proposed technical implementation details

EndOfSupportDate Property

The first requirement is for package authors to have some means to indicate whether the package is supported or not. This may or may not be known at package creation time. The proposal is to add an optional property to <package-id>.installer.yaml that indicates when support for the package ends:

EndOfSupportDate: <UTC-value>

EndOfSupportNotes Property

Package authors can provide a message for users that explains the end of support status of the package. The proposal is to add an optional property to <package-id>.locale.<locale>.yaml that contains this message:

EndOfSupportNotes: <text>

Winget Search Experience

With this proposal, the winget search command would only show supported packages by default, determined by the EndOfSupportDate property described above. To show unsupported packages, an additional option is provided:

--show-unsupported-packages   Includes unsupported packages in the search results 

In the search output, (unsupported) would be appended to the version for any unsupported packages.

Winget Show Experience

With this proposal, the winget show command would include output that indicates the end of support date and notes.

Winget Install Experience

With this proposal, the winget install command would output warning text provided by the EndOfSupportNotes property described above if they were to install an unsupported package.

Winget Upgrade Experience

With this proposal, the winget upgrade command would, by default, indicate a summary count of any packages that are unsupported. To get more detail, the user would use the --show-unsupported-packages option which displays the end of support details of all unsupported packages.

--show-unsupported-packages   Show unsupported packages

The details would output the text provided by the EndOfSupportNotes property described above.

Example

Let's use the Microsoft.DotNet.SDK.5 package as an example to illustrate this proposal.

In Microsoft.DotNet.SDK.5.installer.yaml, add the following property:

EndOfSupportDate: 2022-05-10T00:00:00Z

In Microsoft.DotNet.SDK.5.locale.en-US.yaml, add the following property:

EndOfSupportNotes: Support for .NET 5 ended on May 10, 2022. Please upgrade to a supported version. You can find supported versions of .NET at https://dotnet.microsoft.com/download/dotnet.

With these settings, the package is appropriately configured to provide a better experience for users when using the winget CLI.

Now when the user attempts to search for .NET SDK with winget, they won't see Microsoft.DotNet.SDK.5 if their system clock is after May 10, 2022:

> winget search Microsoft.DotNet.SDK
Name                           Id                           Version                   Source
---------------------------------------------------------------------------------------------
Microsoft .NET SDK 7.0 Preview Microsoft.DotNet.SDK.Preview 7.0.100-preview.7.22377.5 winget
Microsoft .NET SDK 6.0         Microsoft.DotNet.SDK.6       6.0.400                   winget
Microsoft .NET SDK 3.1         Microsoft.DotNet.SDK.3_1     3.1.422                   winget

But they can get it if they use the --show-unsupported-packages option:

> winget search Microsoft.DotNet.SDK --show-unsupported-packages
Name                           Id                           Version                   Source
---------------------------------------------------------------------------------------------
Microsoft .NET SDK 7.0 Preview Microsoft.DotNet.SDK.Preview 7.0.100-preview.7.22377.5 winget
Microsoft .NET SDK 6.0         Microsoft.DotNet.SDK.6       6.0.400                   winget
Microsoft .NET SDK 5.0         Microsoft.DotNet.SDK.5       5.0.408 (unsupported)     winget
Microsoft .NET SDK 3.1         Microsoft.DotNet.SDK.3_1     3.1.422                   winget

When using winget show, they can see the unsupported status of the package:

❯ winget show Microsoft.DotNet.SDK.5
Found Microsoft .NET SDK 5.0 [Microsoft.DotNet.SDK.5]
Version: 5.0.408
Publisher: Microsoft Corporation
Moniker: dotnet-sdk-5
Description: .NET is a free, cross-platform, open-source developer platform for building many different types of applications.
Homepage: https://dotnet.microsoft.com
License: MIT
Installer:
  Type: burn
  Download Url: https://dotnetcli.azureedge.net/dotnet/Sdk/5.0.408/dotnet-sdk-5.0.408-win-x64.exe
  SHA256: 860f7aec7716141bbc09ce7366feb0f1c96ab330611b4641fea8b068ca7f6cd4
End of support date: 2022-05-10
End of support notes: Support for .NET 5 ended on May 10, 2022. Please upgrade to a supported version. You can find supported versions of .NET at https://dotnet.microsoft.com/download/dotnet.

When attempting to install the package, the user sees the end of support notes:

> winget install Microsoft.DotNet.SDK.5
Found Microsoft .NET SDK 5.0 [Microsoft.DotNet.SDK.5] Version 5.0.408
This application is licensed to you by its owner.
Microsoft is not responsible for, nor does it grant any licenses to, third-party packages.
Downloading https://dotnetcli.azureedge.net/dotnet/Sdk/5.0.408/dotnet-sdk-5.0.408-win-x64.exe
  ██████████████████████████████   147 MB /  147 MB
Successfully verified installer hash
Starting package install...
Successfully installed

WARNING: Support for .NET 5 ended on May 10, 2022. Please upgrade to a supported version. You can find supported versions of .NET at https://dotnet.microsoft.com/download/dotnet.

Now that the user has the package installed, the upgrade experience indicates an unsupported package is installed:

> winget upgrade
Name           Id             Version     Available     Source                                                          --------------------------------------------------------------                                                          Microsoft Edge Microsoft.Edge 90.0.818.66 104.0.1293.54 winget                                                          1 upgrades available.                                          
1 unsupported package installed (use the --show-unsupported-packages option for details).

The user can get details on the unsupported packages using the --show-unsupported-packages option:

> winget upgrade --show-unsupported-packages
Name                   Id                     Version End of Support
--------------------------------------------------------------------
Microsoft .NET SDK 5.0 Microsoft.DotNet.SDK.5 5.0.408 2022-05-10

View the notes for end of support by executing "winget show <Id>"

[mthalman]

cc @MichaelSimons, @ashnaga

[denelon]

We should also think about the experience with winget import and consolidation of the notes.

Other potentially related issues:

• Support redirecting manifests #1899
• Package Tombstones #1900

With any new arguments, we should also consider any appropriate settings to establish default behaviors.

[Trenly]

I would suggest --include-unsupported instead of --show-unsupported-packages, to better align with --include-unknown and to make it more command agnostic