Interface stability
To provide predictability and stability when developing with Ping Identity’s client SDKs, Ping Identity’s development practices follow the Semantic Versioning 2.0.0 methodology set out at Semver.org.
This includes a regular cadence of major, minor, and patch versions of each client project. Releases are issued on the respective GitHub code repositories using GitHub’s Releases feature. Changelogs are compiled into release notes on each release and provide a list of resolved issues, enhancements, new features, general updates, and any breaking changes that might cause developers to alter their application project 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 client project and typically require customers to change their application project 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 when 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 Ping SDK client project typically require the developer to make changes to the written application code before they can use the update.
Breaking changes could be required periodically to ensure Ping Identity’s client projects 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 except when a project is not yet released to version 1.0.
Occasionally, breaking changes cannot be included in the major release cycle and must be included in a minor release to ensure that the SDK client project 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 functions, methods, or data structures without following a deprecation path. * Renaming or removing data-structure fields without following a deprecation path. * Changing an "Optional" field to be "Required" in a function signature.
When breaking changes are made to an SDK client project, these are highlighted in the release notes. If the change requires significant rework of application project code, 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 to assist with the conversion process. Upgrade and migration guides are typically created for major releases.