Spec for package pinning

[yao-msft]

null

Microsoft Reviewers: Open in CodeFlow

[Trenly]

I might also suggest winget pin remove --all --force or winget pin reset --force to fully reset the pinning state, similar to a source reset, where the force argument would be required

[yao-msft]

I'll add winget pin reset --force

[yao-msft]

yes, they'll be same

[florelis]

Does that also go for the package query arguments this will use? So, having --query, --id, --name, --moniker, --tag, --command? (I'm already excluding --manifest as that is not linked to a source.)

[yao-msft]

yes, any args for finding a package and applicable for search a package to pin.

[Trenly]

How likely is this case to truly exist? A quick check of winget-pkgs shows that no packages there currently have a version which includes *. I fear this may be limiting functionality for an edge case that is almost non-existent

[yao-msft]

Unlikely, I just wanted to clarify that for any gate version, only the .* in the end is considered. If there is a need to match1.*.*, user should probably use 1.* instead. This is just for simpler logic for parsing and matching gate version, to be less error-prone.

But if there's a need to match gate version like 1.*.2 where 1.1.2 matches and 1.0.3 does not match, I can make a version part with only * as a wild card, that's also fine.

[Trenly]

I'm not sure that it really matters too much. Thank you for the explanation on the reasoning!

[Trenly]

Clarification would be useful around 1.0.1a or 1.0.1b

[florelis]

Also things like gate version 1.0.1 (no .*) and version 1.0.1.2.

[Trenly]

Can you clarify the behavior when a pin already exists for a package? Will a user have to remove the existing pin and re-pin? A winget pin update command? Or is this what the --force parameter is for, so that a warning can be displayed that existing pins would be overwritten and they must force the addition to override it?

[yao-msft]

yes, I will add more clarification and example for it.
Basically, if a pin configuration already exists, we'll show a warning and exit. User will remove the pin and add a new one, or use --force to override

[Trenly]

Users might not be able to pin packages from the msstore source unless, as @JohnMcPMS pointed out, it is made very clear that pinning is not a guarantee the package won't be upgraded outside of winget, it's just saying that it won't be upgraded as part of winget upgrade. Either documentation around this needs to be considered, or provisions should be made to not allow pinning of packages installed from msstore.

With the traditional Microsoft Store packages, the Microsoft Store automatically updates programs. Users would not be able to pin those packages. I need to see if there is a way to pin packages from being automatically updated by the Microsoft Store.

Originally posted by @denelon in #1894 (comment)

[jantari]

If the pins are recorded for each source present at the time of adding the pin then if a user later adds another source the package would be upgraded from there right? I think from a UX perspective if I ran winget pin add <package> --blocking I would expect the package to be pinned indefinitely for all current and future sources. So I would prefer if pinning a package without explicitly listing individual sources would result in a different, bool SQLite column being set like AllSources rather than multiple entries with arbitrary SourceIdentifiers.

[yao-msft]

Re @Trenly , all these pin configurations only apply to winget behaviors, we cannot control upgrades outside winget. Blocking simply blocks winget from doing anything to the blocked package. In the original issue, some community member wanted winget to block upgrade for some specific package, because they want to perform upgrades outside winget through other channel.

Re @jantari , yes, it would be ideal to pin an installed package for all future sources. Due to current limitation on the package identifier generation for installed packages, pinning from installed source is put into future considerations. Currently, a package identifier for an installed package is its produce code, if user upgrade the package, the pin is no longer in effect since most likely product code will change after an upgrade. Regarding AllSources in sqlite, it's trivial to record it, but we don't have efficient cross reference for remote sources yet, so it's unfortunately moved as future considerations.

[Trenly]

Are the powershell cmdlets considered here? I'm assuming the commands will be something like Add-WingetPackagePin and Remove-WingetPackagePin, but didn't see those in here

[jantari]

The verbs Add and Remove are usually used for resources that support having multiple things added to them, such as with Add-Content appending to a file or Add-ADGroupMember adding one or more members to a group which may countain N amount of members total.

Since a package would probably only ever have one pin state (yes with options or no) at a time, I would maybe suggest the verbs Suspend/Resume (updates), Get/Set/Reset (a pin) or Lock/Unlock (a version),

[jantari]

Ok the:

There can only be one pinning configuration for a specific package.

threw me off here, I can see from further down the document now that a package can have multiple co-existing pins for different sources. That makes sense, so Get/Add/Remove/Reset (or Remove without parameters = Reset) makes sense

[Trenly]

I was thinking along the lines that each pin is an item in a collection of pins (even if the package identifier is different, they are still part of the collection), so something like Get-WingetPackagePin would show all pins (Similar to how Get-AppxPackage shows all AppxPackages installed) since Add and Remove are referring to the collection of pins, not the individual package pin

[yao-msft]

Powershell support is not considered in this spec yet :(. I'll add it to future list and we'll probably get back to it after core feature is done.

edit: winget team is moving Powershell cmdlets to call Com Apis to perform winget operations, that means Com Api needs to support the pinning feature first before Powershell support could be enabled. More work is needed..

[Trenly]

Suggested change

	- Improvements to import export commands to work seamlessly with existing package pinning configurations.
	- Improvements to import export commands to work seamlessly with existing package pinning configurations.
	- Pinning multiple versions of a single package installed side by side

[Trenly]

Suggested change

	- Package imports may be impacted by user's package pinning configuration.
	- Package imports may be impacted by user's package pinning configuration.
	- Package exports may not consider user's package pinning configuration

[denelon]

We need to determine the PowerShell (approved nouns & verbs) syntax. @ryfu-msft is working on native PowerShell.

[florelis]

What if the package gets updated to 1.3.0 outside of winget? Do we show a warning, offer a way to re-install the pinned version?

[denelon]

I've commented about that situation before. I think it would be good for WinGet to show when a "pin" has been violated in cases other than "blocking". I think we would also want to make sure that if a user applied "--force" or some other formal override, that the pin is either removed or ideally updated and the user is informed.

[florelis]

Nit: extra "to"

Suggested change

	- **Pinning:** The package is excluded from `winget upgrade --all` but allowed in `winget upgrade <specific package>`, a new argument `--include-pinned` will be introduced to let `winget upgrade --all` to include pinned packages.
	- **Pinning:** The package is excluded from `winget upgrade --all` but allowed in `winget upgrade <specific package>`, a new argument `--include-pinned` will be introduced to let `winget upgrade --all` include pinned packages.

[florelis]

Do we want to add aliases for the subcommands? I see we are using source rm for source remove, rm for uninstall, ls for list. Personally, I'd like to have consistency and add pin rm, pin ls (and source ls).

[yao-msft]

I agree, consistency is better.

[denelon]

Yep, and I bet @Trenly would agree :)

[Trenly]

;)

[florelis]

We need to define how each type of pin interacts with RequireExplicitUpgrade. I'm guessing something like this:

• Pinning pins and RequireExplicitUpgrade behave the same way. Even though they do the same things, we allow pinning in case the manifest gets updated to remove the field or the package updates to a version without that field.
• Blocking pins override RequireExplicitUpgrade, so we won't update even if the include flag is added. We have to both remove the blocking pin and pass the flag when updating.
• Gating pins block from updating beyond the gated version, even with the special flag for RequireExplicitUpgrade, and updates within that version range still require the special flag.

Does that sound good?

[JohnMcPMS]

Seeing as the actual feature is merged, I'm merging this spec PR for historical purposes.