Advance RFC #1003 "Deprecate import Ember from 'ember';"` to Stage Ready for Release

[emberjs-rfcs-bot]

Advance #1003 to the Ready For Release Stage

Rendered

Summary

This pull request is advancing the RFC to the Ready For Release Stage.

• PR to Accepted Stage: Deprecate import Ember from 'ember' #1003

An FCP is required before merging this PR to advance.

Upon merging this PR, automation will open a draft PR for this RFC to move to the Released Stage.

Ready for Release Stage Description

This stage is complete when the implementation is complete according to plan outlined in the RFC, and is in harmony with any changes in Ember that have occurred since the RFC was first written. This includes any necessary learning materials. At this stage, features or deprecations may be available for use behind a feature flag, or with an optional package, etc.

For codebase changes, there are no open questions that are anticipated to require breaking changes; the Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature.

This stage should include a list of criteria for determining when the proposal can be considered Recommended after being Released.

An FCP is required to move into this stage.

Each Ember core team will be requested as a reviewer on the PR to move into this stage. A representative of each team adds a review. If a team does not respond to the request, and after the conclusion of the FCP, it is assumed that the release may proceed.

Checklist to move to Ready for Release

• Implementation is complete according to plan outlined in the RFC, with any adjustments noted in the RFC
• Any necessary learning materials have been updated
• The Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature. This is the go/no go decision for any feature flags, but the flags should only be turned on when moving to Released.
• The feature may not yet have support by the entire ecosystem (e.g. IDEs, addons, Ember Inspector, Engines, Lint Rules, Blueprints, etc), but it does not unintentionally break any existing functionality in those areas.
• The Interactive Tutorial is not broken by this feature.
• Criteria for moving to the Recommended Stage has been filled out
• This PR has been converted from a draft to a regular PR and the Final Comment Period label has been added to start the FCP
• Each team has been added as a reviewer to the PR at the start of the FCP. Reviews are not required by the end of the FCP. This is a notification step.
  • Framework @emberjs/framework
  • Data @emberjs/ember-data-core
  • CLI @emberjs/cli
  • Learning @emberjs/learning-core
  • Typescript @emberjs/typescript-core
  • Steering @emberjs/steering

Criteria for moving to Recommended (required)

A set of criteria for moving this RFC to the Recommended Stage, following release:

1. Update ember-data and other blueprint-packages to avoid import Ember from "ember"

Track Implementation

• Deprecate import Ember from 'ember' ember.js#20686
• Remove import Ember from 'ember'; ember-learn/guides-source#2028
• Deprecation guides Deprecation guides for deprecating importing from `'ember'' ember-learn/deprecation-app#1381
  • Enable grouping in deprecation guides so we don't scare people @kategengler Add parent relationship to deprecations to allow grouping in the UI, especially in the index ember-learn/deprecation-app#1383
  • Update #1381 above to use the deprecation grouping
• Enable deprecation on ember-source
• Enable ember.js "node-tests" to work without the Ember barrel file

[kategengler]

Backed this out of FCP -- the deprecation guides haven't been accepted and there a few blockers to being able to enable the deprecation.

[NullVoxPopuli]

Status Update:
Goal: get default blueprint non-violating with this set of deprecations.

Done, probably (pending any required changes from Outstanding):

• Deprecation guides for deprecating importing from `'ember'' ember-learn/deprecation-app#1381
  • has details on how to migrate all of the below as well

Outstanding

