Overview
In June 2025, Mage-OS has adopted a new release versioning strategy, following a thorough RFC process. This approach is designed to provide clarity, predictability, and meaning to version numbers, while aligning with both upstream Magento releases and the unique needs of the Mage-OS community.
This policy is in effect starting with Mage-OS Distribution version 1.2.0.
How Mage-OS Versioning Works
- All Mage-OS releases will have three version number parts: {Major}.{Minor}.{Patch}.
- Every Mage-OS Distribution update will add to one of those numbers from the previous release.
- Only the latest Mage-OS release will be supported. You must stay up to date for the latest security patches.
Major Updates
- Any upstream feature release (e.g., Magento 2.4.7, 2.4.8, etc.) triggers a major version update for Mage-OS.
- Major releases may include significant or breaking changes. This includes changes to dependencies or system requirements (like supported versions of PHP).
- Target cadence: Approximately every 6 months, ideally in April and September/October, unless upstream schedules require otherwise.
Minor Updates
- Minor-point releases are broadly compatible by convention, ensuring smoother upgrades and fewer surprises for users.
- Upstream security patch releases (e.g., 2.4.8-p1, -p2, -p3) become minor version updates for Mage-OS.
- Exception: If a security patch introduces major software or dependency changes (such as adding/dropping support for PHP, ElasticSearch, TinyMCE, etc.), it will be treated as a major version update.
Patch Updates
- Patch updates are reserved for small but critical off-schedule fixes to a Mage-OS release.
- These should be uncommon, but feature equivalent to the associated major/minor release.
Why this is the best choice for Mage-OS
The version number reflects the nature of the change:
- Major versions for significant or breaking changes.
- Minor versions for security patches and updates that should not break compatibility.
- Patch versions for urgent, critical fixes that should not break compatibility.
This approach should make it clear what to expect from each release.
This is an intentionally more rapid versioning scheme than Magento Open Source uses itself.
Summary
| Release Event | Mage-OS Version Change | Example |
|---|---|---|
| Feature release (e.g., 2.4.9) | Major | 1.x -> 2.0.0 |
| Security patch (e.g., 2.4.8-p1) | Minor | 1.1.x -> 1.2.0 |
| Security patch with major dependency | Major | 1.x -> 2.0.0 |
| Critical off-schedule fix | Patch | 1.2.0 -> 1.2.1 |
