Tell people to run the 1.x to 2.0 upgrade with Composer, not the extension manager - #605

update.md currently tells people they can run the 1.x to 2.0 upgrade from the extension manager's interface instead of the command line. It cannot do that upgrade, and the failure is structural rather than intermittent, so anyone who follows that sentence hits a refusal with no explanation on the one upgrade where a half-applied change costs the most.

Why it cannot work

Two separate problems, one hiding the other.

CheckForUpdatesHandler skips any package that is not a registered extension:

// Skip if not an extension
if (! $this->extensions->getExtension(Extension::nameToId($mainPackageUpdate['name']))) {
    continue;
}

Extension::nameToId('flarum/core') is flarum-core, and flarum/core has no flarum-extension package type, so getExtension() returns null and core is dropped on every run. updates.installed never holds a flarum/core entry, getNewMajorVersion() returns null, and the major-update flow refuses with no_new_major_version. The method's own docblock says the first composer call exists so major updates are visible and "That includes flarum/core itself", so the filter defeats its stated intent.

Behind that, ComposerJson::require('*', '*'), which is meant to relax every extension constraint before a major update, tests the wrong variable: in the wildcard branch the name being checked is the literal *, which never resolves to an extension, so every iteration continues and nothing is relaxed. Fixing only the first problem would therefore run the update with core pinned to the new major and every extension still constrained to the old one, which cannot resolve.

I verified this on a real 1.8.19 forum prepared exactly per this guide, and measured zero packages recorded by the update check. Both problems are present on the current 2.x branch of the framework.

What this changes

• update.md: the :::info block becomes a :::danger saying to use Composer, with the reason in one sentence. It keeps the extension manager recommended for routine updates inside a major version, which is what it does well, so this is a narrowing rather than a blanket warning off the tool.
• update.md: adds the symptom to Troubleshooting, because people search for the message rather than re-reading the introduction.
• extensions.md: the Extension Manager section says it updates "both extensions and Flarum itself" with no qualification. Now scoped to within a major version, pointing at the upgrade guide.

Notes

I have deliberately not referenced any fix PR here, since the docs should describe what today's release does. If the underlying behaviour is fixed and released, this wording should be revisited rather than left in place.

Builds clean with docusaurus build --locale en, zero broken anchors in the 2.x English tree. :::danger with a title matches existing use in console.md, troubleshoot.md, bugs.md and install.md. Merges cleanly with each of my other open docs PRs, including #595, which also touches update.md.