Preparing for Discourse's upgrade to Ember 5

Discourse will soon be upgrading our version of the Ember Javascript framework from version 3 to version 5. The vast majority of the preparation work is done, and many sites are already running on Ember 5 (including Meta!). :ember:

This upgrade is available behind a feature flag right now! This is the default for self-hosted Discourse installations starting 10th January. Initially, Ember 3 support will remain available via a flag, but will be removed within the first quarter of 2024.

On our managed discourse.org hosting, we’ll be doing a staged rollout of the flag over the next couple of months:

:discourse: discourse.org hosting tier Upgrade Date
Basic 2023-12-07 :white_check_mark:
Free 2023-12-12 :white_check_mark:
Standard 2024-01-15 :white_check_mark:
Business 2024-01-22 :white_check_mark:
Enterprise (case-by-case basis)

:eyes: What does this mean for me and my site?

If you’re running Discourse with no extra themes, plugins, or theme components… you’re all set! No need to lift a finger, or worry about this at all.

Equally, if you only use official themes/plugins, we’ve got you covered! We will ensure that all our official themes, theme components, and plugins are primed and ready for the upgrade.

For those who are using third-party customisations, their developers should be making the necessary changes to those so you can continue to use them seamlessly throughout this transition.

However, if you have any custom themes, theme components, or plugins that you have created or commissioned for your sites, then this post is for you! We’ll run through how to identify and resolve any issues in advance of the upgrade.

:face_with_monocle: Identifying issues

All ember-5-related upgrade issues can identified in advance of the upgrade by checking for uses of deprecated APIs. In recent versions of Discourse (starting Discourse 3.2.0.beta4-dev), these critical deprecations will trigger a warning banner for admins:

You can find more information about triggered deprecations in the browser developer console. It’s generally good practice to resolve all deprecations you see. But for this Ember version upgrade, the key ones to resolve are:

  • discourse.modal-controllers (see this topic for more info)

  • all Ember deprecations (i.e. those with non-discourse. IDs)

When printing deprecations to the console, Discourse attempts to identify the relevant theme/plugin.

For developers and hosting providers, we have made a couple of tools available for identifying deprecations in bulk:

  • When running QUnit tests, a report is printed at the end with a list of all unresolved deprecations. In GitHub actions, a markdown version of this is added to the workflow summary page

  • For hosting providers, we have the discourse-deprecation-collector plugin which increments prometheus counters whenever deprecations are hit in production

:technologist: Resolving deprecations

Generally, the console message will include a description of the problem and the steps required to resolve it. In some cases, they’ll link out to external resources like the Ember deprecations website or Discourse Meta.

If anything is unclear, please feel free to post below or in a dedicated dev topic and we’ll do our best to help.

:rocket: Testing on Ember 5

To test things on Ember 5 in a local development environment, you can start our ember-cli helper with the EMBER_VERSION environment variable. For example:

EMBER_VERSION=5 bin/ember-cli -u

To confirm things are working as expected, check the Ember version which Discourse prints to the browser console.

In production, you can achieve the same thing by adding EMBER_VERSION: 5 to the env: section of your app.yml file.

42 Likes

Congratulations team, that must’ve been a LOT of work! :sweat_smile:

11 Likes

David, I presume this is fully reversible with a reversion of this attribute and a rebuild?

5 Likes

Yup, totally reversible :+1:

3 Likes

Nice work guys. How do I find a list of officially supported themes/components. I was able to find that 3 or 4 of my plug-in components are official. (The tag “official” is listed in the topic)

But for the 4th I could only find this URL: GitHub - discourse/discourse-full-width-component: Make Discourse occupy the full browser width

How can I tell if it’s official / won’t break upgrade?

Edit: looks like I can filter here: Topics tagged official

Then search for specific theme in the list. I previously tried searching the forums top right.

When I search the topics list it’s not listed but I do see staff as GitHub contributors:

4 Likes

As a very rough guide, if the URL starts with github.com/discourse/, then we’ll take care of it. In the case of the the discourse-full-width-component, I don’t see any cause for concern - it should work fine under Ember 5.

6 Likes

Is there a way to know if a Discourse hosted site one is an admin on is running Ember 5?

I took a peek on the admin page and did not see any indication of such. The site I am admin on is

https://swi-prolog.discourse.group/

5 Likes

As of right now, Ember 5 is running on Meta and on our ‘basic’ tier of hosting.

On recent versions of Discourse, we print the current version information to the console. So you can open the dev-tools console and check the first line:

10 Likes

You have dev-tools access on every site on the internet! In windows-linux on Chrome, you can hit the F12 key. For mac, it’s on . . . some menu.

8 Likes

Thanks.

I was thinking it meant the Discourse console that one has access to if they install the site at the operating system command prompt.


Steps

  1. Open Internet browser (Chrome for this example)
  2. Navigate to Discourse site (https://swi-prolog.discourse.group/ for this example)
  3. Press F12
  4. If Console tab at top is not active then select Console tab.
  5. First line should note Ember version.

4 Likes

And if someone is trying to do things on iPad then console can be found (Safari only) via an app:

https://apps.apple.com/app/id1064318327

oh, it s not available anymore. Bummer.

5 Likes

Love this addition. Great work on this David and ModernJS Team. :rocket:

heh. you can run Chrome on MacOS and dev tools are the same. It’s iOS and touchscreens that make it difficult/near-impossible to use (ie: iPad in desktop mode has a web inspector thing but it isn’t ideal).

5 Likes

By pressing F12? I thought I knew that didn’t work.

5 Likes

optioncommandJ

5 Likes

Don’t know how that’s any harder to remember than F12. Both are pretty much undiscoverable though. And perhaps looking on a menu as I suggested wouldn’t help.

6 Likes

option command J should be easy for you to remember :laughing:

5 Likes

My go-to is always [right click] [inspect element] - I think that’s consistent for every browser/os

6 Likes

Right!

Oh. That’s easy and always works. Nice. And it saves me like a dozen clicks since that’s so often what you want to do. Of course, it would appear that I’ve hijacked this announcements . Sorry.

7 Likes

I know this one is going to cost me some development time :grimacing: (new sidebar, removal of category badges… it’s quite often - having a custom theme is costly!).

Is there a way to Ember 5 on my forum without breaking everything in production? I’m on the hosted Business Plan.

  • Thanks for the heads up and the deprecations messages anyway. But when fixing the deprecation I have to code my theme for both Ember 3 and Ember 5?
  • Do we have a choice to upgrade or not? Or you are the only one to decide?

Some kind of “preprod” or “testing” environment would be nice I guess.

6 Likes

Hi Damien :wave:.

Discourse and Ember only deprecate things once there is an alternative available for immediate use. So if there are any changes you need to make, those can be made straight away and will work under Ember 3.

This is the approach we’re taking in Discourse core and in all our official themes and plugins. We’re not creating separate code for Ember 3 / Ember 5.

I’m afraid it’s not optional. Keeping Discourse core’s dependencies up-to-date is essential for us in terms of security, performance and features. The features which Ember 5 provides are going to become essential for future improvements to Discourse itself.

That is a good question! We’re putting a lot of work at the moment into making this transition as smooth as possible, and are working on various tooling improvements.

One of those improvements landed a few hours ago, and should help you here.

If you visit /safe-mode on your forum, there is now a checkbox for “Make Javascript deprecations raise an error”.

That will allow you to safely see how your site works with all pending deprecations converted into errors.

Technically that is not quite the same as “Testing ember 5 on the forum”. But it’s a good way to simulate the upcoming breaking changes without needing a fully separate staging environment.

8 Likes