Versioning
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 type | Increment frequency | Characteristics | Example |
|---|---|---|---|
| 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
- 📅 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:
| Designation | Description | Characteristics | Example |
|---|---|---|---|
| -alpha.N | Early development builds. | ⚠️ Potentially unstable, not for production use. 🔄 May contain incomplete features. |
1.1.0-alpha.1 |
| -beta.N | Feature-complete builds undergoing testing. | ✅ Suitable for testing environments. 🔍 Feature-frozen, focusing on stability and bug fixes. |
1.1.0-beta.1 |
| -rc.N | Release 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.
How it works
- 📝 Identifies commits made since the last version.
- 🔢 Determines the new version based on predefined rules.
- 🚀 Automatically generates and publishes the new version.
Version support timeline
- Active support (current major version):
🚀 Receives feature enhancements, bug fixes, and security patches. - 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
- 📜 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.
Tip
For more information about the release schedule, refer to the Release cycle page.