• Scripting
• Modules
• Windows PowerShell 5.0
• Scripts

User Rating: 5 / 5

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.

#GOTO: Best practices for PowerShell release notes.

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.)

What's in Release Notes?

Like help, release notes and change logs benefit the authors and collaborators as much as the end-user. But, the content can vary widely.

Typically:

• Release notes are designed for the end-user. They describe only the changes that users can detect and they do so in simple, non-technical language.
• Changelogs are designed for the developers. They include changes, like refactoring, that the user might not be able to detect.

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.

How to Get Release Notes:

 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.

• Get-Module returns a ModuleInfo object with a ReleaseNotes property. Its data comes from the ReleaseNotes key in the module manifest.
• Find-Module, Find-Script, Get-InstalledModule, and Get-InstalledScript return a PSRepositoryItemInfo object with a ReleaseNotes property. The source is the ModuleInfo or ScriptInfo.xml file for the module or script.

To get the ReleaseNotes for a module:

• (Get-Module [-ListAvailable] <ModuleName>).ReleaseNotes
  This is valid on any module, regardless of how it was installed.

  PS C:\> (Get-Module -List xDSCUtils).ReleaseNotes
  https://github.com/nanalakshmanan/xDSCUtils/blob/master/README.md 

• (Find-Module <ModuleName>).ReleaseNotes
  This command gets the release notes for a module without installing it. This is valid only on PowerShellGet modules.

  PS C:\ps-test> (Find-Module AzureRM).ReleaseNotes
  https://github.com/Azure/azure-powershell/blob/dev/ChangeLog.md

• (Get-InstalledModule <ModuleName>).ReleaseNotes
  This is valid only on modules that PowerShellGet installed.

  PS C:\> (Get-InstalledModule PowerForensics).ReleaseNotes
  - Added Nano Server compatibility
  - Squashed DataRun parsing error

 To get the ReleaseNotes for a script:

• (Find-Script <ScriptName_noextension>).ReleaseNotes
  This is valid only on PowerShellGet scripts. You can do this before you install the script.
  

  PS C:> (Find-Script Posh-DiskHealth).ReleaseNotes
  https://github.com/GavinEke/POSH-DiskHealth

• (Get-InstalledScript <ScriptName_noextension>).ReleaseNotes
  This is valid only on PowerShellGet scripts.

  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 3.2.1.0 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 3.2.0.0 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
...

How to Add ReleaseNotes

To add the ReleaseNotes property to your module (Get-Module):

• In the module manifest, use the ReleaseNotes parameter of New-ModuleManifest.

To add the ReleaseNotes property to PowerShellGet modules (Get-InstalledModule):

• For modules in PowerShell Gallery, use the ReleaseNotes parameter of Publish-Module.
• For scripts in PowerShell Gallery, use the ReleaseNotes parameter of Publish-Script.

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 Guidelines for Release Notes  (Draft 1)

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.

• Use an online source: The highest priorities for release notes are accuracy and completeness. Dynamic online documents, such as well-moderated GitHub changelogs, are more likely to be accurate than static text that's difficult to change. If you're already maintaining a What's New or changelog, just give us a link.
• Be consistent: If you're publishing a PowerShellGet module, enter the same content in the ReleaseNotes of the module manifest and the PowerShellGet ModuleInfo.xml (Publish-Module) file. It's disconcerting when they're different for the same module. And, it's easy enough to copy.
• Maintain it: One of the hardest and most annoying tasks is to try to go through a code base and figure out changes long after they were made. (In PowerShell, when features weren't documented, it was almost always because someone forgot that they had changed something.) Add a changelog requirement to your pull request process. Then, before you release, grab an outsider and have them edit the changelog to create release notes.
• User-focused: As a best practice, release notes, which are user-focused, are different from change logs, which are developer-focused. I know this is a stretch, but this is a best-practice ideal.
• Cumulative: Make the release notes cumulative. If a user is several versions behind, they have to get the release notes for each version. It's much easier to read release notes that have all versions.
• Organized: Create a template with indentation in a format like this and stick to it.
  
  • Version <number> : Use semantic versioning
    
    • Release date
    • Breaking changes: Describe and explain mitigations/work-arounds.
    • New features: Link to About topics online.
    • New commands: Link to online help for each command.
    • Bug fixes

But, most importantly, maintain and share release notes. It will help you, your colleagues and collaborators, and the end-user.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Windows PowerShell MVP. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next