-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Install-Module doc doesn't address handling of declared dependencies #4383
Comments
@SydneyhSmith Can you comment on this issue? |
I was in the process of raising the same (similar) point until I saw this 'issue'. See below... Missing Documentation and/or Defect? For example, if I have 2 PSModules:
... and ModuleB (v55.0.0, for example) has ModuleA listed in the 'RequiredModules' property of the PSModule manifest (to indicate that ModuleB depends on ModuleA), with a specific version of ModuleA detailed (e.g. ModuleVersion = '1.0.0'), like so...
... then it's not clear (and not documented) that when running...
... this will (assuming both exist in a PSRepository) install both 'ModuleA' (version '55.0.0') and also 'ModuleB' ... although the version of ModuleB might be:
I'd argue the documentation isn't clear on this behaviour, and in addition, the 'Install-Module' could be importing later versions of a depended-upon module, rather than the specific version that is depended on (which means that you're potentially installing, then importing/using incorrect combinations of PowerShell module dependencies). For example, if I've tested with:
..my installation/import as part of a process/script I had written (and had thought to be previously tested and working already) could actually be using (or trying to use):
... which has a breaking change in 'ModuleA' that I've released and published but do not want to be used with 'ModuleB' v55.0.0. It seems to always mean that you get the "wrong" (non-specified/required) version of a depended-upon PSModule if later versions exist. I'd like to see this behaviour default to import the actual, required version if a 'ModuleVersion' is specified in the module manifest (i.e. lowest version required, not highest version required). Real World Example/Problem However, when I run Workarounds Hope that makes sense - Shout/tag if you've any questions. EDIT: Just updated some of the points to try and get terminology correct (i.e. import/install etc.) and versions/dependencies the correct way around. |
In addition, NuGet 'Restore' seems to use "Lowest applicable version"... https://docs.microsoft.com/en-us/nuget/consume-packages/dependency-resolution |
@SydneyhSmith Can you comment on this issue? |
Thanks for the feedback @SphenicPaul and @travis-c-lagrone I appreciate the thoughtful comments
|
@SydneyhSmith Can you summarize the changes need to the docs or submit a PR? You said that the changes should probably go in the "publishing" docs. |
Thanks @sdwheeler I have opened PR #4625 to address this item |
Issue Details
The reference documentation for the
Install-Module
cmdlet of thePowerShellGet
module does not address how declared dependencies are handled when a module is installed (i.e. the "RequiredAssemblies" and "RequiredModules" fields of a module manifest).Context
This topic is actually touched on in the reference documentation for the
-RequiredAssemblies
and-RequiredModules
parameters of theNew-ModuleManifest
cmdlet of theMicrosoft.PowerShell.Core
module. However, it is only with respect to importing and not installing. Moreover, this topic deserves attention in the doc of [Install-Module
], which is what actually implements the behavior in question.More perniciously, I have observed (albeit anecdotally) that PowerShell's behavior of not strongly resolving dependencies at installation-time, but rather weakly resolving dependencies at import-time, can be a cause of confusion. This is particularly when compared to the languages that many new adopters hail from, as their package management facilities more commonly resolve and install dependencies contemporaneously with the installation of the dependent (e.g.
pip
,npm
, and evendotnet
).Proposal
In this context, the band-aid solution of appending a short clarifying statement to
Install-Module
's Notes seems likely to be ineffective.A much more effective solution would encompass (1) a simple statement early in the Description; (2) a ''loud'' warning box with a more forward admonition in the Notes; and (3) a cautionary counter-example with subsequent correction in the Examples.
Finally, a broader resolution might require a short-and-pointed standalone About article that orients newcomers to dependency resolution practices around PowerShell Core (PowerShellGet, other PackageManagement, scripts vs. modules, manifests metadata,
#Requires
directives, etc.), and then builds off that to conclude by cementing a standard (or at least recommended best practice) for contributors.I would propose the second of these three possible solutions for practicality's sake. However, fostering a conversation about dependency resolution designs around the PowerShell language is needed.
E.g.
ScriptFileInfo
's idiosyncratic distinction between "required" and "external"; reconciling#Requires
directives andImport-
cmdlets; dynamic-but-fragile metadata-based resolution at runtime vs. secure-but-heavy packaging at publish-time, etc.Version(s) of document impacted
NA
Impacts 5.0 documentNA
Impacts 4.0 documentNA
Impacts 3.0 documentReason(s) for not selecting all version of documents
The text was updated successfully, but these errors were encountered: