(GH-68) Move Puppetization Automation helper functions into the module & document usage

[michaeltlombardi]

This PR moves the helper functions for automating the Puppetization of PowerShell DSC modules from the util script into the module itself as both private and public functions. In the process, it adds unit tests and documentation and refactors as necessary to improve UX and bring the module functions into alignment as described in detail in each commit.

• Resolves Add Repeatable Process for Building & Releasing a Puppetized Module #68

TODO:

• Move Update-ForgeDscModule into the module as a public function with unit tests and documentation
• Move Publish-NewDscModuleVersion into the module as a public function with unit tests and documentation
• Delete the no-longer needed Util.ps1 script file
• Write documentation in the project readme for using the converted functions to manually build/release Puppetized PowerShell modules with DSC Resources to the Forge in preparation for Auto-Puppetize modules via GHA #69

[michaeltlombardi]

Manually updating existing Puppetized DSC Modules

You can run the following command to update ever version of every module in the dsc namespace on the forge:

$UpdateParameters = @{
  ForgeNameSpace = 'dsc'
  ForgeToken = 'my_forge_token'
  BuildFolderPath = 'C:\dsc'
  PackageFolderPath = 'C:\pkg'
}
Update-ForgeDscModule @UpdateParameters

However, as this is hundreds of versions across dozens of modules, it's very slow.
Probably preferable is to do the following:

$UpdateParameters = @{
  ForgeNameSpace = 'dsc'
  ForgeToken = 'my_forge_token'
  BuildFolderPath = 'C:\dsc'
  PackageFolderPath = 'C:\pkg'
  # This ensures we don't rebuild dozens of releases for
  # each module, only the latest 5
  MaximumVersionCountToRebuild = 5
  ErrorAction = 'Stop'
}
$ModulesToUpdate = Get-ForgeModuleInfo -ForgeNameSpace 'dsc' | Select-Object -ExpandProperty Name
"Number of Modules to Update: $($ModulesToUpdate.Count)"
Update-ForgeDscModule @UpdateParameters -Name $ModulesToUpdate[0..9]
Update-ForgeDscModule @UpdateParameters -Name $ModulesToUpdate[10..19]
Update-ForgeDscModule @UpdateParameters -Name $ModulesToUpdate[20..29]
# Continue until out of modules to update

Manually publishing missing versions of PowerShell modules with DSC Resources to the Forge

You can run the following command to Puppetize and publish every version of every PowerShell module with DSC Resources found on the PowerShell Gallery and not in the dsc namespace on the Forge:

$PublishNewVersionParameters = @{
  ForgeNameSpace = 'dsc'
  ForgeToken = 'my_forge_token'
  BuildFolderPath = 'C:\dsc'
  PackageFolderPath = 'C:\pkg'
}
Publish-NewDscModuleVersion @PublishNewVersionParameters

However, as this is hundreds of versions across more than 300 modules, it's very slow.
Probably preferable is to do the following:

$PublishNewVersionParameters = @{
  ForgeNameSpace = 'dsc'
  ForgeToken = 'my_forge_token'
  BuildFolderPath = 'C:\dsc'
  PackageFolderPath = 'C:\pkg'
  # This ensures we don't try building older versions
  # of already Puppetized modules
  OnlyNewer = $true
  # This ensures we only try to build 10 versions in
  # a single execution, shrinking our batch processing
  MaxBuildCount = 10
  ErrorAction = 'Stop'
}
# Repeat until no new versions are published
Publish-NewDscModuleVersion @PublishNewVersionParameters

If you encounter any errors, stop and then document and file a bug.

[michaeltlombardi]

I added the documentation here instead of anywhere long lived as we're planning to obviate it in the next ticket with automation.

[david22swan]

LGTM