TL;DR:
Don’t update to Gantry 5.5.x until you have updated your RocketTheme (RT) theme to a compatible version first.
If you already updated to G5.5 and are stuck with it, G5.5.x has many significant bug fixes, so you should update to the latest version.
Today sees the release of the long-awaited Gantry 5.5.x.
This major update brings significant improvements, including:
Before you update, please read the following important notes:
Study the changelog for Gantry 5.5.0 through to the current version of 5.5.x — there are big changes you should be aware of:
https://gantry.org/downloads
Upgrade on a test environment first to make sure everything works as you expect.
Backup, backup, backup!
Before you do anything, make sure you can restore if something goes wrong. The update to Gantry 5.5.x is a one-way process — you cannot downgrade back to Gantry 5.x without using your restore.
Menu system migration:
Gantry 5.5.x introduces significant redevelopment of the menu system. Immediately after updating, go to the Gantry 5 menu editor and save each of your menus. This migrates your existing menus from the old YAML method (flat files) to the CMS database.
Clear browser and server cache after updating.
Template support:
Alongside Gantry 5.5.x, compatible versions of the Helium and Hydrogen themes have been released. Other RT themes will also need updates (many have already been released — 27 of 45 for Joomla, WordPress, and GRAV). If you use an RT theme, wait for its update.
There are manual methods to update an RT theme to work with Joomla 4, but it’s better to wait for the official RT theme update (see the changelog; it involves copying folders from Helium and checking/reapplying theme overrides).
Joomla 4 & Gantry 5.5:
Gantry 5.5.x now supports Joomla 4, but Joomla 4 introduces Bootstrap 5, which can change your site’s look (RT is working to minimize this). Joomla 4 also changes some of the HTML structure, which may require changes to your custom.scss selectors.
Note: Old RT extensions do not work with Joomla 4 (and won’t be made to do so). Consider this before migrating to Joomla 4 (which requires Gantry 5.5.x).
Internal code updates:
There are significant updates to third-party code Gantry 5 uses (such as the SCSS compiler). This may require changes to your custom code (like custom.scss), as the new SCSS compiler is stricter. RT themes are also affected, so they need updates too.
Cosmetic/layout changes:
Some things may look different after migrating, which may require you to write or amend your custom.scss.
Further reading:
Document created from an Evernote web clip of the original RocketTheme forum post by Mark (aka MrT).