Invoke-AppveyorAfterTestTask: Exception Calling New-DscResourcePowerShellHelp when Type is 'Wiki'

X-Guardian commented 5 years ago

Details of the problem, bug, or enhancement

The changes to New-DscResourcePowerShellHelp made in #325 are causing Invoke-AppveyorAfterTestTask to throw a non-terminating exception calling the function with what is now a non-existing parameter, OutputPath. My fault as I didn't know this function was called from here when I wrote PR #325.

Verbose logs showing the problem (if applicable)

Invoke-AppveyorAfterTestTask `
    -Type 'Wiki' `
    -MainModulePath $mainModuleFolder `
    -ResourceModuleName $moduleName

New-DscResourcePowerShellHelp : A parameter cannot be found that matches parameter name 'OutputPath'.
At C:\projects\officeonlineserverdsc\DscResource.Tests\AppVeyor.psm1:1051 char:39
+         New-DscResourcePowerShellHelp -OutputPath $docoPath -ModulePa ...
+                                       ~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [New-DscResourcePowerShellHelp], ParameterBindingException
    + FullyQualifiedErrorId : NamedParameterNotFound,New-DscResourcePowerShellHelp

Suggested solution to the issue

Options are: 1) Restore the OutputPath parameter back to New-DscResourcePowerShellHelp. Easy enough to do but looking into this, the PowerShell help files are not making it into the final published module. Look at CertificateDsc and ActiveDirectoryCsDsc as examples that have the 'Wiki' parameter on Invoke-AppveyorAfterTestTask and the AppVeyor build logs show the help files being built, but neither of them contain the files when installed from the PowerShell Gallery. Is the ApppVeyor artifact not used for populating the gallery?

2) Remove the 'OutputPath' parameter from the New-DscResourcePowerShellHelp function call in Invoke-AppveyorAfterTestTask. This would output the help files into the relevant resource's en-US directory, but if the AppVeyor artifact isn't being used for populating the gallery, they will still get lost.

2) Remove the call to New-DscResourcePowerShellHelp from Invoke-AppveyorAfterTestTask. It doesn't make sense being in the 'Wiki' type anyway and look for another solution to populate the help files. I prefer having the help files present within the Git repo, so they can be seen and verified before publishing. I was thinking maybe of another opt-in metatest that verified they existed and were up to date. It could then prompt to manually run the script to bring them up-to-date if required.

Thoughts anyone?

PlagueHO commented 5 years ago

Just to answer one of your questions: The AppVeyor artifact is not being used to publish to the PS Gallery. Katies scripts I think rebuild the artifact locally and publish it from there.

I'd go with restoring the OutputPath parameter, because I suspect other maintainers (possibly SharepointDsc) that use this too and a breaking change to the signature might cause other problems.

Also, we don't store the documentation in the Dev branch, only the master branch - and this is all generated during deployment using automation that Katie looks after.

So making too many changes to these processes without having more control over the deployment process is going to be risky. So I'd suggest not making too many changes to this process...yet :grin:

johlju commented 5 years ago

I agree to add back the OutputPath parameter, but if it is not provided then use the current behavior. I just saw this error to, and thought of submitting an issue. Awesome that you are on top of things @X-Guardian! 🙂

PowerShell / DscResource.Tests