One of the best things about shared PowerShell scripts and modules is that they change a lot. The authors, the community, and development teams are continuously improving them. But, that creates a responsibility for users to discover changes and for development teams to help us do so. I love finding out about new features, but I kick myself when I discover, way too late, that a new feature I didn't know about could really have improved my productivity.
So, check the release notes! (Get-Module's ReleaseNotes property (PSModuleInfo.ReleaseNotes) was introduced in PowerShell 5.0.)
Beginning in PowerShell 5.0, all modules have a ReleaseNotes property on the module object. Get-Module gets release notes from the module manifest. Modules and scripts that PowerShellGet installs get release notes from the ScriptInfo.xml or ModuleInfo.xml file And, modules that PowerShell Get installs have both.
So, if you can't find the release notes from one source...
Try another source.
You can also get release notes for scripts that PowerShellGet installs. (Tip: Omit the .ps1 in the script name.)
Like help, release notes and change logs benefit the authors and collaborators as much as the end-user. But, the content can vary widely.
But, I'll take a changelog in release notes rather than no data at all.
There's not much official guidance. The PSRepositoryItemInfo that PowerShellGet commands return isn't documented anywhere, because it's really just a named PSCustomObject. The ModuleInfo object that Get-Module returns is documented in MSDN, but its ReleaseNotes property isn't well defined...
And, there's not (yet) much guidance from Get-Help...
.... so module authors just do what they think is best.
A quick survey of the modules in PowerShell Gallery shows that nearly one-third of the modules have a ReleaseNotes value, about 20% of the ReleaseNotes values are URLs; almost all URLs link to GitHub repos, mainly Changelog.md pages.
The remaining 80% consist of release note strings for the module, either the current version...
Or, all versions...
The core modules from Microsoft don't have release notes, but I suspect that we'll see them in 6.0 open-source versions.
I think this is fine, at least for now. It gives us some time to figure out what's really useful to users. At some point, the community will publish best-practice guidelines, but it's good to have some time to experiment.
Beginning in PowerShell 5.0 (and continuing in PowerShell 6 on all platforms, so far), there are ReleaseNotes properties on two different objects. They're independent and have different data sources.
To get the ReleaseNotes for a module:
PS C:\> (Get-Module -List xDSCUtils).ReleaseNotes https://github.com/nanalakshmanan/xDSCUtils/blob/master/README.md
PS C:\ps-test> (Find-Module AzureRM).ReleaseNotes https://github.com/Azure/azure-powershell/blob/dev/ChangeLog.md
PS C:\> (Get-InstalledModule PowerForensics).ReleaseNotes - Added Nano Server compatibility - Squashed DataRun parsing error
To get the ReleaseNotes for a script:
PS C:> (Find-Script Posh-DiskHealth).ReleaseNotes https://github.com/GavinEke/POSH-DiskHealth
PS C:> (Find-Script Test-Credential).ReleaseNotes Updated $Domain default value to $Credential.GetNetworkCredential().Domain. Added support for multipule credential objects to be passed into $Credential.
For extra value, use the version parameters of the cmdlets to find the differences between versions.
PS C:\ps-test> Find-Module PSCX -AllVersions | Format-Table -Property Name, Version, ReleaseNotes -Wrap Name Version ReleaseNotes ---- ------- ------------ Pscx 3.2.2 Pscx 184.108.40.206 What's New in PSCX 3.2.1 July 29, 2015 * Updated to support PowerShell 5.0. * Fixed bug in Get-Parameter related to getting dynamic parameter info. * Updated Expand-Archive to output DirectoryInfo and FileInfo objects for the extracted directories and files when using -PassThru. * Updated Get-TypeName to normally write the typename to the standard output stream. However, if -PassThru is specified the object input to the command is output and the typename is written directly to the host UI. This allows you to insert Get-TypeName -PassThru into the pipeline to observe which object types a flowing in the pipeline. Pscx 220.127.116.11 What's New in PSCX 3.2.0 October 23, 2014 * New Edit-File cmdlet that edits a file in-place using regular expressions and corresponding replacement strings. The cmdlet attempts to determine the original encoding of the file and preserve that encoding. * Fixed issue with the nested FileSystem module. It's format data had to be updated to handle wider column output from Get-ChildItem now that WMF 5.0 ...
To add the ReleaseNotes property to your module (Get-Module):
To add the ReleaseNotes property to PowerShellGet modules (Get-InstalledModule):
In all cases, the value of the ReleaseNotes parameter is a string array. Enter a URL, an extended string, or a here-string.
In the module manifest, the ReleaseNotes key must be a member of the PSData hash table in the PrivateData hash table. You can use a snippet or add the ReleaseNotes key manually.
If you don't enclose the ReleaseNotes key in PrivateData, Import-Module fails, because it considers ReleaseNotes to be an invalid key. And, you can put anything in PrivateData, but Get-Module doesn't populate the ReleaseNotes property value unless the ReleaseNotes key is in PSData.
Because Import-Module fails when it finds an unknown or invalid key in the module manifest, the PowerShell Team is putting all of its its new keys in PrivateData to prevent breaking changes, like the one caused by the HelpInfoUri key. The team puts official PowerShell keys in PSData to distinguish them from keys defined by a module author.
Best-practice standards are important, but I'm secretly pleased that there wasn't much initial guidance for the ReleaseNotes value, because it gave people time to experiment. Here's my first draft of guidance. I'd like to hear your opinions.
Special thanks to Aaron Jensen for his contributions.
But, most importantly, maintain and share release notes. It will help you, your colleagues and collaborators, and the end-user.