Have you ever wondered why Az.Compute has a different version than the Az module or why a module had documentation but is not available in Cloud Shell?
The following describes our versioning principles, upgrade policies, and preview process for the PowerShell modules for Azure.
Versioning
We follow the semantic versioning principles (https://semver.org/) for all the Azure modules. Essentially this means:
- Major version change for releases with breaking changes.
- Minor version change for functionality with backward compatibility.
- Patch version change for bug fixes or improvements with backward compatibility.
We apply this policy for each module that we own. For example, Az.Storage had one version upgrade that had a breaking change since the initial version and is currently in version 2.4.0. Az.Network had two major upgrades and is now in version 3.3.0.
The Az wrapper module’s goal is to facilitate the acquisition of the different Azure modules. It comprises several modules with different versions like Az.Storage and Az.Network from the previous example.
From the semver rule definition, if a major version upgrade happens for an underlying module, Az will undergo a major version upgrade as well.
Breaking changes
A breaking change is a change in a PowerShell module that can break a script written with a previous version.
The breaking changes fall into two main categories:
- Changes in the modules: cmdlet or parameter deprecated, parameter name change, change from optional to required, returned type change.
- Changes in the default behaviors. For example, soft delete turned on by default for Azure KeyVault.
Upgrading to a new major version of Az will require script validation with this version and implement the necessary changes.
To allow customers to plan for this, we have two policies in place:
Breaking change releases are identified with “Major Release” in the title and have an exclamation mark in the description on GitHub: https://github.com/Azure/azure-powershell/milestones.
Preview
We have two types of preview modules:
- Modules with a 0.X.X version: new modules potentially calling Azure APIs that are not stable. Hence breaking changes may happen at any time, and issues can occur. Modules will remain at least six weeks in preview to allow customer feedback before considering moving the modules to GA.
Preview modules can be found in the reference documentation (https://docs.microsoft.com/powershell/module/) but are not included in the Az wrapper module nor are available in Cloud Shell by default until they can move to a stable version.
- Modules with X.Y.Z-preview version: expose new features of the associated service that may not be stable yet or introduce breaking changes waiting for the next major release.
We publish the reference documentation for all modules including those with a version 0.x.x. However, only the stable modules are present in Cloud Shell. If you want to use a preview module, you must install the specific module individually.
Over the last few months, you told us that it was difficult to find and install modules in preview and I’m pleased to announce that we are working on a solution that will improve the discovery and management of preview modules along with those that are stable. We will be announcing more about this very soon.
Should you be interested in having a preview module move to GA, please help us prioritize by commenting on existing issues listed here: https://github.com/Azure/azure-powershell/issues/12755
As always, any feedbacks and issues are always welcome https://github.com/Azure/azure-powershell/issues/new/choose
The Azure PowerShell team
