Interface stability
To provide predictability and stability when developing Terraform HCL, Ping Identity’s development practices align with development guidelines set out by Hashicorp and follow the expectations of the Hashicorp community.
When developing Terraform providers, Ping Identity follows the SemVer (Semantic Versioning) methodology set out at Semver.org.
This includes a regular cadence of major, minor and patch versions of each Terraform provider. Releases are issued on the respective GitHub code repositories using GitHub’s Releases feature. Changelogs are compiled on each release that provide a list of issues resolved, enhancements, new features, general updates, and any breaking changes that might cause HCL developers to alter the Terraform code in order to use the update.
High-level descriptions of the release types are:
-
Major releases: Typically once every year or couple of years. Major releases are issued when significant changes are made to the Terraform provider and typically require customers to change their HCL code, otherwise known as breaking changes.
-
Minor releases: Typically on a planned schedule, such as every few weeks or aligned with product releases. Minor releases are issued when the providers are enhanced with additional, optional functionality and can also include planned bug fixes.
-
Patch releases: Typically ad-hoc, patch releases are issued between minor releases where bug fixes or documentation updates must be released before the next minor release.
Learn more about major, minor, and patch releases at Semver.org
Breaking changes
Breaking changes to a Terraform provider typically require the customer Terraform developer to make changes to the written HCL before they can use the update.
Breaking changes are required periodically to ensure Ping Identity’s Terraform providers remain aligned with the product API. Significant breaking changes are typically planned in advance to be released in-bulk in the major release cycle.
As part of Ping Identity’s development practices, breaking changes are kept to a minimum and are planned as technical debt in the major release cycle. It’s uncommon for breaking changes to occur in minor and patch releases.
Occasionally, breaking changes cannot be included in the major release cycle and must be included in a minor release to ensure that the provider functions correctly. These breaking changes are marked clearly in the release notes.
Some examples of breaking changes are: * Scheduled removal of previously deprecated functionality. * Renaming resources, data sources, or functions without following a deprecation path. * Renaming or removing schema fields without following a deprecation path. * Changing an Optional field to be Required in a resource or data source schema.
When breaking changes are made to a provider, these are highlighted in the release notes. If the change requires significant rework of HCL code, or the corrective action cannot be included in the release note, or if there are many breaking changes to be handled, then a specific guide might be created and published on the Terraform registry to assist with the conversion process. Upgrade and migration guides are typically created when major releases are issued.