Versioning guide

README.md

@@ -197,21 +197,25 @@ Example of webhook implementation:
     }
 ```
 #### 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).
 
 #### Send email
-For send email quick start guide please check [these examples](email.md).
+For the send email quick start guide please check [these examples](email.md).
 
 #### Moments
-For Flow & Forms quick start guide please check [these examples](moments.md).
+For the Flow & Forms quick start guide please check [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 issue or feature request. 
+Feel free to open an issue on the repository if you see any problem or want to request a feature.
 Check the `CONTRIBUTING` [file][contributing] for details about contributions - in short, we will not merge any pull requests since this code is auto-generated.
 
-However, if you find something that requires our imminent attention feel free to contact us @ [support@infobip.com](mailto:support@infobip.com).
-
+However, if you find something that requires our immediate attention, feel free to 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
@@ -221,3 +225,4 @@ However, if you find something that requires our imminent attention feel free to
 [authentication-apikey]: https://www.infobip.com/docs/essentials/api-authentication#api-key-header
 [datetimeformat]: https://www.infobip.com/docs/essentials/api-essentials/integration-best-practices#date-formats-backward-compatibility
 [receive-inbound-sms]: https://www.infobip.com/docs/api/channels/sms/inbound-sms/receive-inbound-sms-messages
+[versioning]: VERSIONING.md

VERSIONING.md

@@ -0,0 +1,101 @@
+# Versioning Strategy
+
+This document defines the versioning strategy for the Infobip C# 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` → `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.
+
+**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 C# 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. C# and Dependency Compatibility Policy
+
+### 4.1 Minimum C# Version Changes
+
+Increasing the **minimum targeted .NET framework version** (e.g.,.NET Standard 2.0 → .NET Standard 2.1) 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
+
+**PATCH**
+
+* Only patch-level dependency updates are allowed (e.g., Polly 7.2.0 → 7.2.4).
+* 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., Polly 7.0 → 7.2).
+* 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., Polly 7 → 8) 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.