Versioning Policy

Versioning Policy

This page outlines our approach to versioning, detailing how we increment versions, handle pre-release designations, automate versioning, and structure our release cycle. It also covers our support policy, upgrade recommendations, and how we communicate changes to ensure a smooth user experience.


Version Numbering Scheme

We follow a modified semantic versioning scheme in the format X.Y.Z[-designation], where:

Version TypeIncrement FrequencyCharacteristicsExample
X (Major Version)Evaluated every two development cycles but only released if there are significant changes.🚨 May introduce breaking changes.
🔹 Requires explicit upgrade steps.		1.0.0 → 2.0.0
Y (Minor Version)Every development cycle✅ Maintains backward compatibility.
✨ Introduces new features and functionality.		1.0.0 → 1.1.0
Z (Patch Version)As needed, outside the regular cycle🔧 For hotfixes, security patches, and critical updates.
✅ Maintains backward compatibility.		1.1.0 → 1.1.1

Breaking Change Scenario

When a breaking change is necessary:

  • 📅 It will be scheduled for a major version release.
  • 📣 It will be documented in advance with migration guidance.
  • ⚠️ Deprecated features will emit warnings before removal.

Pre-Release Designations

We use the following pre-release designations when applicable:

DesignationDescriptionCharacteristicsExample
-alpha.NEarly development builds.⚠️ Potentially unstable, not for production use.
🔄 May contain incomplete features.		1.1.0-alpha.1
-beta.NFeature-complete builds undergoing testing.✅ Suitable for testing environments.
🔍 Feature-frozen, focusing on stability and bug fixes.		1.1.0-beta.1
-rc.NRelease Candidates.🚀 Expected to be stable and production-ready.
🔧 Only critical bug fixes applied before the final release.		1.1.0-rc.1

Examples

Potential Releases

  • 1.0.0 → Initial stable release
  • 1.0.1 → Patch with bug fixes
  • 1.1.0-alpha.1 → Alpha for next minor
  • 1.1.0-beta.1 → Beta for next minor
  • 1.1.0-rc.1 → Release candidate
  • 1.1.0 → Stable minor release
  • 1.2.0 → Next minor release
  • 2.0.0 → New major version


Versioning Automation

To ensure an automated and predictable versioning process, we follow Semantic Versioning principles. This ensures that changes impact the correct version in a structured way.

How It Works

  1. 📝 Identifies commits made since the last version.
  2. 🔢 Determines the new version based on predefined rules.
  3. 🚀 Automatically generates and publishes the new version.

Version Support Timeline

We maintain two support tiers:

  1. Active Support (Current Major Version):

    • 🚀 Receives feature enhancements, bug fixes, and security patches.

  2. Security Support (Post Active Support):

    • 🔒 Receives only critical security patches.

❗️

Important

Older versions do not receive further updates or support.


Upgrade Path Recommendations

  • Minor version upgrades (1.0.0 → 1.1.0) should be straightforward and require minimal effort.
  • Major version upgrades (1.2.0 → 2.0.0) may require planning and testing.
  • 📖 We provide upgrade guides for each major version.

Communication of Changes

For each release, we provide:

  • 📜 Release Notes detailing:
    • 🌟 New features, improvements, and bug fixes.
    • ⚠️ Known issues and breaking changes (with migration paths).
  • 📚 Documentation Updates reflecting API, configuration, and behavioral changes.
  • 📢 Pre-Release Announcements for major versions in advance.

Versioning of Dependencies

  • 🔄 Internal dependencies follow the same versioning scheme.
  • 🔧 External dependencies are managed to maintain compatibility throughout a major version lifecycle.

Backward Compatibility Commitment

This versioning policy applies to all new releases. We commit to maintaining the described support windows for all future versions.

📘

Releace Cycles

For more information about the release schedule, refer to the Release Cycle page.