Why GNOME Extensions Break After Every Shell Update

Here is the edited version:

You update GNOME, reboot, and half your desktop customizations vanish. The dock disappears, the top bar reverts to stock, and the GNOME Extensions app shows a wall of grayed-out toggles with a vague "incompatible" warning. This isn't a bug you triggered by accident. It's the predictable result of how GNOME Shell extensions are built, and it happens after nearly every release cycle.

The reason comes down to one uncomfortable fact: GNOME extensions aren't sandboxed plugins running against a stable public API. They're JavaScript code injected directly into the GNOME Shell process itself, calling internal functions and touching UI objects that GNOME's own developers can rewrite at will. When the Shell's internals change, even slightly, extensions that reach into those internals can fail instantly, sometimes with no warning beyond a disabled toggle. See cifs/smb3 kernel maintainer steve french steps down: the details for additional background.

Context

Every GNOME extension ships with a metadata.json file, and inside it sits a shell-version array listing exactly which Shell releases the extension has been tested against. GNOME Shell checks that array on load. If your installed Shell version isn't listed, GNOME Shell disables the extension automatically, regardless of whether the code would actually still work. See related: eevdf vs cfs: what really changed in linux scheduling for additional background.

Also read: context: is kde plasma 6.8 worth upgrading for performance?

This is intentional, not sloppy. GNOME's upstream developers have said for years that they won't freeze the Shell's internal JavaScript objects and functions just to keep third-party extensions stable. Doing so would lock the desktop's evolution to whatever hooks extension authors happened to rely on.

So instead, each new Shell release can rename functions, restructure panel widgets, or change how the overview and quick settings menus are built. Maintainers then have to update any extension that touches those pieces to match.

That puts the burden on extension maintainers, and turnaround varies wildly. Maintainers of popular extensions like Dash to Dock or User Themes tend to release compatibility patches within days of a new version, often before most users even upgrade. Smaller or abandoned extensions can lag for months, or never receive an update at all — which is why it's worth checking an extension's page on extensions.gnome.org before upgrading. The site lists which Shell versions each extension supports.

Note: I trimmed the final sentence ("and a quick look at the") since it cut off mid-thought and completing it would have required adding information not present in your draft. Let me know what that sentence was meant to say and I can fold it back in properly.