Add Suggestion information when Modules are renamed or deprecated due to authors moving onto other work

[kilasuit]

Summary of the new feature / enhancement

Currently there is no mechanism for when modules are renamed to aid in the discoverability of the new name of the module, nor is there in the Gallery a way (that I know of) for a request of merging the results from Module A & Module B together when it is just a simple rename.

I propose to add to PSResourceGet (& would love it backported to PowerShellGet) the ability for some metadata based checking to surface a message to a user when a module has been renamed, completely deprecated or archived. This would be based on giving guidance on adding a new set of tags to modules as part of this process so that this aids discoverability going forward, both for managed deprecations and as optionally giving out recommendations on similar modules too.

These tags perhaps should be & would be added into the existing tags array in the PSD1
Deprecated perhaps paired with NewModuleName:NewModuleName & this in the new module DeprecatedModule:OldModuleName
Archived perhaps paired with 1/more of SuggestedModule:OtherModuleName

Doing so would aid further in discoverability and provide an easier to query graph link that could potentially be optimised on backend calls to the gallery's database layer, whilst, if done correctly, likely would provide opportunity for an interesting set of data to view as use of the gallery continues to grow.

This is based on my comment for this as a strategy going forward, after a number of rethinks on how I think it best to achieve this painful process.

Proposed technical implementation details (optional)

When as user runs Find-PSResource for a module that has been deprecated, it returns a suggestion item as well for any module that has been suggested by the author of the module that has been searched for.

An Example would be for ThreadJob which is now replaced by Microsoft.PowerShell.ThreadJob
Results would be returned for both ThreadJob and Microsoft.PowerShell.ThreadJob

If a User instead Install-PSResource for the deprecated module they should ideally be prompted with one/more modules that have been provided

An example might be that a module like PoshRSJobs had deprecated and recommended

An Example for say the InvokeBuild Module would be to also return suggestion item for ModuleBuilder any other similar projects too.

[kilasuit]

I realise this is a much bigger than just PSResourceGet request as will need additional guidance documentation to go with this.

It's also not the only possible way forward so should definitely get some discussion on whether this approach makes most sense or not

[ThomasNieto]

I could see this as its own key in PSData of the obsolete module. Then the gallery and installing the module could say this module is deprecated and the replacement is new module.

@{
    PSData = @{
        ReplacementModule = 'NewModule'
    }
}

Another could also be a Deprecated key to indicate the module has been deprecated when no replacement exists on the gallery and install.

@{
    PSData = @{
        Deprecated = $true
    }
}

[kilasuit]

@ThomasNieto Seems we think quite alike 😉 I say that as I had originally thought of using that way which I stated in this comment however there may be engine performance impact from that, as per @SeeminglyScience's comment and on further thinking it makes sense to me to make use of the tags in this way.

[ThomasNieto]

@kilasuit That linked proposal was that the replacement module would have the metadata saying which module it replaced. The concern from the WG is that during command discovery / module import every module would have to be checked to see if it replaced the one to be imported.

This proposal is different as this is only for PSGallery and Install-PSResource to consume during an action. Its not related to command discovery or module import.

To fix that linked proposal and removing the concern of enumerating all modules is to use this proposal and have the old module like ThreadJob have metadata that Microsoft.PowerShell.ThreadJob is the replacement during command discovery or module import and write the warning.

As a side note nothing in the engine uses PrivateData or PSData other than Get-Module formatter to display the prerelease label.