From f2075a6226025d3a2df8682e49b14a73588290c2 Mon Sep 17 00:00:00 2001 From: Tamas Juhasz Date: Thu, 27 Nov 2025 13:06:08 +0100 Subject: [PATCH 1/3] README.md updated and Versioning.md added --- README.md | 22 +++++++---- VERSIONING.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 8 deletions(-) create mode 100644 VERSIONING.md diff --git a/README.md b/README.md index 184e33b..32121ca 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ For `infobip-api-java-client` versioning we use [Semantic Versioning][semver] sc Published under [MIT License][license]. -The library requires Java 11 and is compatible with the latest Java versions. +The library requires Java 11 and is compatible up to and including Java 19. ## Installation @@ -199,27 +199,32 @@ Example of webhook implementation with Spring Web framework: } ``` #### Two-Factor Authentication (2FA) -For 2FA quick start guide, view [these examples](two-factor-authentication.md). +For the 2FA quick start guide, view [these examples](two-factor-authentication.md). #### Email -For Email quick start guide, view [these examples](email.md). +For the Email quick start guide, view [these examples](email.md). #### WhatsApp -For WhatsApp quick start guide, view [these examples](whatsapp.md). +For the WhatsApp quick start guide, view [these examples](whatsapp.md). #### Messages API -For Messages API quick start guide, view [these examples](messages-api.md). +For the Messages API quick start guide, view [these examples](messages-api.md). #### Moments -For Moments quick start guide, view [these examples](moments.md). +For the Moments quick start guide, view [these examples](moments.md). + +## Versioning + +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. For pull requests, go to the `CONTRIBUTING` [file][contributing] related to it. This code is auto generated, and we are unable to merge any pull requests form here. +Feel free to open an issue on the repository if you see any problem or want to request a feature. For pull requests, go to the `CONTRIBUTING` [file][contributing] related to it. This code is auto generated, and we are unable to merge any pull requests form here. This code is auto generated, and we are unable to merge any pull request from here, but we will review and implement changes directly within our pipeline, as described in the `CONTRIBUTING` [file][contributing]. -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 @@ -227,3 +232,4 @@ For anything that requires our imminent attention, contact us @ [support@infobip [semver]: https://semver.org [license]: LICENSE [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..a73865f --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,101 @@ +# Versioning Strategy + +This document defines the versioning strategy for the Infobip Java API Client SDK. + +--- + +## 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 Javadoc 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` → `Enum`). +* 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 Java 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. Java and Dependency Compatibility Policy + +### 4.1 Minimum Java Version Changes + +Increasing the **minimum supported Java version** (e.g., Java 11 → Java 21) 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., Jackson 2.17.0 → 2.17.2). +* 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., Jackson 2.15 → 2.16). +* 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., Jackson 2 → 3, OkHttp 3 → 4) should be shipped in major releases. +* Framework switches (e.g., Gson → Jackson), 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 be2098c7e94ab17b93af1d2d54a925c23b82266d Mon Sep 17 00:00:00 2001 From: Tamas Juhasz Date: Fri, 28 Nov 2025 09:20:56 +0100 Subject: [PATCH 2/3] Accidental overwriting reverted to orignal state in README.md. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 32121ca..16cd289 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ For `infobip-api-java-client` versioning we use [Semantic Versioning][semver] sc Published under [MIT License][license]. -The library requires Java 11 and is compatible up to and including Java 19. +The library requires Java 11 and is compatible with the latest Java versions. ## Installation From 43151fd8c08eb3b8b7345fc29198568fbe36c1c7 Mon Sep 17 00:00:00 2001 From: Tamas Juhasz Date: Fri, 28 Nov 2025 13:27:57 +0100 Subject: [PATCH 3/3] VERSIONING.md guide updated. --- VERSIONING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index a73865f..7e68266 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 Java Version Changes -Increasing the **minimum supported Java version** (e.g., Java 11 → Java 21) 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 Java version** (e.g., Java 11 → Java 21) 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