• Ember Inspector:

  • release
  • For ember-source 5.10-beta+, do not use the Ember barrel file (it's been deprecated) ember-inspector#2572
  • Move more utilities into Glimmer
    • add tracked utilities for ember-inspector glimmerjs/glimmer-vm#1489
    • support modifier delegate manager in debug render tree glimmerjs/glimmer-vm#1589
  • Update ember to provide a debug-utilities-focused export of private utils for the inspector to use
    • provide debug utilities for inspector via event communication ember.js#20580

• ember-cli-app-version

  • release - https://github.com/ember-cli/ember-cli-app-version/releases/tag/v7.0.0
  • Uses EmberBarrelDefaultExport.libraries - https://github.com/ember-cli/ember-cli-app-version/blob/master/addon/initializer-factory.js#L3
    • Do not use Ember Barrel file import ember-cli/ember-cli-app-version#416
  • Needs general CI maintenance for confidence in changes
    • Expand ember-try matrix ember-cli/ember-cli-app-version#414
  • Maybe we add a @ember/user-meta to support this:

    import { libraries } from '@ember/user-meta';
    
    libraries.register('name of thing', 'version or whatever');

    (instead of getting rid of the thing entirely)
    UPDATE: this isn't explicitly needed as libraries can be imported from @ember/-internals/metal

• ember-resolver

  • release - changes available in v12 - https://github.com/ember-cli/ember-resolver/releases/tag/v12.0.0
  • Needs to remove TEMPLATES - https://github.com/ember-cli/ember-resolver/blob/main/addon/addon/index.js#L298
    • use resolver-local cache instead of this one from ember.
      • Do not use global ember -- drop support for ember-source < 4.12 ember-cli/ember-resolver#973
  • Needs to remove Ember.ENV - https://github.com/ember-cli/ember-resolver/blob/main/addon/addon/index.js#L462
    • use resolveRegistration to lookup the app's config
  • But also, some general CI maintenance for confidence in changes
    • Expand try matrix ember-cli/ember-resolver#972

• @glimmer/component

  • Moving into ember-source, PR Bring @glimmer/component into ember repo ember.js#20751. This fixes the deprecation too.

• @ember/test-helpers

[davidtaylorhq]

Is there a plan for Ember.EventDispatcher? I don't see it listed in the RFC, or the deprecation-guides PR 👀

(context: we access it to disable its functionality, so that we can use our own our own browser-native events implementation for classic components, and therefore have better support for mixing glimmer/classic components)

[ef4]

EventDispatcher would still be accessible at:

import { EventDispatcher } from '@ember/-internals/views';

It would be really good if you could upstream that more-compatible event dispatching. It could be behind an optional feature so it's non-breaking. Instead of paying for the whole old event dispatching system that you don't want to use anyway, the optional feature could make sure it's dropped from the build.

I don't think it would be a controversial RFC, especially since you've already done the work to thoroughly test how compatible it is.

[ef4]

Now is a good time to re-check whether we can get the stock blueprint running cleanly with no deprecation firing. We think everything is done but upgrades (like @glimmer/component) in the blueprint may need to land.

The inspector issue can still get tracked as a blocker for Recommended, not Released.

[ef4]

It would be good to implement the optional deprecation activation in #896 as a way to test this deprecation.

[NullVoxPopuli]

enabling PR: emberjs/ember.js#20813

text:

What are folks thoughts on enabling this? and then the deprecation messages would force us to work on improving the inspector experience?

I have some ideas for how to bring back compatibility.

Our setup would be something like this:

const EMBER_INSPECTOR_SUPPORT = Symbol.for('__EMBER_INSPECTOR__');
globalThis[EMBER_INSPECTOR_SUPPORT] ||= {};
globalThis[EMBER_INSPECTOR_SUPPORT].init = async function loadEmberInspectorUtilities() {
  // store things on the secret object 2 lines above
  globalThis[EMBER_INSPECTOR_SUPPORT].tracking = await import(...);
  /* ... etc ... */.container = await import(...);

  // ensuring to set up an event listener pair for communicating via postMessage with the inspector
}

This should probably wrap all of this code: https://github.com/emberjs/ember.js/pull/20775/files#diff-b2c569a1648b65b7314971b3bd201a82fda450a5cccc8c3d415b864166c98e27

And then on the app side, we only need to load the module, since everything the inspector needs is await-imported

import '@ember/inspector-support';

And then on the inspector side, we access the globalThis

// loading the inspector
await globalThis[EMBER_INSPECTOR_SUPPORT].init();

// we can now start building the UI / Panels in the ember-inspector project.

@PatrickJS , @ef4 thoughts?