Mage-OS 3.1.0 – Bug Fixes & Composer Plugin Improvements

Mage-OS Distribution 3.1.0 is now available. This is a maintenance release built on the same Magento Open Source 2.4.9 base as 3.0.0, with a fix to the Composer root-update plugin and a batch of core stability improvements. There are no dependency additions or removals and no change to PHP support, so it is a low-risk, drop-in upgrade from 3.0.0. We recommend updating at your convenience.

What’s changed

• Composer root-update plugin now supports Mage-OS package names mage-os/composer-root-update-plugin now correctly resolves Mage-OS package names in the require-commerce path, so root composer.json updates and upgrades work cleanly for Mage-OS-named distributions. This resolves the bin/magento setup:upgrade failure some 3.0.0 upgrades hit (Class "MageOS\Installer\Console\Command\InstallCommand" not found) — see the recovery note below if you’re affected. (#7) by @marcelmtz

• Sixteen core stability fixes, all contributed by @ddevallan, including:

  • Let PaymentException propagate from savePaymentInformationAndPlaceOrder, so checkout surfaces the real payment error (#266)
  • Persist the auto-selected payment method when only one is available (#265)
  • Map HTTP 429 (Too Many Requests) in the WebAPI ErrorProcessor (#267)
  • Fix QueryParamsResolver corrupting base64 values and crashing on valueless params (#263)
  • Switch AMQP cron consumers from basic_get polling to basic_consume push (#213)
  • Convert the admin forgot-password email to HTML with a clickable reset link (#261)
  • Plus null-safety, validator, admin-UI, and collection-ordering fixes (#255, #257, #259, #264, #268, #273, #274, #275, #276, #277)

• RMA module updated to 2.3.1 Fixed an unqualified column reference in a database query. (#36) by @norgeindian, reviewed by @SamueleMartini

• Ignition for Magento updated to 1.3.0 The bundled swissup/module-ignition developer tool gains optional JS error reporting and improved stack-trace handling, maintained by Swissup Labs.

Our foundation

Mage-OS 3.1.0 is built on Magento Open Source 2.4.9, the same upstream base as 3.0.0. For details on the upstream release, see the Magento Open Source 2.4.9 release notes.

Thanks to everyone who contributed!

This release was made possible by:

• @ddevallan (Allan Fernandes), from São Paulo, Brazil — the entirety of this release’s core stability work, sixteen fixes spanning checkout, the WebAPI layer, message queues, and the admin UI
• @marcelmtz (Marcel Martinez) — Composer root-update plugin fix and release engineering
• @norgeindian — RMA database query fix
• @SamueleMartini (Samuele Martini) — RMA review and maintainership

And thanks to Swissup Labs for the bundled Ignition developer tool.

Want to participate?

Mage-OS is a community-driven project, and we welcome contributions of all kinds. Whether you’re fixing bugs, adding features, improving documentation, or helping with testing, your contributions make a difference.

• Mage-OS GitHub
• Mage-OS Discord

Installation

New installations

composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition=3.1.0 <install-directory-name>

Upgrading from Mage-OS 3.0.x

composer require mage-os/product-community-edition=3.1.0 --no-update
composer update
bin/magento setup:upgrade

Recovering a broken 3.0.0 upgrade (installer “class not found” error)

If you upgraded to 3.0.0 and bin/magento setup:upgrade failed with Class "MageOS\Installer\Console\Command\InstallCommand" not found, your project’s root composer.json is missing the MageOS\Installer\ autoload entry. The 3.0.0 root-update plugin didn’t apply it for Mage-OS package names; 3.1.0 fixes the plugin. Recover in one of two ways, then re-run bin/magento setup:upgrade:

Option A — add the entry manually. Merge this into the autoload.psr-4 block of your root composer.json:

"MageOS\\Installer\\": "setup/src/MageOS/Installer/"

then regenerate the autoloader:

composer dump-autoload

Option B — let the fixed plugin reconcile it. Update the root-update plugin to 3.1.0, then have it apply the root composer.json delta:

composer require mage-os/composer-root-update-plugin:3.1.0
composer require-commerce mage-os/product-community-edition:3.1.0

If your install originated from Magento Open Source and the source edition/version can’t be detected from composer.lock, add --base-project-edition "Open Source" --base-project-version <your-version> to the require-commerce command.

Upgrading from an older Mage-OS version

composer require mage-os/product-community-edition=^3.1 --no-update
composer update
bin/magento setup:upgrade

Migrating from Adobe Commerce or Magento Open Source

See our migration guide for detailed instructions on switching to Mage-OS.

We hope you enjoy Mage-OS 3.1.0. As always, please report any issues on GitHub and join the conversation on Discord.