Compatibility gate messages

Every message the compatibility gate prints, with its cause and its fix. Versioning explains the gate. The wording of these messages is internal (tier "Internal" in Versioning): read them, don't parse them. The blocks below are copied from the code, so npm run docs:check fails when a message changes and this page doesn't.

When the gate runsCopy Anchor Link

The formatsCopy Anchor Link

Every message is built from the constants of Compatibility. %s and %d are filled in per module:

public const LINE = '%s needs Light API %s, this is %s (%s)';

public const LINE_SKIPPED = '; its registration guard left it unregistered';

public const LINE_UNDECLARED = '%s declares no Light API range (%s)';

public const FIX_OUT_OF_RANGE = 'Install a release made for Light API %s, or disable or remove the module.';

public const FIX_SKIPPED = 'Update or remove the package.';

public const FIX_UNDECLARED = 'Add extra.mrx-light-api to its composer.json.';

Out of range: LINE and FIX_OUT_OF_RANGECopy Anchor Link

Acme_Deposit needs Light API ^1.1, this is 1.0.0 (app/code/Acme/Deposit/composer.json). Install a release made for Light API 1.0, or disable or remove the module.

• Cause. The module is registered and enabled, and its extra.mrx-light-api doesn't include VERSION. A malformed range and a branch name such as dev-main count as out of range too.
• What Light does. It hides the module's Light parts in every mode (Versioning).
• Fix. Install a release of the module made for this Light API, or disable or remove it. Then run bin/magento cache:clean config layout.

Skipped: LINE_SKIPPED and FIX_SKIPPEDCopy Anchor Link

acme/module-report-light needs Light API ^2.0, this is 1.0.0 (vendor/acme/module-report-light/composer.json); its registration guard left it unregistered. Update or remove the package.

• Cause. The package declares a range, and the range guard in its registration.php left the module unregistered, so none of its code loaded.
• Fix. Update the package to a release for this Light API, or remove it. module:disable can't help: an unregistered module is unknown to Magento.

No range: LINE_UNDECLARED and FIX_UNDECLAREDCopy Anchor Link

Acme_Deposit declares no Light API range (app/code/Acme/Deposit). Add extra.mrx-light-api to its composer.json.

• Cause. The module contributes to Light, or uses Light classes, and has no extra.mrx-light-api.
• What Light does. During 0.x nothing: the doctor warns with api_undeclared. From the later 1.0.0 release the gate hides a module that contributes, and api_undeclared is an error.
• Fix. Add the range to the module's composer.json, or to a small composer.json in its own folder when it has no package.

No range guard: LINE_NO_GUARDCopy Anchor Link

Acme_Deposit uses Light PHP without a range guard (app/code/Acme/Deposit/registration.php). Add the guard with the range of extra.mrx-light-api.

public const LINE_NO_GUARD = '%s uses Light PHP without a range guard (%s). Add the guard with the range of '
    . 'extra.mrx-light-api.';

• Cause. The module's PHP or templates name a Light class, and its registration.php doesn't call satisfies(. On a Light major such a module fails to compile the whole shop, and the gate can't stop that.
• Fix. Add the range guard with the range of extra.mrx-light-api (Getting started shows one). The doctor reports it as the error api_constraint and adds: "Without it, a Light major would fail to compile the shop (spec 11.3)."

The banner: BANNER_HEAD, BANNER_CLEAN and BANNER_MODECopy Anchor Link

In developer mode every Light page shows a red banner above its title while a module is hidden or skipped:

Light API 1.0.0 hides 2 modules until you fix them:
- Acme_Deposit needs Light API ^1.1, this is 1.0.0 (app/code/Acme/Deposit/composer.json). Install a release made for Light API 1.0, or disable or remove the module.
- acme/module-report-light needs Light API ^2.0, this is 1.0.0 (vendor/acme/module-report-light/composer.json); its registration guard left it unregistered. Update or remove the package.
Then run bin/magento cache:clean config layout. bin/magento mrx:light:doctor shows the details.
You see this because Magento runs in developer mode. Production and default mode hide these modules and only log them.

public const BANNER_HEAD = 'Light API %s hides %d %s until you fix them:';

public const BANNER_CLEAN = 'Then run bin/magento cache:clean config layout. bin/magento mrx:light:doctor shows the '
    . 'details.';

The banner is the kit banner, so a browser test finds it by its attribute:

$html = '<div class="mrx-banner mrx-banner--critical" role="alert" data-mrx-compat-banner>'

• It shows only in developer mode, and only on pages the Light shell draws: never on stock pages in advanced mode or on the sign-in page.
• Fix. Fix each listed module, then run bin/magento cache:clean config layout. cache:clean config alone leaves the cached layout with the hidden blocks.

The log line: LOGCopy Anchor Link

public const LOG = 'Light hides a module: %s. Run bin/magento mrx:light:doctor.';

• In every mode, var/log/system.log gets one warning per hidden or skipped module when the map is built, so once per cache lifetime. Production and default mode show nothing else: no admin notice and no email.
• Fix. Run the doctor, fix the module, and clean the config and layout caches.

setup:upgradeCopy Anchor Link

setup:upgrade prints the same lines as the banner, one per module that is not ok or core, and one LINE_NO_GUARD line per module without a needed range guard. When every module fits:

$lines[] = sprintf('Light API %s: every module that extends Light is in range.', $map['api']);

When the check itself fails, it prints Light could not check module ranges: <error> and the upgrade goes on. The gate never stops an upgrade.

Doctor rulesCopy Anchor Link

The doctor builds the map fresh, and exits 1 on any error.

api_constraint (error)Copy Anchor Link

Each out_of_range or skipped module, with the LINE and fix above. A hidden module's changes to other modules' items stay in effect, and the error lists them, one per line:

$kept = $entry['kept'] === [] ? '' : "\nThese changes to other modules' items stay in effect:\n- "

It also reports a registered module whose range guard holds another range than its extra:

'%s guards its registration on "%s" in %s/registration.php, but %s declares "%s". Use the same '
. 'range in both.',

a require on mrx/module-light whose range differs from extra:

'%s requires mrx/module-light "%s" in %s, but declares "%s" in extra.mrx-light-api. Use the same '
. 'range in both.',

and a module without a needed range guard (LINE_NO_GUARD). Fix: make the three ranges one range.

api_undeclared (warning during 0.x, error from 1.0.0)Copy Anchor Link

The LINE_UNDECLARED line with FIX_UNDECLARED. During 0.x it adds "From Light API 1.0.0 the gate hides it." for a module that contributes, or "From Light API 1.0.0 this is an error." for one that only uses Light.

api_range_form (warning)Copy Anchor Link

'%s declares the Light API range "%s" in %s. Use ^X.Y parts joined by ||, such as ^%s: a wider '
. 'range matches Light majors it was never tested on, a narrower one is hidden by the next minor.',

Fix. Declare ^<major>.<minor>, or several joined by ||.

mixed_layout (warning)Copy Anchor Link

'%s references a Light container in %s, a layout file off the Light handles. The gate drops '
. 'whole files, so its other changes would go too while the module is hidden. Move the Light '
. 'references into a light_* or mrx_* file.',

Fix. Move the Light references into a layout file on a light_* or mrx_* handle.