From 3f6b252c4bd25ab2dcd09593e4966bd67bfd96a3 Mon Sep 17 00:00:00 2001 From: Tamas Juhasz Date: Thu, 27 Nov 2025 10:57:23 +0100 Subject: [PATCH 1/3] Updated readme and versioning guide. --- README.md | 18 ++++----- VERSIONING.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+), 9 deletions(-) create mode 100644 VERSIONING.md diff --git a/README.md b/README.md index 32aa14e..a9e2a7f 100644 --- a/README.md +++ b/README.md @@ -189,28 +189,28 @@ Example of webhook implementation using Flask: ``` #### Two-Factor Authentication (2FA) -For 2FA quick start guide please check [these examples](two-factor-authentication.md). +For the 2FA quick start guide please check [these examples](two-factor-authentication.md). #### Calls -For Calls quick start guide please check [these examples](calls.md). +For the Calls quick start guide please check [these examples](calls.md) -#### Email -For Email quick start guide, view [these examples](email.md). +## Versioning -#### Moments -For Moments quick start guide, view [these examples](moments.md). +This project follows a pragmatic Semantic Versioning approach. +For full details on how versions are managed, please see our [Versioning guide][versioning]. ## Ask for help -Feel free to open issues on the repository for any encountered problem or feature request. +Feel free to open an issue on the repository if you see any problem or want to request a feature. If you want to contribute to this library in any way, please follow the guidelines in [CONTRIBUTING][contributing] file. -For anything that requires our imminent attention, contact us @ [support@infobip.com](mailto:support@infobip.com). +For anything that requires our immediate attention, contact us @ [support@infobip.com](mailto:support@infobip.com). [apidocs]: https://www.infobip.com/docs/api [freetrial]: https://www.infobip.com/docs/essentials/getting-started/free-trial [signup]: https://www.infobip.com/signup [semver]: https://semver.org [license]: LICENSE -[contributing]: CONTRIBUTING.md \ No newline at end of file +[contributing]: CONTRIBUTING.md +[versioning]: VERSIONING.md \ No newline at end of file diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000..be4ad4c --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,101 @@ +# Versioning Strategy + +This document defines the versioning strategy for the Infobip PHP API Client. + +--- + +## 1. Versioning Model + +The SDK follows a **pragmatic Semantic Versioning** model: + +``` +MAJOR.MINOR.PATCH +``` + +While we adhere to the core principles of SemVer, the SDK evolves in tandem with Infobip's backend APIs, which may require **occasional breaking changes in MINOR releases**. These will always be documented clearly. + +### Summary of Intent + +* **MAJOR** → Large, coordinated breaking changes across multiple areas, architectural redesigns, endpoint version migrations. +* **MINOR** → New features, new endpoints, model updates, and in some cases *breaking changes required by API correctness*. +* **PATCH** → Bug fixes, documentation fixes, safe dependency bumps. + +--- + +## 2. Change Classification + +### 2.1 Patch Changes (PATCH) + +PATCH versions include changes that are fully backward compatible: + +* Bug fixes. +* Typo and documentation corrections. +* Safe dependency upgrades. +* Internal refactors with no public API impact. + +--- + +### 2.2 New Features and API Updates (MINOR) + +MINOR versions introduce: + +* New endpoints, webhooks, or new request/response fields. +* Support for new message types, enums, or capabilities. +* Fixing wrong field types (e.g., `string` → `int32`). +* Removing fields or models when upstream endpoints no longer support them. +* Unifying models (e.g., platform enums, validity windows, message statuses). +* Replacing request/response classes due to upstream schema changes. + +**Breaking changes may appear in MINOR releases** when necessary. + +--- + +### 2.3 Major Changes (MAJOR) + +MAJOR releases are reserved for **significant, multi-area-breaking changes**, such as: + +* Full API reorganization. +* Global unification or rework of API surface. +* Endpoint version migrations across several products. +* Architectural redesigns. +* Removal of deprecated features accumulated over multiple MINOR releases. + +--- + +## 3. Handling Upstream API Changes + +* **Correctness takes priority over Python API backward compatibility.** +* When upstream APIs change field types, remove fields, or alter schemas, the SDK must remain consistent. +* Such updates may cause MINOR releases to include breaking changes. +* These will always be documented with a ⚠️ note in the CHANGELOG. + +This ensures the SDK remains reliable and accurate for production usage. + +--- + +## 4. Python and Dependency Compatibility Policy + +### 4.1 Minimum Python Version Changes + +Increasing the **minimum supported Python version** (e.g., Python 3.7 → Python 3.11) is always treated as a **MAJOR** version change. Such a change breaks compilation and runtime compatibility for existing users and therefore constitutes a breaking API change. + +### 4.2 Dependency Upgrade Policy + +**PATCH** + +* Only patch-level dependency updates are allowed (e.g., urllib 1.25.0 → 1.25.3). +* Must not introduce behavior changes, serialization differences, or require consumers to adjust their dependencies. +* Test/build-only dependency bumps are allowed. + +**MINOR** + +* Patch or minor dependency updates are allowed (e.g., urllib 1.24 → 1.25). +* No breaking serialization or model changes caused solely by dependency bumps. + +**MAJOR** + +* All dependency upgrades are allowed, including breaking changes. +* Major dependency upgrades (e.g., urllib 1.25 → 2, pydantic 1 → 2) should be shipped in major releases. +* Framework switches, large refactors, or structural changes belong here. + +All dependency-related breaking changes will be clearly documented in the CHANGELOG. \ No newline at end of file From 26b17d4a6c9194d8ec666ec57808d04dd793c98a Mon Sep 17 00:00:00 2001 From: Tamas Juhasz Date: Fri, 28 Nov 2025 09:24:18 +0100 Subject: [PATCH 2/3] Updated readme and versioning guide. --- README.md | 6 ++++++ VERSIONING.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a9e2a7f..2592b71 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,12 @@ For the 2FA quick start guide please check [these examples](two-factor-authentic #### Calls For the Calls quick start guide please check [these examples](calls.md) +#### Email +For Email quick start guide, view [these examples](email.md). + +#### Moments +For Moments quick start guide, view [these examples](moments.md). + ## Versioning This project follows a pragmatic Semantic Versioning approach. diff --git a/VERSIONING.md b/VERSIONING.md index be4ad4c..457aba2 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -41,7 +41,7 @@ MINOR versions introduce: * New endpoints, webhooks, or new request/response fields. * Support for new message types, enums, or capabilities. -* Fixing wrong field types (e.g., `string` → `int32`). +* Fixing wrong field types (e.g., `string` → `int`). * Removing fields or models when upstream endpoints no longer support them. * Unifying models (e.g., platform enums, validity windows, message statuses). * Replacing request/response classes due to upstream schema changes. From 8734ea3dd56e1012d278596c9b0073607b45e66e Mon Sep 17 00:00:00 2001 From: Tamas Juhasz Date: Fri, 28 Nov 2025 13:29:34 +0100 Subject: [PATCH 3/3] Versioning.md updated. --- VERSIONING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index 457aba2..e98c1ab 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -77,7 +77,7 @@ This ensures the SDK remains reliable and accurate for production usage. ### 4.1 Minimum Python Version Changes -Increasing the **minimum supported Python version** (e.g., Python 3.7 → Python 3.11) is always treated as a **MAJOR** version change. Such a change breaks compilation and runtime compatibility for existing users and therefore constitutes a breaking API change. +Increasing the **minimum supported Python version** (e.g., Python 3.7 → Python 3.11) is always treated as a **MAJOR** version change. Such a change may break compilation and runtime compatibility for existing users and therefore constitutes a breaking API change. ### 4.2 Dependency Upgrade Policy