User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active

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


ReleaseNotes EndUserSources


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

 ReleaseNotes NoneFromGetModule

Try another source.

ReleaseNotes FromPSGallery


You can also get release notes for scripts that PowerShellGet installs. (Tip: Omit the .ps1 in the script name.)

ReleaseNotes Script



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.


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

ReleaseNotes Msdn

And, there's not (yet) much guidance from Get-Help...

ReleaseNotes 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 pages.

ReleaseNotes Survey


The remaining 80% consist of release note strings for the module, either the current version...

ReleaseNotes OneVersion


Or, all versions...

ReleaseNotes allVersions


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.


To get the ReleaseNotes for a module:

 To get the ReleaseNotes for a script:


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

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.

ReleaseNotes PrivateDataPSData

ReleaseNotes works


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.


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.


If you have questions about our products, please post in our support forum.
For licensed customers, use the forum associated with your product in our Product Support Forums for Registered Customers.
For users of trial versions, please post in our Trial Software Questions forum.