search

JustinGrote / ModuleFast

A "fast and loose" way to install modules from Powershell Gallery quickly. Meant for CICD, not production
Other
74 stars 5 forks source link

Possible improvement of help #47

Closed johlju closed 7 months ago

johlju commented 7 months ago

Thoughts for your consideration.

Help for Install-ModuleFast:

  1. The For more information... should be moved down to a separate row and not be part of the last list item to more easily find the information: https://github.com/JustinGrote/ModuleFast/blob/44c656f3322b953c6db264fdf2cb576b751638ff/ModuleFast.psm1#L53-L54

  2. Missing '!' in shorthand, and how it can be combined with other shorthand.

  3. How the command Clear-ModuleFastCache relates to the parameter -Update or do not relate to clarify that they are different and -Update does not run Clear-ModuleFastCache (not sure of this myself after reading the help)?

  4. The parameter -Prerelease help. Clarify that it forces prerelease on all specifications, also that ! shorthand will get prereleases on individual specification regardless if this parameter is specified.

  5. "Using the CI switch will write a lockfile". Would be great if the lockfile specification could be documented so it possible to programmatically create it.

  6. In the parameter help for CILockFilePath it says "This is ignored if CI is not present.". Does it mean to say only when $env:CI -eq $true?

  7. The parameter ModuleFastInfo is missing help description.

  8. The parameter for Plan (and WhatIf) says "Output a list of specifications for the modules to install". But should it say something like "Output a list of specifications for the modules to install and lists only modules that are not already available for the user" .

  9. The description for the parameter Plan and WhatIf are different as in the text This can be saved and provided to Install-ModuleFast at a later date. should also be added to paramneter Plan. Or have parameter Plan reference the parameter description of WhatIf for further information so the description is not duplicated (and regress in the future).

  10. Maybe the text for example 9 (CI) should be simplified and reference the text of the CI parameter instead of duplicate the text in the example too?

  11. The shorthand :* is only mentioned in example 8, maybe that should be added to the rest of the shorthand list?

Release notes:

  1. Says If a GUID is specified as part of a ModuleFast specification... but there are no reference on how to specify this GUID.
JustinGrote commented 7 months ago

If I say Agreed below, I will fix in #51

  1. The For more information... should be moved down to a separate row and not be part of the last list item to more easily find the information: https://github.com/JustinGrote/ModuleFast/blob/44c656f3322b953c6db264fdf2cb576b751638ff/ModuleFast.psm1#L53-L54

Agreed

  1. Missing '!' in shorthand, and how it can be combined with other shorthand.

Agreed

  1. How the command Clear-ModuleFastCache relates to the parameter -Update or do not relate to clarify that they are different and -Update does not run Clear-ModuleFastCache (not sure of this myself after reading the help)?

I decided that I will have -Update run Clear-ModuleFastCache implicitly. Implemented 6c6074de303ae7c736be6b14b40c60908c0f50d1

  1. The parameter -Prerelease help. Clarify that it forces prerelease on all specifications, also that ! shorthand will get prereleases on individual specification regardless if this parameter is specified.

Agreed

  1. "Using the CI switch will write a lockfile". Would be great if the lockfile specification could be documented so it possible to programmatically create it.

It's not meant to be created outside of modulefast in the same way the pnpm lockfile is not meant to be managed outside of Modulefast, that is just asking for trouble and bugs/etc. but I'll consider it.

  1. In the parameter help for CILockFilePath it says "This is ignored if CI is not present.". Does it mean to say only when $env:CI -eq $true?

It means the -CI parameter. I'll clarify.

  1. The parameter ModuleFastInfo is missing help description.

It's sort of an implicit parameter but I added help there, thanks.

  1. The parameter for Plan (and WhatIf) says "Output a list of specifications for the modules to install". But should it say something like "Output a list of specifications for the modules to install and lists only modules that are not already available for the user" .

Agreed

  1. The description for the parameter Plan and WhatIf are different as in the text This can be saved and provided to Install-ModuleFast at a later date. should also be added to paramneter Plan. Or have parameter Plan reference the parameter description of WhatIf for further information so the description is not duplicated (and regress in the future).

Agreed

  1. Maybe the text for example 9 (CI) should be simplified and reference the text of the CI parameter instead of duplicate the text in the example too?

  2. The shorthand :* is only mentioned in example 8, maybe that should be added to the rest of the shorthand list?

It is mentioned indirectly in the shorthand section, that wildcards are supported. The * operator is not a special modulefast operator, it's a nuget operator.

  1. Says If a GUID is specified as part of a ModuleFast specification... but there are no reference on how to specify this GUID.

GUIDs are not supported with Shorthand syntax, only ModuleSpecification syntax. I'm not going to provide a lot of info on this because the GUID cannot be verified until install time and its use should be discouraged over using trusted repos that have your module, and relying on module signing, not GUIDs, to verify authenticity.