(#3477) Replace Get-ChecksumValid with Assert-ValidChecksum cmdlet.

[vexx32]

Description Of Changes

• Remove Get-ChecksumValid
• Add Assert-ValidChecksum
• Add tests for command to verify behaviour matches the old command.
• Add alias for backwards compatibility with packages.
• Minor fixes for the doc-gen script to address issues I ran into.
• Added a framework we can use in future for deprecating old aliases or to-be-removed commands in a simple and standardised way.

This PR does not contain the compiled XML help information for the command. In discussion with @gep13 we agreed that it would be better to compile that in the final release. I will have a docs PR linked here in a moment, watch this space.

Note: As this PR is part of #3477 and is thus a breaking change to a degree, we will need to cut a support/2.x branch once this is merged, so that none of the breaking changes associated with #3477 inadvertently make their way into the 2.x versions.

Motivation and Context

See #3477

Documentation PR: https://github.com/chocolatey/docs/pull/1075

Testing

Tested locally with the accompanying Pester tests:

1. From an administrative PowerShell session
2. Run .\build.ps1
3. Run .\Invoke-Tests.ps1 -Tag AssertValidChecksum
4. From VS, run the integration tests and verify there are no unexpected issues.

Proving out the deprecated commands framework

After running the above, close and reopen the admin PowerShell session, and then follow these steps:

1. Apply the following patch: Get-ValidCheckSum-deprecation-verification.patch
2. Rerun the prior steps to run the build and tests again, including the code and test change.
3. Monitor the output from the tests; near the start of the test run, you should see a warning issued about the test calling Get-ChecksumValid and that the alias is deprecated and should be replaced with Assert-ValidChecksum

Operating Systems Testing

Windows 10

Change Types Made

• [ ] Bug fix (non-breaking change).
• [ ] Feature / Enhancement (non-breaking change).
• [x] Breaking change (fix or feature that could cause existing functionality to change).
• [ ] Documentation changes.
• [x] PowerShell code changes.

Change Checklist

• [x] Requires a change to the documentation.
• [x] Documentation has been updated.
• [x] Tests to cover my changes, have been added.
• [x] All new and existing tests passed?
• [ ] PowerShell code changes: PowerShell v3 compatibility checked?

Related Issue

Part of #3477

[vexx32]

There is one final matter to resolve before this PR is fully ready; help documentation for the cmdlet. I will have a corresponding PR opened on the docs repository by tomorrow, and then update the Chocolatey.PowerShell.dll-help.xml file for this PR accordingly.

[vexx32]

There is one final matter to resolve before this PR is fully ready; help documentation for the cmdlet. I will have a corresponding PR opened on the docs repository by tomorrow, and then update the Chocolatey.PowerShell.dll-help.xml file for this PR accordingly.

After talking with @gep13 we have agreed it is best not to update the XML here at present, as it would require increasingly complicated messing around with the associated docs PRs as we rewrite more commands, and will instead opt to update the help XML file before a release artifact is created.

[vexx32]

@gep13 are we good to merge this? just gave it a rebase so I think everything's more or less sorted?

[gep13]

@vexx32 said... are we good to merge this?

Yes, I think we can move forward with this! Thanks for getting this done!