Repository navigation
Fill three gaps in the 1.x to 2.0 upgrade guide, found by following it - #606
Conversation
Walked this guide end to end on a real Flarum 1.8.20 forum with five third-party extensions, upgrading it to 2.0.0-rc.8 on MariaDB. The documented path works. Three things it leaves out cost time, and the first one stops you before you start. Step 1 tells you to update your v1 install first, and on current Composer that command fails outright. Flarum 1.x requires league/flysystem 1.x, which has security advisories and no patched 1.x release, so Composer refuses to load any version of it and reports that no flarum/core version is installable. Ignoring the advisory is the recommended approach for 1.8, so the guide now shows the composer.json entry that does it, and says it can be dropped after upgrading because 2.0 is on Flysystem 3.x. Step 3 lists superseded extensions but misses flarum/package-manager, which was renamed to flarum/extension-manager for v2. The old name still resolves, so this blocks nothing, but Composer warns that it is abandoned on every single run during the upgrade and the guide offers no explanation. Step 8 recommends disabling third-party extensions before upgrading and never says to turn them back on. Anyone following the page literally finishes with a working forum and their extensions off.
Step 6 asks you to change the database driver if you are on MariaDB, without saying how to find out which you are running. The obvious place to look gives the wrong answer: on Flarum 1.x, `php flarum info` prints the line as "MySQL version" whichever server is behind it, so a MariaDB forum reads as MySQL and the step gets skipped. Noticed while upgrading a real 1.8.20 forum, where the line read "MySQL version: 11.8.9-MariaDB-ubu2404". 2.0 reports it as "MariaDB version" correctly, so the confusion only exists during the window where the decision is actually made.
|
Added a fourth item, from a question about whether this guide should cover upgrade paths for different databases. It should not, and the reason is worth stating: Flarum 1.x only ran on MySQL and MariaDB. What step 6 was missing is how to tell which one you have, and the obvious check gives the wrong answer. On 1.x, That forum is on MariaDB and does need the driver change, but anyone reading the label rather than the version string will conclude step 6 does not apply and carry a wrong Pushed as a separate commit rather than amending, so the original three findings stay reviewable on their own. Still builds clean with zero broken anchors, and still merges cleanly with each of the other open docs PRs. |
| MySQL version: 11.8.9-MariaDB-ubu2404 | ||
| ``` | ||
|
|
||
| That forum is on MariaDB and does need this change, despite what the label says. After upgrading, 2.0 reports it as `MariaDB version` correctly. |
There was a problem hiding this comment.
If a 1.x forum is running MariaDB, for the 2.x upgrade, the driver entry in config.php needs to change to mariadb, else there will be compatibility errors going forward
There was a problem hiding this comment.
Agreed. The step now says the change is required and that leaving driver as mysql causes compatibility errors on 2.x, instead of the softer "update the value". Pushed in bf8caa7.
Per review: a 1.x forum on MariaDB must switch the config.php driver to mariadb, or it hits compatibility errors on 2.x.
2 participants
I walked this guide end to end on a real Flarum 1.8.20 forum and upgraded it to 2.0.0-rc.8 on MariaDB 11.8, with five third-party extensions installed, deliberately chosen so the guide's own cases were exercised: one with no v2 release at all, two with v2 releases, and
flarum/package-manager.The documented path works. Core went to 2.0.0-rc.8, migrations ran, and the forum served
/,/apiand/allafterwards. Three things the guide leaves out cost time, and the first one stops you before you start.1. Step 1's command fails on current Composer
Flarum 1.x requires
league/flysystem1.x, which has security advisories and no patched 1.x release. Composer blocks advisory-affected packages by default, so "update your v1 install first" dies with noflarum/coreversion being installable:I hit this on a clean 1.8 install before I could even build the test forum, and it has come up on the forums already. Ignoring the advisory is the recommended approach for 1.8, so the guide now carries the
composer.jsonentry that does it.Verified on Composer 2.10.3: the single
GHSA-cxf4-7mrp-vvprignore clears both reported PKSA advisories. I also checked that 2.0 genuinely does not need the entry afterwards: core 2.0 requiresleague/flysystem ^3.15and the upgraded tree resolved 3.36.0, so the note saying it can be dropped is accurate.2. Step 3 misses
flarum/package-managerIt was renamed to
flarum/extension-managerfor v2. The old name still resolves to a 2.0 release, so this blocks nothing, but Composer printsPackage flarum/package-manager is abandoned, you should avoid using iton every run throughout the upgrade, and afterwardsphp flarum infocarriesReplaced by flarum/extension-managerin its Notes column. The guide's superseded list is the natural place to say so.3. Step 8 opens a loop it never closes
It recommends disabling third-party extensions before upgrading, and nothing afterwards says to re-enable them. Following the page literally leaves you with a working forum and your extensions switched off.
One thing I checked and did not change
I expected
minimum-stability: betawith noprefer-stablein the 1.x skeleton to pull pre-release versions of unrelated packages. It did not: zero non-Flarum packages resolved to a pre-release version. No warning added, since there is nothing to warn about.I also want to be clear about something I got wrong mid-testing, in case it saves anyone repeating it: I initially thought the upgrade pruned the enabled-extensions list. A second clean run, identical except for skipping step 8, showed the list intact apart from the two extensions step 3 tells you to remove. The earlier result was caused by my own step 8, not by the upgrade. Nothing in this PR rests on it.
Builds clean with
docusaurus build --locale en, zero broken anchors in the 2.x English tree. Merges cleanly with each of my other open docs PRs, including #605 and #595, which also touchupdate.md.