Is it "safe" to upgrade to Ghost 6.0?

It's always a good question: There's a new major version – is my stuff going to continue to "just work"? And maybe the "upgrade" button is a little scary. Here's my take.

Breaking changes?

It's technical, but you can find the breaking changes for Ghost 6.0 here: https://docs.ghost.org/changes#ghost-6-0

So how do I know if any of that is going to cause me problems?

Self-hoster version:

If you're self hosting, you need to pay attention to Node versions. You should already have been on MySQL 8. If you aren't, you should strongly consider it. There are enough show-stopper bugs in SQLite that you don't want to be there.

A big question for self-hosters is whether you're going to upgrade via cli. I did that this morning, and it worked great (ghost upgrade and then it'll prompt you to get version 6). Except that ActivityPub didn't work immediately, apparently a self-hoster only bug that'll likely be fixed this week. If you're currently running a ghost-cli managed install, this is probably the easiest way to get to 6.0, and likely Ghost-hosted ActivityPub either today or in short order. (There's an issue with redirects for self-hosters with admin panels on separate domains that tripped me up, but a fix is coming.) Using Ghost-CLI won't get you analytics, however.

The other option is the new Docker setup. The dev team is moving/has moved to that, and it'll be required at 7.0. And I'd guess that functionally, support for the Ghost-CLI version is likely to start 'rotting' sooner than that, since as fewer devs use it, fewer bugs will get patched. So you'll eventually want to switch, and when you do, then you can have ActivityPub (Ghost-hosted or self-hosted) and also analytics (with your own API key). There's a migration script. Poor spectralwebservices.com has been the guinea pig for this, revealing all the many and various ways in which assumptions and reality don't always coincide. It's non-destructive, so no harm in trying it, and it's been much improved compared to the first time I tried it. If the migration to Docker fails, you just run the recovery-instructions script included – if it generates (it didn't for me in one version) – or else you restart Ghost and NginX. Not too bad. I'm headed for this sooner or later, but it was still failing for me this morning.

And what else? Well, everything below:

Managed host version:

If you're on Ghost Pro, there's a button to click to trigger the upgrade, and you'll be offline for a couple minutes while it runs. If you're on Magic Pages, you're already upgraded. (If you see analytics and network tabs in your dashboard, you're on 6.0.)

So... should you click the button?

There are two possible breaking changes for managed-hosters:

1) AMP support is going away. And you may not even know what that is, so don't worry about it. Moving on. 🤣

2) 🛒There's now a 100-item limit on requests. So if you have a theme that attempts to get all the posts or all the tags or all the authors, it'll now only get the most recent 100. But... most themes never do this. They tend to load posts with lazy-loading, meaning they make a bunch of requests for a dozen or so posts at a time. Still, if you have a "tags" page that shows all your tags, and you have >100 tags, you might only see 100 of them there. (Or maybe you have >100 authors? I am working on a site this week that does, so ok, maybe!) Your site isn't going to break if you upgrade in this case, but you might need your theme tweaked to restore the previous behavior.

My guess is that the vast majority of themes will see no impacts, or will only have impacts on their tags list page and author list page, and of course that's only if they have these lists and only if they have >100 items. But if that's you, feel free to book a theme tune-up. (Retainer clients: drop a task in Asana.)

Quick self-serve: Check your theme with gscan

You can check if your theme might be impacted by downloading it (/ghost > settings ⚙️> theme > installed > (three buttons) > download and then uploading it at https://gscan.ghost.org . Be sure to select Ghost 6.x from the dropdown.

If you haven't had a recent theme update, you may see messages about missing custom fonts support. You can ignore this. Nice to have if you like to change your fonts, but not going to break anything.

If you see a message about limit=all being deprecated, that's item #2 above.

Integrations? Might be impacted.

If you're using an integration that retrieves a lot of content from Ghost, you may want to pause before upgrading. The change to only returning 100 items at a time means that an integration that asks for 'all' of a content item is only gong to get the first 100. That's going to break integrations that weren't already using pagination.

The FAQ for integrations I've deployed recently:

• Social sign-on: Not impacted. It asks for ONE member, never all of them.
• Password sign-on: Not impacted, ditto.
• Search integrations: Ongoing sync is not impacted. The script I run to load content initially needs an upgrade, but that's my problem, not yours. Ghost's built-in search got an update a few weeks ago and has its own special endpoint now.
• Institutional access: Not impacted. (The potential impacts were back when the 2FA requirements were released. Those are already fixed.)
• PhantomAdmin: Possibly impacted. It does make a couple of 'all' requests (for tags) that'll need to be updated to get the full content. It's due for an update anyway.

If you need your theme updated, either because you're noticing breakage or because you'd like to be very sure everything is perfect before you upgrade, feel free to book a couple hours here. Retainer clients can drop me a task in Asana. 🙂