From 5c3a6ccb2cf18b770353e9af209503df4a86942d Mon Sep 17 00:00:00 2001 From: wagenet Date: Wed, 23 Nov 2022 21:15:21 +0000 Subject: [PATCH 01/66] Advance RFC to Stage ready-for-release --- text/0779-first-class-component-templates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0779-first-class-component-templates.md b/text/0779-first-class-component-templates.md index d86a727e04..474b9b9965 100644 --- a/text/0779-first-class-component-templates.md +++ b/text/0779-first-class-component-templates.md @@ -1,5 +1,5 @@ --- -stage: accepted +stage: ready-for-release start-date: 2021-12-03T00:00:00.000Z release-date: release-versions: @@ -8,7 +8,7 @@ teams: - learning - cli prs: - accepted: https://github.com/emberjs/rfcs/pull/779 + accepted: 'https://github.com/emberjs/rfcs/pull/779' project-link: --- From f34476fff9186e6f94af258d685d9bfb896f0bbd Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Wed, 23 Nov 2022 21:15:25 +0000 Subject: [PATCH 02/66] Update RFC 0779 ready-for-release PR URL --- text/0779-first-class-component-templates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0779-first-class-component-templates.md b/text/0779-first-class-component-templates.md index 474b9b9965..e2ba1bd2d5 100644 --- a/text/0779-first-class-component-templates.md +++ b/text/0779-first-class-component-templates.md @@ -9,6 +9,7 @@ teams: - cli prs: accepted: 'https://github.com/emberjs/rfcs/pull/779' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/871' project-link: --- From 44d249c790c04c2905809b7cf63b69e9e298d51e Mon Sep 17 00:00:00 2001 From: chriskrycho Date: Thu, 1 Dec 2022 15:03:24 +0000 Subject: [PATCH 03/66] Advance RFC to Stage ready-for-release --- text/0830-evolving-embers-major-version-process.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/text/0830-evolving-embers-major-version-process.md b/text/0830-evolving-embers-major-version-process.md index be7cc0d2ad..b5790b534d 100644 --- a/text/0830-evolving-embers-major-version-process.md +++ b/text/0830-evolving-embers-major-version-process.md @@ -1,5 +1,5 @@ --- -stage: accepted +stage: ready-for-release start-date: 2022-07-12T00:00:00.000Z release-date: release-versions: @@ -8,8 +8,7 @@ teams: - framework - learning prs: - accepted: https://github.com/emberjs/rfcs/pull/830 - + accepted: 'https://github.com/emberjs/rfcs/pull/830' --- # Evolving Ember's Major Version Process From e861b3db6fdbf852658ddef7efd38e7fb44b0abe Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Thu, 1 Dec 2022 15:03:28 +0000 Subject: [PATCH 04/66] Update RFC 0830 ready-for-release PR URL --- text/0830-evolving-embers-major-version-process.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0830-evolving-embers-major-version-process.md b/text/0830-evolving-embers-major-version-process.md index b5790b534d..658199caaa 100644 --- a/text/0830-evolving-embers-major-version-process.md +++ b/text/0830-evolving-embers-major-version-process.md @@ -9,6 +9,7 @@ teams: - learning prs: accepted: 'https://github.com/emberjs/rfcs/pull/830' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/878' --- # Evolving Ember's Major Version Process From 59bf40a41cc05698b0cb3098af7a2d4fe63f5a5f Mon Sep 17 00:00:00 2001 From: locks Date: Fri, 4 Aug 2023 15:09:31 +0000 Subject: [PATCH 05/66] Advance RFC {{ inputs.rfc-number }} to Stage recommended --- text/0812-tracked-built-ins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0812-tracked-built-ins.md b/text/0812-tracked-built-ins.md index 5213b8e707..fda4793c67 100644 --- a/text/0812-tracked-built-ins.md +++ b/text/0812-tracked-built-ins.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2022-03-29T00:00:00.000Z release-date: 2023-01-21T00:00:00.000Z release-versions: From 6a999a38b5d656b1b3b8d66641a0e0d2e902cadc Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 4 Aug 2023 15:09:34 +0000 Subject: [PATCH 06/66] Update RFC 0812 recommended PR URL --- text/0812-tracked-built-ins.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0812-tracked-built-ins.md b/text/0812-tracked-built-ins.md index fda4793c67..faeb3cac53 100644 --- a/text/0812-tracked-built-ins.md +++ b/text/0812-tracked-built-ins.md @@ -11,6 +11,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/812' ready-for-release: 'https://github.com/emberjs/rfcs/pull/886' released: 'https://github.com/emberjs/rfcs/pull/937' + recommended: 'https://github.com/emberjs/rfcs/pull/943' project-link: --- From 4f7b57fe59d3a9e23bc612a3128568b164b4f264 Mon Sep 17 00:00:00 2001 From: runspired Date: Sun, 24 Sep 2023 10:20:37 +0000 Subject: [PATCH 07/66] Advance RFC 0740 to Stage recommended --- text/0740-ember-data-deprecate-non-strict-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0740-ember-data-deprecate-non-strict-relationships.md b/text/0740-ember-data-deprecate-non-strict-relationships.md index ac664200cb..bce89a0bf4 100644 --- a/text/0740-ember-data-deprecate-non-strict-relationships.md +++ b/text/0740-ember-data-deprecate-non-strict-relationships.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2021-04-23T00:00:00.000Z release-date: 2023-09-19T00:00:00.000Z release-versions: From 541478fe3d1ba1d3a6d061926f0065630f5bf219 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Sun, 24 Sep 2023 10:20:42 +0000 Subject: [PATCH 08/66] Update RFC 0740 recommended PR URL --- text/0740-ember-data-deprecate-non-strict-relationships.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0740-ember-data-deprecate-non-strict-relationships.md b/text/0740-ember-data-deprecate-non-strict-relationships.md index bce89a0bf4..ed27252589 100644 --- a/text/0740-ember-data-deprecate-non-strict-relationships.md +++ b/text/0740-ember-data-deprecate-non-strict-relationships.md @@ -10,6 +10,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/740' ready-for-release: 'https://github.com/emberjs/rfcs/pull/910' released: 'https://github.com/emberjs/rfcs/pull/967' + recommended: 'https://github.com/emberjs/rfcs/pull/972' project-link: --- From 2be9e9d0d782165ccdb87e5c24f5fb0fa82b4571 Mon Sep 17 00:00:00 2001 From: runspired Date: Fri, 13 Oct 2023 18:09:03 +0000 Subject: [PATCH 09/66] Advance RFC 0743 to Stage recommended --- text/0743-ember-data-deprecate-legacy-imports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0743-ember-data-deprecate-legacy-imports.md b/text/0743-ember-data-deprecate-legacy-imports.md index 74ed18d392..c6389a2f9d 100644 --- a/text/0743-ember-data-deprecate-legacy-imports.md +++ b/text/0743-ember-data-deprecate-legacy-imports.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2021-04-23T00:00:00.000Z release-date: 2023-09-18T00:00:00.000Z release-versions: From 4b9e5360d31a8514a95e1b25de6bf5af9eb9cf42 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 13 Oct 2023 18:09:07 +0000 Subject: [PATCH 10/66] Update RFC 0743 recommended PR URL --- text/0743-ember-data-deprecate-legacy-imports.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0743-ember-data-deprecate-legacy-imports.md b/text/0743-ember-data-deprecate-legacy-imports.md index c6389a2f9d..4670898e96 100644 --- a/text/0743-ember-data-deprecate-legacy-imports.md +++ b/text/0743-ember-data-deprecate-legacy-imports.md @@ -10,6 +10,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/743' ready-for-release: 'https://github.com/emberjs/rfcs/pull/947' released: 'https://github.com/emberjs/rfcs/pull/969' + recommended: 'https://github.com/emberjs/rfcs/pull/979' --- # EmberData | Deprecate Legacy Imports From c0a338fb4155360c5fdb875ad18c641a74b40cb5 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 12:43:19 -0500 Subject: [PATCH 11/66] Make deprecation-workflow-built-in --- .../0000-move-deprecation-workflow-to-apps.md | 327 ++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 text/0000-move-deprecation-workflow-to-apps.md diff --git a/text/0000-move-deprecation-workflow-to-apps.md b/text/0000-move-deprecation-workflow-to-apps.md new file mode 100644 index 0000000000..d0e02478b9 --- /dev/null +++ b/text/0000-move-deprecation-workflow-to-apps.md @@ -0,0 +1,327 @@ +--- +stage: accepted +start-date: 2024-02-22T00:00.000Z +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: # delete teams that aren't relevant + - cli + - data + - framework + - learning + - steering + - typescript +prs: + accepted: # Fill this in with the URL for the Proposal RFC PR +project-link: +suite: +--- + + + +<-- Replace "RFC title" with the title of your RFC --> +# Move the deprecation workflow to apps by default + +## Summary + +Historically, folks have benefitted from [ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow). This behavior is _so useful_, that it should be built in to folks applications by default. + +tl;dr: move `setupDeprecationWorkflow` to `@ember/debug` + +> One paragraph explanation of the feature. + +## Motivation + +Everyone needs a deprecation-workflow, and yet `ember-cli-deprecation-workflow` is not part of the default blueprint. It probably doesn't need to be as the code it provides (if implemented in an app) is ~ 20 lines (but is slightly more if we want all features). + +This RFC proposes how we can ship deprecation workflow handling behavior in apps by default, which may give us a blessed path for better integrating with build time deprecations as well (though that is not the focus of this RFC). + + +## Detailed design + +There are only a few features of `ember-cli-deprecation-workflow` that we need to worry about: +- enabled or not - do we check deprecations at all, or ignore everything (current default) +- `throwOnUnhandled` - this is the most aggressive way to stay on top of your deprecations, but can be frustrating for folks who may not be willing to fix things in `node_modules` when new deprecations are introduced. + +- `window.flushDeprecations()` - prints the list of deprecations encountered since the last page refresh +- Matchers - a fuzzier way to match deprecation messages rather than strictly matching on the deprecation id (sometimes deprecation messages have information about surrounding / relevant context, and these could be used to more fine-grainedly work through large-in-numbers deprecations) +- Logging / Ignoring / Throwing - when encountering a matched deprecation (whether by id or by regex, how should it be handled?) + + +However, folks can get a basic deprecation-handling workflow going in their apps without the above features, + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('/deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` + this conditional import is now easily customizable for folks in their apps, so they could opt to _not_ strip deprecation messages in production, and see where deprecated code is being hit by users (reported via Sentry, BugSnag, or some other reporting tool) -- which may be handy for folks who have a less-than-perfect test suite (tests being the only current way to automatically detect where deprecated code lives). +3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) + ```js + import { registerDeprecationHandler } from '@ember/debug'; + + import config from '/config/environment'; + + const SHOULD_THROW = config.environment !== 'production'; + const SILENCED_DEPRECATIONS: string[] = [ + // Add ids of deprecations you temporarily want to silence here. + ]; + + registerDeprecationHandler((message, options, next) => { + if (!options) { + console.error('Missing options'); + throw new Error(message); + } + + if (SILENCED_DEPRECATIONS.includes(options.id)) { + return; + } else if (SHOULD_THROW) { + throw new Error(message); + } + + next(message, options); + }); + ``` + + +This simple implementation of deprrecation workflow may work for libraries' test-apps, but it is not as robust as what `ember-cli-deprecation-workflow` offers, per the above-listed set of features that folks are used to. + +To get all of that, taken from the [Modernization PR on ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159), this is what the deprecation-workflow file could look like: +```js +import { registerDeprecationHandler } from '@ember/debug'; + +const LOG_LIMIT = 100; + +export default function setupDeprecationWorkflow(config) { + self.deprecationWorkflow = self.deprecationWorkflow || {}; + self.deprecationWorkflow.deprecationLog = { + messages: {}, + }; + + registerDeprecationHandler((message, options, next) => + handleDeprecationWorkflow(config, message, options, next), + ); + + registerDeprecationHandler(deprecationCollector); + + self.deprecationWorkflow.flushDeprecations = flushDeprecations; +} + +let preamble = `import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; + +setupDeprecationWorkflow({ + workflow: [ +`; + +let postamble = ` ] +});`; + +export function detectWorkflow(config, message, options) { + if (!config || !config.workflow) { + return; + } + + let i, workflow, matcher, idMatcher; + for (i = 0; i < config.workflow.length; i++) { + workflow = config.workflow[i]; + matcher = workflow.matchMessage; + idMatcher = workflow.matchId; + + if (typeof idMatcher === 'string' && options && idMatcher === options.id) { + return workflow; + } else if (typeof matcher === 'string' && matcher === message) { + return workflow; + } else if (matcher instanceof RegExp && matcher.exec(message)) { + return workflow; + } + } +} + +export function flushDeprecations() { + let messages = self.deprecationWorkflow.deprecationLog.messages; + let logs = []; + + for (let message in messages) { + logs.push(messages[message]); + } + + let deprecations = logs.join(',\n') + '\n'; + + return preamble + deprecations + postamble; +} + +export function handleDeprecationWorkflow(config, message, options, next) { + let matchingWorkflow = detectWorkflow(config, message, options); + if (!matchingWorkflow) { + if (config && config.throwOnUnhandled) { + throw new Error(message); + } else { + next(message, options); + } + } else { + switch (matchingWorkflow.handler) { + case 'silence': + // no-op + break; + case 'log': { + let key = (options && options.id) || message; + + if (!self.deprecationWorkflow.logCounts) { + self.deprecationWorkflow.logCounts = {}; + } + + let count = self.deprecationWorkflow.logCounts[key] || 0; + self.deprecationWorkflow.logCounts[key] = ++count; + + if (count <= LOG_LIMIT) { + console.warn('DEPRECATION: ' + message); + if (count === LOG_LIMIT) { + console.warn( + 'To avoid console overflow, this deprecation will not be logged any more in this run.', + ); + } + } + + break; + } + case 'throw': + throw new Error(message); + default: + next(message, options); + break; + } + } +} + +export function deprecationCollector(message, options, next) { + let key = (options && options.id) || message; + let matchKey = options && key === options.id ? 'matchId' : 'matchMessage'; + + self.deprecationWorkflow.deprecationLog.messages[key] = + ' { handler: "silence", ' + matchKey + ': ' + JSON.stringify(key) + ' }'; + + next(message, options); +} +``` + +and at this point, we may as well build in in to `ember` and not use an additional library at all, **and this is what the primary proposal of this RFC is proposing: built the deprecation workflow setup function in to ember**, so re-running thorugh the setup steps: + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('/deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` + this conditional import is now easily customizable for folks in their apps, so they could opt to _not_ strip deprecation messages in production, and see where deprecated code is being hit by users (reported via Sentry, BugSnag, or some other reporting tool) -- which may be handy for folks who have a less-than-perfect test suite (tests being the only current way to automatically detect where deprecated code lives). +3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) + ```js + import { setupDeprecationWorkflow } from '@ember/debug'; + + setupDeprecationWorkflow({ + htrowOnUnhandled: true, + handlers: [ + /* ... handlers ... */ + ] + }); + ``` + + + + +## How we teach this + +We'd want to add a new section in the guides under [`Application Concerns`](https://guides.emberjs.com/release/applications/) that talks about deprecations, how and how to work through those deprecations. + +All of this content already exists using a similar strategy as above, here, [under "Configuring Ember"](https://guides.emberjs.com/release/configuring-ember/handling-deprecations/#toc_deprecation-workflow), and also walks through how to use `ember-cli-deprecation-workflow`. +When adapting the existing content, we'd want to remove so much focus on `ember-cli-deprecation-workflow`, as the behavior would be "built in". + +## Drawbacks + +For older projects, this could be _a_ migration. But as it is additional blueprint boilerplate, it is optional, and `ember-cli-deprecation-workflow` would continue to be a viable option for those already using it. + +## Alternatives + +Have `ember-cli-deprecation-workflow` installed by default, (and) transferring `ember-cli-deprecation-workflow` to the emberjs org. +(note: dependent on [This PR](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159)) + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('/deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` +3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) + ```js + import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; + + setupDeprecationWorkflow({ + htrowOnUnhandled: true, + handlers: [ + /* ... handlers ... */ + ] + }); + ``` + +## Unresolved questions + +n/a From 2ef5ac27d39e3a3eb2c77316e3e878a860f27ed6 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 12:45:45 -0500 Subject: [PATCH 12/66] Update --- text/0000-move-deprecation-workflow-to-apps.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/text/0000-move-deprecation-workflow-to-apps.md b/text/0000-move-deprecation-workflow-to-apps.md index d0e02478b9..37ecc4557f 100644 --- a/text/0000-move-deprecation-workflow-to-apps.md +++ b/text/0000-move-deprecation-workflow-to-apps.md @@ -114,7 +114,10 @@ However, folks can get a basic deprecation-handling workflow going in their apps This simple implementation of deprrecation workflow may work for libraries' test-apps, but it is not as robust as what `ember-cli-deprecation-workflow` offers, per the above-listed set of features that folks are used to. -To get all of that, taken from the [Modernization PR on ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159), this is what the deprecation-workflow file could look like: +To get all of those features from `ember-cli-deprecation-workflow`, we could define a function, `setupDeprecationWorkflow`, taken from the [Modernization PR on ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159), this is what the deprecation-workflow file could look like: + +
ember-cli-deprecation-workflow/index.js + ```js import { registerDeprecationHandler } from '@ember/debug'; @@ -232,6 +235,8 @@ export function deprecationCollector(message, options, next) { } ``` +
+ and at this point, we may as well build in in to `ember` and not use an additional library at all, **and this is what the primary proposal of this RFC is proposing: built the deprecation workflow setup function in to ember**, so re-running thorugh the setup steps: 1. applications must have `@embroider/macros` installed by default. From 4304c238b3a02f9077e4a2003b189e016c0f305d Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 12:47:13 -0500 Subject: [PATCH 13/66] Rename file --- ...ow-to-apps.md => 1009-move-deprecation-workflow-to-apps.md} | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) rename text/{0000-move-deprecation-workflow-to-apps.md => 1009-move-deprecation-workflow-to-apps.md} (99%) diff --git a/text/0000-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md similarity index 99% rename from text/0000-move-deprecation-workflow-to-apps.md rename to text/1009-move-deprecation-workflow-to-apps.md index 37ecc4557f..2d1fddb938 100644 --- a/text/0000-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -11,7 +11,7 @@ teams: # delete teams that aren't relevant - steering - typescript prs: - accepted: # Fill this in with the URL for the Proposal RFC PR + accepted: https://github.com/emberjs/rfcs/pull/1009 project-link: suite: --- @@ -30,7 +30,6 @@ project-link: Leave as is suite: Leave as is --> -<-- Replace "RFC title" with the title of your RFC --> # Move the deprecation workflow to apps by default ## Summary From c638e8b1a12172dbcc84b297de17c80d229d1fd6 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 12:49:55 -0500 Subject: [PATCH 14/66] answer why not this --- text/1009-move-deprecation-workflow-to-apps.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 2d1fddb938..bddd90d80a 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -326,6 +326,8 @@ Have `ember-cli-deprecation-workflow` installed by default, (and) transferring ` }); ``` +Why _not_ just do this tiny change to the blueprint? The whole implementation is _very small_, and it's something the framework ultimately has to support anyway, so building it in to `@ember/debug` provides a convinient way to for folks to get started. We also have a bit of a too-many-imports problem at the moment. + ## Unresolved questions n/a From ffece8ba90ba0f4012f7e5f7f7acde3fb08a6c70 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 15:21:22 -0500 Subject: [PATCH 15/66] Forgat a :00 --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index bddd90d80a..6eac899505 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -1,6 +1,6 @@ --- stage: accepted -start-date: 2024-02-22T00:00.000Z +start-date: 2024-02-22T00:00:00.000Z release-date: # In format YYYY-MM-DDT00:00:00.000Z release-versions: teams: # delete teams that aren't relevant From d36dcef37ee5aa957e8dc5552d356f4eb4984d11 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 16:04:51 -0500 Subject: [PATCH 16/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 6eac899505..b656f1a27d 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -236,7 +236,7 @@ export function deprecationCollector(message, options, next) { -and at this point, we may as well build in in to `ember` and not use an additional library at all, **and this is what the primary proposal of this RFC is proposing: built the deprecation workflow setup function in to ember**, so re-running thorugh the setup steps: +and at this point, we may as well build it into `ember` and not use an additional library at all, **and this is what the primary proposal of this RFC: build the deprecation workflow setup function in to ember**, so re-running through the setup steps: 1. applications must have `@embroider/macros` installed by default. 2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow From 2e9c5914ea423a1736be952422e4bc72b501ddff Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 16:04:57 -0500 Subject: [PATCH 17/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index b656f1a27d..5d815e7856 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -111,7 +111,7 @@ However, folks can get a basic deprecation-handling workflow going in their apps ``` -This simple implementation of deprrecation workflow may work for libraries' test-apps, but it is not as robust as what `ember-cli-deprecation-workflow` offers, per the above-listed set of features that folks are used to. +This simple implementation of deprecation workflow may work for libraries' test-apps, but it is not as robust as what `ember-cli-deprecation-workflow` offers, per the above-listed set of features that folks are used to. To get all of those features from `ember-cli-deprecation-workflow`, we could define a function, `setupDeprecationWorkflow`, taken from the [Modernization PR on ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159), this is what the deprecation-workflow file could look like: From ad9a9bc8427bb246749e804e0d60e36a1cd72fcd Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 16:05:03 -0500 Subject: [PATCH 18/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 5d815e7856..65ede6965a 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -266,7 +266,7 @@ and at this point, we may as well build it into `ember` and not use an additiona import { setupDeprecationWorkflow } from '@ember/debug'; setupDeprecationWorkflow({ - htrowOnUnhandled: true, + throwOnUnhandled: true, handlers: [ /* ... handlers ... */ ] From 759ee007a1899fd37d6933ceb09a24b8e569163c Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 16:05:07 -0500 Subject: [PATCH 19/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 65ede6965a..3e8ca32f60 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -319,7 +319,7 @@ Have `ember-cli-deprecation-workflow` installed by default, (and) transferring ` import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; setupDeprecationWorkflow({ - htrowOnUnhandled: true, + throwOnUnhandled: true, handlers: [ /* ... handlers ... */ ] From 45f675ad18241679e15b3505e62a032e59fb42b1 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 16:05:13 -0500 Subject: [PATCH 20/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 3e8ca32f60..7f8ea540f5 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -326,7 +326,7 @@ Have `ember-cli-deprecation-workflow` installed by default, (and) transferring ` }); ``` -Why _not_ just do this tiny change to the blueprint? The whole implementation is _very small_, and it's something the framework ultimately has to support anyway, so building it in to `@ember/debug` provides a convinient way to for folks to get started. We also have a bit of a too-many-imports problem at the moment. +Why _not_ just do this tiny change to the blueprint? The whole implementation is _very small_, and it's something the framework ultimately has to support anyway, so building it in to `@ember/debug` provides a convenient way for folks to get started. We also have a bit of a too-many-imports problem at the moment. ## Unresolved questions From f920ec251d8d438ab0ae7435a2754ab1c7beb3a4 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 22 Feb 2024 16:05:18 -0500 Subject: [PATCH 21/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1009-move-deprecation-workflow-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 7f8ea540f5..d7586396da 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -84,7 +84,7 @@ However, folks can get a basic deprecation-handling workflow going in their apps ``` this conditional import is now easily customizable for folks in their apps, so they could opt to _not_ strip deprecation messages in production, and see where deprecated code is being hit by users (reported via Sentry, BugSnag, or some other reporting tool) -- which may be handy for folks who have a less-than-perfect test suite (tests being the only current way to automatically detect where deprecated code lives). 3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) - ```js + ```ts import { registerDeprecationHandler } from '@ember/debug'; import config from '/config/environment'; From 9310137035a094ccc1675aff66af73c0691a047c Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Wed, 27 Mar 2024 12:11:20 -0400 Subject: [PATCH 22/66] Update text/1009-move-deprecation-workflow-to-apps.md Co-authored-by: Katie Gengler --- text/1009-move-deprecation-workflow-to-apps.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index d7586396da..1105e84b66 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -8,7 +8,6 @@ teams: # delete teams that aren't relevant - data - framework - learning - - steering - typescript prs: accepted: https://github.com/emberjs/rfcs/pull/1009 From f2396ba145d11b1f229806b45aac5ac0cb4717b1 Mon Sep 17 00:00:00 2001 From: ef4 Date: Fri, 14 Jun 2024 18:31:33 +0000 Subject: [PATCH 23/66] Advance RFC 1026 to Stage ready-for-release --- ...-ember-data-deprecate-store-extends-ember-object.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/text/1026-ember-data-deprecate-store-extends-ember-object.md b/text/1026-ember-data-deprecate-store-extends-ember-object.md index 46ad7a0c4a..00d2d01162 100644 --- a/text/1026-ember-data-deprecate-store-extends-ember-object.md +++ b/text/1026-ember-data-deprecate-store-extends-ember-object.md @@ -1,14 +1,14 @@ --- -stage: accepted +stage: ready-for-release start-date: 2024-05-11T00:00:00.000Z -release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-date: release-versions: -teams: # delete teams that aren't relevant +teams: - data prs: - accepted: https://github.com/emberjs/rfcs/pull/1026 + accepted: 'https://github.com/emberjs/rfcs/pull/1026' project-link: -suite: +suite: --- # EmberData | Deprecate Store extending EmberObject From 977014d58adfb0499ba8d0ea703367ad94353be4 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 14 Jun 2024 18:31:36 +0000 Subject: [PATCH 24/66] Update RFC 1026 ready-for-release PR URL --- text/1026-ember-data-deprecate-store-extends-ember-object.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/1026-ember-data-deprecate-store-extends-ember-object.md b/text/1026-ember-data-deprecate-store-extends-ember-object.md index 00d2d01162..87d94f1139 100644 --- a/text/1026-ember-data-deprecate-store-extends-ember-object.md +++ b/text/1026-ember-data-deprecate-store-extends-ember-object.md @@ -7,6 +7,7 @@ teams: - data prs: accepted: 'https://github.com/emberjs/rfcs/pull/1026' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/1035' project-link: suite: --- From bcf55e87189a647cac657d1e0e94677327b914fe Mon Sep 17 00:00:00 2001 From: ef4 Date: Fri, 14 Jun 2024 18:32:25 +0000 Subject: [PATCH 25/66] Advance RFC 1006 to Stage recommended --- text/1006-deprecate-action-template-helper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1006-deprecate-action-template-helper.md b/text/1006-deprecate-action-template-helper.md index 124eb9aea4..2920a29d43 100644 --- a/text/1006-deprecate-action-template-helper.md +++ b/text/1006-deprecate-action-template-helper.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2024-02-13T00:00:00.000Z release-date: 2024-06-07T00:00:00.000Z release-versions: From cffa29684cc3ccf3531bd740f56b307984968917 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 14 Jun 2024 18:32:28 +0000 Subject: [PATCH 26/66] Update RFC 1006 recommended PR URL --- text/1006-deprecate-action-template-helper.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/1006-deprecate-action-template-helper.md b/text/1006-deprecate-action-template-helper.md index 2920a29d43..ca274a3623 100644 --- a/text/1006-deprecate-action-template-helper.md +++ b/text/1006-deprecate-action-template-helper.md @@ -15,6 +15,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/1006' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1011' released: 'https://github.com/emberjs/rfcs/pull/1022' + recommended: 'https://github.com/emberjs/rfcs/pull/1036' project-link: --- From ef2bf7d0bb76632cdd3014c5376c8fb01fde5942 Mon Sep 17 00:00:00 2001 From: Katie Gengler Date: Fri, 12 Jul 2024 14:09:54 -0400 Subject: [PATCH 27/66] Arbitrary commit to trigger CI --- text/0743-ember-data-deprecate-legacy-imports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0743-ember-data-deprecate-legacy-imports.md b/text/0743-ember-data-deprecate-legacy-imports.md index 4670898e96..27a7372a8d 100644 --- a/text/0743-ember-data-deprecate-legacy-imports.md +++ b/text/0743-ember-data-deprecate-legacy-imports.md @@ -1,5 +1,5 @@ --- -stage: recommended +stage: recommended start-date: 2021-04-23T00:00:00.000Z release-date: 2023-09-18T00:00:00.000Z release-versions: From bee592d24e004253187d38bb12472d4fa8efc1b3 Mon Sep 17 00:00:00 2001 From: ef4 Date: Fri, 12 Jul 2024 18:20:26 +0000 Subject: [PATCH 28/66] Advance RFC 0995 to Stage recommended --- text/0995-deprecate-non-colocated-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0995-deprecate-non-colocated-components.md b/text/0995-deprecate-non-colocated-components.md index 943c2a0896..ab4f904b06 100644 --- a/text/0995-deprecate-non-colocated-components.md +++ b/text/0995-deprecate-non-colocated-components.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2023-12-15T00:00:00.000Z release-date: release-versions: From 23bc878c19e834193ada1afb33379aae60332ae0 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 12 Jul 2024 18:20:30 +0000 Subject: [PATCH 29/66] Update RFC 0995 recommended PR URL --- text/0995-deprecate-non-colocated-components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0995-deprecate-non-colocated-components.md b/text/0995-deprecate-non-colocated-components.md index ab4f904b06..1365249178 100644 --- a/text/0995-deprecate-non-colocated-components.md +++ b/text/0995-deprecate-non-colocated-components.md @@ -13,6 +13,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/995' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1012' released: 'https://github.com/emberjs/rfcs/pull/1023' + recommended: 'https://github.com/emberjs/rfcs/pull/1040' project-link: --- From dd09a792bd86dc298356229435acd0c34dd21990 Mon Sep 17 00:00:00 2001 From: ef4 Date: Fri, 9 Aug 2024 18:19:47 +0000 Subject: [PATCH 30/66] Advance RFC 0848 to Stage recommended --- text/0848-deprecate-array-prototype-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0848-deprecate-array-prototype-extensions.md b/text/0848-deprecate-array-prototype-extensions.md index 08f75c1925..d90d63f3b7 100644 --- a/text/0848-deprecate-array-prototype-extensions.md +++ b/text/0848-deprecate-array-prototype-extensions.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2022-08-21T00:00:00.000Z release-date: release-versions: From ea585fcbe8e31e3633a1173d59bc1470f5f19a30 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 9 Aug 2024 18:19:51 +0000 Subject: [PATCH 31/66] Update RFC 0848 recommended PR URL --- text/0848-deprecate-array-prototype-extensions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0848-deprecate-array-prototype-extensions.md b/text/0848-deprecate-array-prototype-extensions.md index d90d63f3b7..9ef0c9ac83 100644 --- a/text/0848-deprecate-array-prototype-extensions.md +++ b/text/0848-deprecate-array-prototype-extensions.md @@ -10,6 +10,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/848' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1020' released: 'https://github.com/emberjs/rfcs/pull/1042' + recommended: 'https://github.com/emberjs/rfcs/pull/1043' project-link: --- From 41e4eed904da7b346e12314f0f8641d54ac3374b Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 20 Sep 2024 15:06:25 -0400 Subject: [PATCH 32/66] Flip the suggestion to prefer using the addon in the blueprint --- .../1009-move-deprecation-workflow-to-apps.md | 113 ++++++++++-------- 1 file changed, 60 insertions(+), 53 deletions(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index 1105e84b66..f0c14c272f 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -48,6 +48,66 @@ This RFC proposes how we can ship deprecation workflow handling behavior in apps ## Detailed design + +Have `ember-cli-deprecation-workflow` installed by default. + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('./deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` +3. then in `app/deprecation-workflow.js` would use the already public API, + ```js + import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; + + setupDeprecationWorkflow({ + /** + false by default, but if a developer / team wants to be more aggressive about being proactive with + handling their deprecations, this should be set to "true" + */ + throwOnUnhandled: false, + handlers: [ + /* ... handlers ... */ + ] + }); + ``` + + +This follows the README of [ember-cli-deprecation-workflow](https://github.com/ember-cli/ember-cli-deprecation-workflow?tab=readme-ov-file#getting-started). + + + +## How we teach this + +We'd want to add a new section in the guides under [`Application Concerns`](https://guides.emberjs.com/release/applications/) that talks about deprecations, how and how to work through those deprecations. + +All of this content already exists using a similar strategy as above, here, [under "Configuring Ember"](https://guides.emberjs.com/release/configuring-ember/handling-deprecations/#toc_deprecation-workflow), and also walks through how to use `ember-cli-deprecation-workflow`. + +This README of [ember-cli-deprecation-workflow](https://github.com/ember-cli/ember-cli-deprecation-workflow?tab=readme-ov-file#getting-started) also explains, in detail, how to use this tool / workflow, and that content can be copied in to the guides. + +## Drawbacks + +For older projects, this could be _a_ migration. But as it is additional blueprint boilerplate, it is optional, and `ember-cli-deprecation-workflow` would continue to be a viable option for those already using it. + +## Alternatives + There are only a few features of `ember-cli-deprecation-workflow` that we need to worry about: - enabled or not - do we check deprecations at all, or ignore everything (current default) - `throwOnUnhandled` - this is the most aggressive way to stay on top of your deprecations, but can be frustrating for folks who may not be willing to fix things in `node_modules` when new deprecations are introduced. @@ -273,59 +333,6 @@ and at this point, we may as well build it into `ember` and not use an additiona ``` - - -## How we teach this - -We'd want to add a new section in the guides under [`Application Concerns`](https://guides.emberjs.com/release/applications/) that talks about deprecations, how and how to work through those deprecations. - -All of this content already exists using a similar strategy as above, here, [under "Configuring Ember"](https://guides.emberjs.com/release/configuring-ember/handling-deprecations/#toc_deprecation-workflow), and also walks through how to use `ember-cli-deprecation-workflow`. -When adapting the existing content, we'd want to remove so much focus on `ember-cli-deprecation-workflow`, as the behavior would be "built in". - -## Drawbacks - -For older projects, this could be _a_ migration. But as it is additional blueprint boilerplate, it is optional, and `ember-cli-deprecation-workflow` would continue to be a viable option for those already using it. - -## Alternatives - -Have `ember-cli-deprecation-workflow` installed by default, (and) transferring `ember-cli-deprecation-workflow` to the emberjs org. -(note: dependent on [This PR](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159)) - -1. applications must have `@embroider/macros` installed by default. -2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow - ```diff app/app.js - import Application from '@ember/application'; - + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; - - import loadInitializers from 'ember-load-initializers'; - import Resolver from 'ember-resolver'; - import config from 'test-app/config/environment'; - - + if (macroCondition(isDevelopingApp())) { - + importSync('/deprecation-workflow'); - + } - - export default class App extends Application { - modulePrefix = config.modulePrefix; - podModulePrefix = config.podModulePrefix; - Resolver = Resolver; - } - - loadInitializers(App, config.modulePrefix); - ``` -3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) - ```js - import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; - - setupDeprecationWorkflow({ - throwOnUnhandled: true, - handlers: [ - /* ... handlers ... */ - ] - }); - ``` - -Why _not_ just do this tiny change to the blueprint? The whole implementation is _very small_, and it's something the framework ultimately has to support anyway, so building it in to `@ember/debug` provides a convenient way for folks to get started. We also have a bit of a too-many-imports problem at the moment. ## Unresolved questions From 68f9b4d07b7562c9af61f203cb5d55828ceb7daa Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 20 Sep 2024 15:08:09 -0400 Subject: [PATCH 33/66] Updates --- text/1009-move-deprecation-workflow-to-apps.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md index f0c14c272f..c62922b3e0 100644 --- a/text/1009-move-deprecation-workflow-to-apps.md +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -29,19 +29,15 @@ project-link: Leave as is suite: Leave as is --> -# Move the deprecation workflow to apps by default +# Move the deprecation workflow library to be installed in apps by default ## Summary Historically, folks have benefitted from [ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow). This behavior is _so useful_, that it should be built in to folks applications by default. -tl;dr: move `setupDeprecationWorkflow` to `@ember/debug` - -> One paragraph explanation of the feature. - ## Motivation -Everyone needs a deprecation-workflow, and yet `ember-cli-deprecation-workflow` is not part of the default blueprint. It probably doesn't need to be as the code it provides (if implemented in an app) is ~ 20 lines (but is slightly more if we want all features). +Everyone needs a deprecation-workflow, and yet `ember-cli-deprecation-workflow` is not part of the default blueprint. This RFC proposes how we can ship deprecation workflow handling behavior in apps by default, which may give us a blessed path for better integrating with build time deprecations as well (though that is not the focus of this RFC). @@ -104,7 +100,7 @@ This README of [ember-cli-deprecation-workflow](https://github.com/ember-cli/emb ## Drawbacks -For older projects, this could be _a_ migration. But as it is additional blueprint boilerplate, it is optional, and `ember-cli-deprecation-workflow` would continue to be a viable option for those already using it. +For older projects, this could be _a_ migration. But as it is additional blueprint boilerplate, it is optional. ## Alternatives @@ -130,7 +126,7 @@ However, folks can get a basic deprecation-handling workflow going in their apps import config from 'test-app/config/environment'; + if (macroCondition(isDevelopingApp())) { - + importSync('/deprecation-workflow'); + + importSync('./deprecation-workflow'); + } export default class App extends Application { From 51c419bdf10b8a4cd4ceebaa0a03469986a87935 Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 4 Oct 2024 12:50:12 -0400 Subject: [PATCH 34/66] Template Tag In Routes --- text/1046-template-tag-in-routes.md | 184 ++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 text/1046-template-tag-in-routes.md diff --git a/text/1046-template-tag-in-routes.md b/text/1046-template-tag-in-routes.md new file mode 100644 index 0000000000..7ea43f0fba --- /dev/null +++ b/text/1046-template-tag-in-routes.md @@ -0,0 +1,184 @@ +--- +stage: accepted +start-date: 2024-10-04T00:00:00.000Z +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: # delete teams that aren't relevant + - framework + - learning + - typescript +prs: + accepted: https://github.com/emberjs/rfcs/pull/1046 +project-link: +suite: +--- + + + +# Use Template Tag in Routes + +## Summary + +Allow `app/templates/*.hbs` to convert to `app/temlates/*.gjs`. + +## Motivation + +We are rapidly approaching the point where Template Tag is the recommended way to author components. This means using `.gjs` (or `.gts`) files that combine your template and Javascript into one file. But you cannot currently use Template Tag to author the top-level templates invokes by the router (`app/templates/*.hbs`). + +This inconsistency is especially apparent when working on teaching materials for new users. Making people learn both `.hbs` with global component resolution and `.gjs` with strict template resolution before they can even make their first component is unreasonable. + +This RFC proposes allowing consistent use of `.gjs` everywhere. It doesn't remove any support for `.hbs`, but recommends that the guides default to all `.gjs`. + +## Detailed design + +The [implementation is small and already done](https://github.com/emberjs/ember.js/pull/20768). + +### Illustration By Example + +If you currently have this: + +```hbs +{{! app/templates/example.hbs }} +
+ +
+``` + +You can convert it to this: + +```gjs +// app/templates/example.gjs +import MainContent from 'my-app/components/main-content'; + +``` + +Key differences: + + - this is [strict handlebars](https://github.com/emberjs/rfcs/blob/master/text/0496-handlebars-strict-mode.md), so components are imported explicitly + - the controller is no longer `this`, it is `@controller`. + +Many things that you might have been forced to put on a controller can now be done directly. For example, if your controller has a `doSomething` event handler: + +```hbs +{{! app/templates/example.hbs }} +
+``` + +You now have options to implement it in-place in the same file. If it's stateless it can just be a function: + +```gjs +// app/templates/example.gjs + +// This import will be unnecessary after https://github.com/emberjs/rfcs/pull/1033 +import { on } from '@ember/modifier'; + +function doSomething() { + alert("It worked"); +} + + +``` + +If it's stateful, you can upgrade from a template-only component to a Glimmer component: + +```gjs +// app/templates/example.gjs +import { on } from '@ember/modifier'; +import Component from '@glimmer/component'; +import { tracked } from '@glimmer/tracking'; + +export default class extends Component { + @tracked activated = false; + + doSomething = () => { + this.activated = !this.activated; + } + + +} +``` + +### Implementation + +When Ember resolves a route template: + +1. Check whether the resulting value has a component manager. + - If no, do exactly what happens today. + - If yes, continue to step 2. +2. Synthesize a route template that invokes your component with these arguments: + - @model: which means exactly the same as always. + - @controller: makes the controller available. + +Keen observers will notice that this says nothing about only supporting gjs files. Any component is eligible, no matter how it's authored or what Component Manager it uses. This is by design, because there's no reason for the router to violate the component abstraction and care about how that component was implemented. + +However, in our learning materials we should present this as a feature designed for GJS files. Using it with components authored in .hbs would be needlessly confusing, because automatic template co-location **does not work in app/templates**, because it would collide with traditional route templates. + +### ember-route-template addon + +This RFC replaces the [ember-route-template](https://github.com/discourse/ember-route-template) addon. If you're already using it, it would continue to work without breaking, but you can simply delete all the calls to its `RouteTemplate` function and remove it. The popularity of that addon among teams who are already adopting Template Tag is an argument in favor of this RFC. + +### Codemod + +Because Embroider already generates imports for components, helpers, and modifiers in non-strict templates, there is [ongoing work](https://github.com/embroider-build/embroider/pull/2134) to offer Embroider's existing functionality as a Template Tag codemod. + +For route templates, the only extra feature required would be replacing `this` with `@controller`. + +### TypeScript + +No new typescript-specific features are required. If you're authoring route templates in GTS, Glint should treat them just like any other component. You will need to manually declare the signature for `@model` and `@controller`, but that is the same as now. + +## How we teach this + +This RFC was directly inspired by a first attempt at updating the Guides for Template Tag. It became immediately apparent that we can write *much* clearer guides if we can teach all GJS, instead of a mix of GJS and HBS. + +Starting at https://guides.emberjs.com/release/components/ when the first `application.hbs` file is introduced, we would use `.gjs` instead. In those opening examples that are empahsizing HTML, the only change to the content would be wrapping `` around the HTML. + +Progressing to https://guides.emberjs.com/release/components/introducing-components/, learners extract their first component. It now becomes possible to do that within the same file. This allows teaching fewer things in a single step. First, people can learn what a component is. Second, it can be refactored into a separate file. We can avoid teaching anything about "pascal case" and naming rules, because everything just follows javascript naming rules. + +When starting to teach routing in https://guides.emberjs.com/release/routing/defining-your-routes/, the file extensions change and `` wrappers are added, but nothing else on that page necessarily changes. + +In https://guides.emberjs.com/release/routing/query-params/, it's appropriate to first introduce the `@controller` argument. + +In https://guides.emberjs.com/release/routing/controllers/, the list of reasons to use a controller gets shortened to only queryParams, since now you can manage state directly in your route's component. + + +## Drawbacks + +There is appetite for a more ambitious RFC that changes more things about routing. Eliminating controllers, making routes play nice with the newer `@ember/destroyable` system, allowing parallel model hooks, etc, are all good goals. There is a risk that if we do those things soon, this would be seen as two steps of churn instead of one. + +I think we can mitigate that risk because + - we won't deprecate `.hbs` routes yet, so no churn is forced immediately. + - we can ship the Template Tag codemod so that even big apps can adopt at low cost + - it's extremely unlikely that a future routing design would use anything other than `.gjs` to define route entrypoints. By converting now, you are already moving in the right direction by eliminating all the non-strict behaviors. + + +## Alternatives + +The main alternative here is to do a bigger change to the routing system. A "Route Manager" RFC would allow the creation of new Route implementations that could have their own opinions about how to route to GJS files. This RFC does not preclude that other work from also happening. + +The main benefit of this RFC is that the [implementation is small and already done](https://github.com/emberjs/ember.js/pull/20768) so we could have it immediately. + + From 8523a0fd6cfe2eaadadd0d96ea933a4c15861994 Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 4 Oct 2024 13:06:31 -0400 Subject: [PATCH 35/66] Update text/1046-template-tag-in-routes.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/1046-template-tag-in-routes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1046-template-tag-in-routes.md b/text/1046-template-tag-in-routes.md index 7ea43f0fba..09e9d30103 100644 --- a/text/1046-template-tag-in-routes.md +++ b/text/1046-template-tag-in-routes.md @@ -35,7 +35,7 @@ Allow `app/templates/*.hbs` to convert to `app/temlates/*.gjs`. ## Motivation -We are rapidly approaching the point where Template Tag is the recommended way to author components. This means using `.gjs` (or `.gts`) files that combine your template and Javascript into one file. But you cannot currently use Template Tag to author the top-level templates invokes by the router (`app/templates/*.hbs`). +We are rapidly approaching the point where Template Tag is the recommended way to author components. This means using `.gjs` (or `.gts`) files that combine your template and Javascript into one file. But you cannot currently use Template Tag to author the top-level templates invoked by the router (`app/templates/*.hbs`). This inconsistency is especially apparent when working on teaching materials for new users. Making people learn both `.hbs` with global component resolution and `.gjs` with strict template resolution before they can even make their first component is unreasonable. From 3251dc10eb1114ccd9548024200b66681a30b336 Mon Sep 17 00:00:00 2001 From: ef4 Date: Fri, 4 Oct 2024 18:23:48 +0000 Subject: [PATCH 36/66] Advance RFC 1026 to Stage released --- text/1026-ember-data-deprecate-store-extends-ember-object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1026-ember-data-deprecate-store-extends-ember-object.md b/text/1026-ember-data-deprecate-store-extends-ember-object.md index 87d94f1139..5566797a39 100644 --- a/text/1026-ember-data-deprecate-store-extends-ember-object.md +++ b/text/1026-ember-data-deprecate-store-extends-ember-object.md @@ -1,5 +1,5 @@ --- -stage: ready-for-release +stage: released start-date: 2024-05-11T00:00:00.000Z release-date: release-versions: From 6f4ead25f6f3dc1df29742f68bbb9cf6523217ce Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 4 Oct 2024 18:23:51 +0000 Subject: [PATCH 37/66] Update RFC 1026 released PR URL --- text/1026-ember-data-deprecate-store-extends-ember-object.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/1026-ember-data-deprecate-store-extends-ember-object.md b/text/1026-ember-data-deprecate-store-extends-ember-object.md index 5566797a39..1e88da6cb6 100644 --- a/text/1026-ember-data-deprecate-store-extends-ember-object.md +++ b/text/1026-ember-data-deprecate-store-extends-ember-object.md @@ -8,6 +8,7 @@ teams: prs: accepted: 'https://github.com/emberjs/rfcs/pull/1026' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1035' + released: 'https://github.com/emberjs/rfcs/pull/1047' project-link: suite: --- From 8cfb0b15f24f4bf38888fd63248ae6e0e3fdb2cb Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 4 Oct 2024 15:01:58 -0400 Subject: [PATCH 38/66] Update text/1046-template-tag-in-routes.md Co-authored-by: Ignace Maes <10243652+IgnaceMaes@users.noreply.github.com> --- text/1046-template-tag-in-routes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1046-template-tag-in-routes.md b/text/1046-template-tag-in-routes.md index 09e9d30103..505216d002 100644 --- a/text/1046-template-tag-in-routes.md +++ b/text/1046-template-tag-in-routes.md @@ -93,7 +93,7 @@ function doSomething() { } ``` From 519e97a4cc190d55118c8f1fd6aa06890520ccde Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Mon, 28 Oct 2024 10:24:22 -0400 Subject: [PATCH 39/66] this RFC is unimplemented --- text/0389-dynamic-tag-names.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0389-dynamic-tag-names.md b/text/0389-dynamic-tag-names.md index 57d56f1d79..55f6ec7151 100644 --- a/text/0389-dynamic-tag-names.md +++ b/text/0389-dynamic-tag-names.md @@ -1,5 +1,5 @@ --- -stage: recommended +stage: accepted start-date: 2018-10-14T00:00:00.000Z release-date: # FIXME release-versions: # FIXME From 7a2100b8c5e1fb7b7fdec64926215f9c27791395 Mon Sep 17 00:00:00 2001 From: ef4 Date: Fri, 1 Nov 2024 18:08:42 +0000 Subject: [PATCH 40/66] Advance RFC 0779 to Stage released --- text/0779-first-class-component-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0779-first-class-component-templates.md b/text/0779-first-class-component-templates.md index e2ba1bd2d5..0dbe5bd61d 100644 --- a/text/0779-first-class-component-templates.md +++ b/text/0779-first-class-component-templates.md @@ -1,5 +1,5 @@ --- -stage: ready-for-release +stage: released start-date: 2021-12-03T00:00:00.000Z release-date: release-versions: From d677b1efa32f459f0a696ab1dbf062ac67888f14 Mon Sep 17 00:00:00 2001 From: "Ember.js RFCS CI" Date: Fri, 1 Nov 2024 18:08:46 +0000 Subject: [PATCH 41/66] Update RFC 0779 released PR URL --- text/0779-first-class-component-templates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0779-first-class-component-templates.md b/text/0779-first-class-component-templates.md index 0dbe5bd61d..e71e29a153 100644 --- a/text/0779-first-class-component-templates.md +++ b/text/0779-first-class-component-templates.md @@ -10,6 +10,7 @@ teams: prs: accepted: 'https://github.com/emberjs/rfcs/pull/779' ready-for-release: 'https://github.com/emberjs/rfcs/pull/871' + released: 'https://github.com/emberjs/rfcs/pull/1050' project-link: --- From 195d8c578d956870c4b900117d326f15447b8c61 Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 8 Nov 2024 14:06:25 -0500 Subject: [PATCH 42/66] Update 1026-ember-data-deprecate-store-extends-ember-object.md --- text/1026-ember-data-deprecate-store-extends-ember-object.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/1026-ember-data-deprecate-store-extends-ember-object.md b/text/1026-ember-data-deprecate-store-extends-ember-object.md index 1e88da6cb6..4e344fcda2 100644 --- a/text/1026-ember-data-deprecate-store-extends-ember-object.md +++ b/text/1026-ember-data-deprecate-store-extends-ember-object.md @@ -3,6 +3,7 @@ stage: released start-date: 2024-05-11T00:00:00.000Z release-date: release-versions: + ember-data: 5.3.0 teams: - data prs: @@ -108,4 +109,4 @@ none ## Unresolved questions -None \ No newline at end of file +None From 895aac3fade278cc209c6fbec12f723bbaab3b1b Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 8 Nov 2024 14:08:55 -0500 Subject: [PATCH 43/66] Update 0779-first-class-component-templates.md --- text/0779-first-class-component-templates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0779-first-class-component-templates.md b/text/0779-first-class-component-templates.md index e71e29a153..06a88ac1ce 100644 --- a/text/0779-first-class-component-templates.md +++ b/text/0779-first-class-component-templates.md @@ -3,6 +3,8 @@ stage: released start-date: 2021-12-03T00:00:00.000Z release-date: release-versions: + ember-template-imports: 4.0.0 + ember-source: 3.28.0 teams: - framework - learning From 1175fea8b0b2aa6769b63f9f1f806193d8ca0f08 Mon Sep 17 00:00:00 2001 From: Katie Gengler Date: Fri, 8 Nov 2024 14:22:51 -0500 Subject: [PATCH 44/66] Update pull_request_template.md Fix typo --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 36ded6d2cd..6cd2c78254 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,7 +14,7 @@ and choosing `View file' from the `...' menu in the right hand corner of the fil This pull request is proposing a new RFC. -To succeed, it will need to pass into the [Exploring Stage](https://github.com/emberjs/rfcs#exploring)), followed by the [Accepted Stage](https://github.com/emberjs/rfcs#accepted). +To succeed, it will need to pass into the [Exploring Stage](https://github.com/emberjs/rfcs#exploring), followed by the [Accepted Stage](https://github.com/emberjs/rfcs#accepted). A Proposed or Exploring RFC may also move to the [Closed Stage](https://github.com/emberjs/rfcs#closed) if it is withdrawn by the author or if it is rejected by the Ember team. This requires an "FCP to Close" period. From 16c993c69cbe30b860a3bf2b0948a9dab35ab707 Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 22 Nov 2024 14:48:12 -0500 Subject: [PATCH 45/66] updating alternatives and hbs teaching --- text/1046-template-tag-in-routes.md | 53 ++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/text/1046-template-tag-in-routes.md b/text/1046-template-tag-in-routes.md index 505216d002..023108d48f 100644 --- a/text/1046-template-tag-in-routes.md +++ b/text/1046-template-tag-in-routes.md @@ -10,11 +10,11 @@ teams: # delete teams that aren't relevant prs: accepted: https://github.com/emberjs/rfcs/pull/1046 project-link: -suite: +suite: --- - + +# v2 App Format + +## Summary + +This RFC defines a new app format, +building off the prior work in [v2 Addon format](https://github.com/emberjs/rfcs/pull/507), +that is designed to make Ember apps more compatible with the rest of the JavaScript ecosystem. This RFC will define conventions of the app such that it is _possible_ to confidently build an ember app without ember-cli (e.g.: in jsbin). + +## Motivation + +Ember has a long-standing tradition of pioneering developer-friendly conventions, allowing developers to build powerful web applications with minimal configuration. Over the years, we have embraced the philosophy of "convention over configuration," making it easy for developers to get started and achieve consistency across Ember projects. + +However, as the JavaScript ecosystem evolves, it becomes increasingly important for Ember to adapt and interoperate seamlessly with the broader web development landscape. The introduction of a v2 app format is driven by several key motivations: + +1. Compatibility with the JavaScript Ecosystem + +Ember's success lies not only in its robust features but also in its ability to integrate effortlessly with other JavaScript libraries and tools. With the v2 app format, we aim to make Ember applications more compatible with the rest of the JavaScript ecosystem. This means that developers should feel confident in building Ember applications without the need for specialized tooling like ember-cli. Whether it's experimenting with code in an environment like jsbin or integrating Ember into projects that use native packagers like Vite, Webpack, or Turbopack, the v2 app format should empower developers to work seamlessly with Ember in diverse contexts. + + +2. Improved Insight into App Initialization + +Ember's boot process lacks clear, documented specifications. This lack of clarity means that developers often struggle to comprehend the precise steps involved in booting an Ember app manually (if they ever attempt to do so). + +The v2 app format aims to rectify this by providing comprehensive documentation that outlines the intricacies of an Ember app's initialization process. By shedding light on the sequence of steps necessary to bootstrap an Ember application, developers will gain a deeper understanding of the framework's internal mechanisms. This newfound knowledge will empower developers to confidently control and customize the app initialization process, enabling them to tailor Ember apps to their specific needs. + +3. Performance and Optimization + +Performance is a critical concern for modern web applications. The v2 app format is designed to deliver tangible benefits to Ember developers and users. Most importantly, all capabilities of a chosen packager (be that Vite, Webpack, turbopack, etc) would become available to Ember (module federation, alternative SSR methods, etc). + +4. Interoperability with Native Packagers + +Embracing native packagers such as Vite, Webpack, and Turbopack is crucial for staying current with JavaScript ecosystem trends. The v2 app format is designed to accommodate these packagers seamlessly, ensuring that Ember applications can harness the benefits of these tools while maintaining compatibility. + +5. Future-Proofing + +Lastly, the v2 app format positions Ember to take advantage of ongoing and future developments in the wider JavaScript ecosystem related to code bundling and optimization. By aligning with industry trends, Ember remains a forward-looking framework, ready to embrace new technologies and practices. + +## Detailed design + +How much of this should be "the path/migration to" as opposed to "this is the end state, details can be part of implementation"? + +1. start with embroider-strictest +2. all blueprint addons must be either in the v2 format, or non-addons entirely (such as qunit-dom's recent change to real type=module package) +3. use Vite w/ embroider +4. remove unneeded dependencies + - ember-auto-import + - replaced by _the packager's_ own way of processing dependencies + (requires all consumed dependencies to _not_ be v1 addons) + - broccoli-asset-rev + - replaced by _the packager's_ production build mode + - ember-cli-babel + - replaced by actual babel + - ember-cli-clean-css + - replaced by _the packager's_ production build mode + - ember-cli-htmlbars + - replaced by [babel-plugin-ember-template-compilation](https://github.com/emberjs/babel-plugin-ember-template-compilation/) and embroider-provided build plugins + - ember-cli-inject-live-reload + - replaced by _the packager's_ development mode + - ember-cli-sri + - replaced by _the packager's_ production build mode + - ember-cli-terser + - replaced by _the packager's_ production build mode + - ember-fetch + - requires work in `@ember/test-helpers` and `ember-fetch` to make this smooth. + - ember-load-initializers + - tbd + - ember-resolver + - tbd + - loader.js + - require / AMD has been private for a long time, and folks should not be using it. + + +> This is the bulk of the RFC. + +> Explain the design in enough detail for somebody +familiar with the framework to understand, and for somebody familiar with the +implementation to implement. This should get into specifics and corner-cases, +and include examples of how the feature is used. Any new terminology should be +defined here. + +## How we teach this + +> What names and terminology work best for these concepts and why? How is this +idea best presented? As a continuation of existing Ember patterns, or as a +wholly new one? + +> Would the acceptance of this proposal mean the Ember guides must be +re-organized or altered? Does it change how Ember is taught to new users +at any level? + +> How should this feature be introduced and taught to existing Ember +users? + +## Drawbacks + +> Why should we *not* do this? Please consider the impact on teaching Ember, +on the integration of this feature with other existing and planned features, +on the impact of the API churn on existing apps, etc. + +> There are tradeoffs to choosing any path, please attempt to identify them here. + +## Alternatives + +> What other designs have been considered? What is the impact of not doing this? + +> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. + +## Unresolved questions + +> Optional, but suggested for first drafts. What parts of the design are still +TBD? From 095a2f9958e66d1f3a530ac3a16e220521d3c78d Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 4 Nov 2023 11:02:03 -0400 Subject: [PATCH 58/66] Update text/0977-template.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/0977-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0977-template.md b/text/0977-template.md index 05309d5bf8..9ead02c803 100644 --- a/text/0977-template.md +++ b/text/0977-template.md @@ -70,7 +70,7 @@ Lastly, the v2 app format positions Ember to take advantage of ongoing and futur How much of this should be "the path/migration to" as opposed to "this is the end state, details can be part of implementation"? 1. start with embroider-strictest -2. all blueprint addons must be either in the v2 format, or non-addons entirely (such as qunit-dom's recent change to real type=module package) +2. all blueprint addons must be either in the v2 format, or non-addons entirely (such as qunit-dom's recent change to real `type=module` package) 3. use Vite w/ embroider 4. remove unneeded dependencies - ember-auto-import From ceab8f96c013bcce1e39f58a9eee6e3a8bba4bb4 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 4 Nov 2023 11:02:10 -0400 Subject: [PATCH 59/66] Update text/0977-template.md Co-authored-by: MrChocolatine <47531779+MrChocolatine@users.noreply.github.com> --- text/0977-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0977-template.md b/text/0977-template.md index 9ead02c803..53d258ea37 100644 --- a/text/0977-template.md +++ b/text/0977-template.md @@ -71,7 +71,7 @@ How much of this should be "the path/migration to" as opposed to "this is the en 1. start with embroider-strictest 2. all blueprint addons must be either in the v2 format, or non-addons entirely (such as qunit-dom's recent change to real `type=module` package) -3. use Vite w/ embroider +3. use Vite with Embroider 4. remove unneeded dependencies - ember-auto-import - replaced by _the packager's_ own way of processing dependencies From 490c1666a4a9eba88b7a070e6022506bcc4b7ee1 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Tue, 5 Nov 2024 13:07:49 +0000 Subject: [PATCH 60/66] fix file name --- text/{0977-template.md => 0977-v2-app-format.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0977-template.md => 0977-v2-app-format.md} (100%) diff --git a/text/0977-template.md b/text/0977-v2-app-format.md similarity index 100% rename from text/0977-template.md rename to text/0977-v2-app-format.md From b3ee0f5df72bbed4e24a74ffb8ac42c6d2c9edbd Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Wed, 13 Nov 2024 07:28:38 +0000 Subject: [PATCH 61/66] update content --- text/0977-v2-app-format.md | 46 +++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md index 53d258ea37..98641fb22e 100644 --- a/text/0977-v2-app-format.md +++ b/text/0977-v2-app-format.md @@ -33,39 +33,46 @@ suite: Leave as is ## Summary This RFC defines a new app format, -building off the prior work in [v2 Addon format](https://github.com/emberjs/rfcs/pull/507), -that is designed to make Ember apps more compatible with the rest of the JavaScript ecosystem. This RFC will define conventions of the app such that it is _possible_ to confidently build an ember app without ember-cli (e.g.: in jsbin). +building off the prior work in [v2 Addon format](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format), +that is designed to make Ember apps more compatible with the rest of the JavaScript ecosystem. This RFC will define conventions of the app and clearly identify functionality that is considered "compat" and could be considered optional in the near future. ## Motivation -Ember has a long-standing tradition of pioneering developer-friendly conventions, allowing developers to build powerful web applications with minimal configuration. Over the years, we have embraced the philosophy of "convention over configuration," making it easy for developers to get started and achieve consistency across Ember projects. +When ember-cli was created there was no existing JS tooling that met the needs of the Ember Framework. Over the years we have added more and more developer-friendly conventions to our build system that many Ember applications and addons depend on. As the JavaScript tooling story has gotten a lot better of the years Ember has fallen behind because our custom-built tools have not been keeping up with the wider community. Efforts have been started to improve the situation with the advent of [Embroider](https://github.com/embroider-build/embroider) but the current stable release of Embroider still runs inside ember-cli and is somewhat bound in performance and capability by the underlying technology [broccolijs](https://github.com/broccolijs/broccoli). -However, as the JavaScript ecosystem evolves, it becomes increasingly important for Ember to adapt and interoperate seamlessly with the broader web development landscape. The introduction of a v2 app format is driven by several key motivations: +Over the past year the Ember Core Tooling team have been working hard to invert the control between the bundler and ember-cli, which means that instead of ember-cli running the bundler as part of its build system the whole Ember build process will essentially become a plugin to the bundler. This means that we can more effectively make use of bundler innovations, performance improvements, and we are more capable of adapting to whatever next generation of build systems come to the Javascript ecosystemm. -1. Compatibility with the JavaScript Ecosystem +With the Ember build system as a plugin to bundlers (such as Vite or Webpack) we also have the ability to only intervene on things that are Emberisims (i.e. not-standard) and as we work to make Ember more standard we can eventually turn off these compat plugins. -Ember's success lies not only in its robust features but also in its ability to integrate effortlessly with other JavaScript libraries and tools. With the v2 app format, we aim to make Ember applications more compatible with the rest of the JavaScript ecosystem. This means that developers should feel confident in building Ember applications without the need for specialized tooling like ember-cli. Whether it's experimenting with code in an environment like jsbin or integrating Ember into projects that use native packagers like Vite, Webpack, or Turbopack, the v2 app format should empower developers to work seamlessly with Ember in diverse contexts. +This RFC is not going to describe a new blueprint where you don't need any compatibility plugins to run an Ember app, this RFC instead is going to propose a new blueprint that has all the compatibility plugins turned on so that it is easiest for most people to upgrade to. +## Key Ideas -2. Improved Insight into App Initialization +Much like the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format#key-ideas) we want the new app blueprint to rely on ES Modules and not leave anything hidden or automatic. This not noly makes it easier for developers to know where things are coming from, it also makes it easier for bundlers to know what to do with Ember applications. -Ember's boot process lacks clear, documented specifications. This lack of clarity means that developers often struggle to comprehend the precise steps involved in booting an Ember app manually (if they ever attempt to do so). +Each of the following sections go into detail of all the changes between the current blueprint and the new proposal which is currently being developed at https://github.com/embroider-build/app-blueprint -The v2 app format aims to rectify this by providing comprehensive documentation that outlines the intricacies of an Ember app's initialization process. By shedding light on the sequence of steps necessary to bootstrap an Ember application, developers will gain a deeper understanding of the framework's internal mechanisms. This newfound knowledge will empower developers to confidently control and customize the app initialization process, enabling them to tailor Ember apps to their specific needs. +## Detailed design -3. Performance and Optimization +In this section I'm going to go through each of the changes in the new proposed blueprint, in each section I will do my best to explain the reasoningin for why it needs to be like this but if you have any questions or comments please feel free to comment on the RFC and we will try to update that section. -Performance is a critical concern for modern web applications. The v2 app format is designed to deliver tangible benefits to Ember developers and users. Most importantly, all capabilities of a chosen packager (be that Vite, Webpack, turbopack, etc) would become available to Ember (module federation, alternative SSR methods, etc). +### Entrypoint -> index.html -4. Interoperability with Native Packagers +### App Entrypoint -> app/app.js -Embracing native packagers such as Vite, Webpack, and Turbopack is crucial for staying current with JavaScript ecosystem trends. The v2 app format is designed to accommodate these packagers seamlessly, ensuring that Ember applications can harness the benefits of these tools while maintaining compatibility. +TODO add a comment about eagerness with the compat module import -5. Future-Proofing +### Application Config -> app/config/environment.js and config/environment.js + +### Test Entrypoint -> tests/index.html and tests/test-helper.js + +### Explicit Babel Config -> babel.config.cjs + +### Ember Pre-Build Config -> ember-cli-build.js + +### Explicit Bundler Config -> vite.config.mjs -Lastly, the v2 app format positions Ember to take advantage of ongoing and future developments in the wider JavaScript ecosystem related to code bundling and optimization. By aligning with industry trends, Ember remains a forward-looking framework, ready to embrace new technologies and practices. -## Detailed design How much of this should be "the path/migration to" as opposed to "this is the end state, details can be part of implementation"? @@ -135,7 +142,10 @@ on the impact of the API churn on existing apps, etc. > This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. +In this section I'll + ## Unresolved questions -> Optional, but suggested for first drafts. What parts of the design are still -TBD? +### Application config + +In the current design of the new build we are still using the node-generated config that all ember developers are used to. We have considered unifying the `config/environemnt.js` and `app/config/environment.js` files to reduce complexity in the learning story but From 2e5faf1f053c91cd7a86c9c9fbca16f9ba631dbf Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Wed, 13 Nov 2024 16:13:11 +0100 Subject: [PATCH 62/66] start filling out some of the sections --- text/0977-v2-app-format.md | 72 ++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md index 98641fb22e..ece34257f6 100644 --- a/text/0977-v2-app-format.md +++ b/text/0977-v2-app-format.md @@ -34,32 +34,90 @@ suite: Leave as is This RFC defines a new app format, building off the prior work in [v2 Addon format](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format), -that is designed to make Ember apps more compatible with the rest of the JavaScript ecosystem. This RFC will define conventions of the app and clearly identify functionality that is considered "compat" and could be considered optional in the near future. +and is designed to make Ember apps more compatible with the rest of the JavaScript ecosystem. This RFC will define conventions of the app and clearly identify functionality that is considered "compatibility integrations" and could be considered optional in the near future. ## Motivation -When ember-cli was created there was no existing JS tooling that met the needs of the Ember Framework. Over the years we have added more and more developer-friendly conventions to our build system that many Ember applications and addons depend on. As the JavaScript tooling story has gotten a lot better of the years Ember has fallen behind because our custom-built tools have not been keeping up with the wider community. Efforts have been started to improve the situation with the advent of [Embroider](https://github.com/embroider-build/embroider) but the current stable release of Embroider still runs inside ember-cli and is somewhat bound in performance and capability by the underlying technology [broccolijs](https://github.com/broccolijs/broccoli). +When ember-cli was created there was no existing JS tooling that met the needs of the Ember Framework. Over the years we have added more and more developer-friendly conventions to our build system that many Ember applications and addons depend on. As the wider JavaScript tooling story has evolved over the years Ember has fallen behind, this is mainly because our custom-built tools have not been keeping up with the wider community and we haven’t been able to directly use any more advanced tooling in our apps. Efforts have been started to improve the situation with the advent of [Embroider](https://github.com/embroider-build/embroider) but the current stable release of Embroider still runs inside ember-cli and is somewhat bound in terms of performance and capability by the underlying technology [broccolijs](https://github.com/broccolijs/broccoli) and some other architectural decisions. -Over the past year the Ember Core Tooling team have been working hard to invert the control between the bundler and ember-cli, which means that instead of ember-cli running the bundler as part of its build system the whole Ember build process will essentially become a plugin to the bundler. This means that we can more effectively make use of bundler innovations, performance improvements, and we are more capable of adapting to whatever next generation of build systems come to the Javascript ecosystemm. +Over the past year the Ember Core Tooling team have been working hard to invert the control between bundlers and ember-cli, which means that instead of ember-cli running a bundler (such as Webpack) as part of its build system the whole Ember build process will essentially become a plugin to the bundler. This means that we can more effectively make use of bundler innovations, performance improvements, and we are more capable of adapting to whatever next generation of build systems come to the Javascript ecosystem. -With the Ember build system as a plugin to bundlers (such as Vite or Webpack) we also have the ability to only intervene on things that are Emberisims (i.e. not-standard) and as we work to make Ember more standard we can eventually turn off these compat plugins. +With the Ember build system as a plugin to bundlers (such as Vite or Webpack) we also have the ability to only intervene on things that are Emberisims (i.e. not-standard) and as we work to make Ember more standard we can eventually turn off these ”compatibility plugins”. Compatibility plugins will need to be powered by an “ember prebuild” that collects information about your app and addons and output metadata that the bundler plugins will consume. The intention is that this prebuild will be done automatically for you as part of the bundler plugin setup and you should not have to worry about preforming extra steps. -This RFC is not going to describe a new blueprint where you don't need any compatibility plugins to run an Ember app, this RFC instead is going to propose a new blueprint that has all the compatibility plugins turned on so that it is easiest for most people to upgrade to. +This RFC is not going to describe a new blueprint where you don't need any compatibility plugins (or an ember prebuild) to run an Ember app, this RFC instead is going to propose a new blueprint that has all the compatibility plugins turned on so that it is easiest for most people to upgrade to. Any discussion about a minimal “compatibility-free” blueprint should happen in a later RFC. ## Key Ideas -Much like the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format#key-ideas) we want the new app blueprint to rely on ES Modules and not leave anything hidden or automatic. This not noly makes it easier for developers to know where things are coming from, it also makes it easier for bundlers to know what to do with Ember applications. +Much like the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format#key-ideas) we want the new app blueprint to rely on ES Modules and not leave anything hidden or automatic. This not only makes it easier for developers to know where things are coming from, it also makes it easier for bundlers to know what to do with Ember applications. Each of the following sections go into detail of all the changes between the current blueprint and the new proposal which is currently being developed at https://github.com/embroider-build/app-blueprint ## Detailed design -In this section I'm going to go through each of the changes in the new proposed blueprint, in each section I will do my best to explain the reasoningin for why it needs to be like this but if you have any questions or comments please feel free to comment on the RFC and we will try to update that section. +In this section I'm going to go through each of the changes in the new proposed blueprint, in each section I will do my best to explain the reasoning for why it needs to be like this but if you have any questions or comments please feel free to comment on the RFC and we will try to update that section. ### Entrypoint -> index.html +A lot of modern bundlers make use of your index.html file as the main entrypoint to kick off bundling. Any files that are referenced in your index.html would then end up getting bundled. + +This already an issue for an Ember app because the index.html that is traditionally found at `app/index.html` is ultimately not used directly. Information in the index.html file is used to generate the real file that is used at the end of the pipeline. + +This new blueprint proposes to remove this oddity and both allow bundlers to look directly at the source index.html instead of the output build artifact and will remove almost all ember build customisations that targed the index.html. We still intend to support `{{content-for}}` entries in the index.html with a few caveats that I will explain in more detail in the next section, but the support for `{{content-for}}` will need to be provided by a bundler plugin that has the ability to replace content in the index.html. + +The index.html will also have an inline script tag that performs the application boot. This process used to be hidden away in a `{{content-for “app-boot”}}` section in one of the javascript files automatically added to the index.html during the build pipeline. This explicit inline application boot significantly improves the visibility of how the application actually boots and should allow developers to customise that process without our build system needing to provide a way to handle those customisations. Incidently this now means that if you are using an addon to customise the `{{content-for “app-boot”}}` then this will no longer work. If Embroider discovers that an app is trying to customise the app-boot in any way it will throw this error: + +> Your app uses at least one classic addon that provides content-for 'app-boot'. This is no longer supported. +> +> With Embroider, you have full control over the app-boot script, so classic addons no longer need to modify it under the hood. +> +> The following code is used for your app boot: +> +> {{inline-custom-app-boot-code}} +> +> 1. If you want to keep the same behavior, copy and paste it to the app-boot script included in app/index.html. +> 2. Once app/index.html has the content you need, remove the present error by setting "useAddonAppBoot" to false in the build options. + +The embedded boot section in the index.html will look like the following: + +``` + +``` + +This boot section touches app/app.js and the new app/config/environment.js files which are both described in sections below. + +#### content-for in index.html + +The way that `{{content-for}}` works in ember-cli currently is under-specified and cronically under documented. The highest level summary is that anyone can currently add `{{content—for “any-string“}}` and as long as any active ember-addon provided a value for that specific content-for section the exact string that the addon provided would be injected at that point in the document. While we are familiar with sections like `{{content-for “head”}}` there is no pre-defined list and the common sections are only common due to convention. This makes it **extremely** hard for a modern build system that doesn’t understand ember-addons to be able to know what to do with these sections. + +We are proposing that we codify the conventional sections as the default set, and the ember prebuild will be able to collate the text each addon wants to add to these sections + +- head +- test-head +- head-footer +- test-head-footer +- body +- test-body +- body-footer +- test-body-footer +- config-module +- app-boot + +If you are using any other custom `{{content-for}}` section then you will need to explicitly pass this to your embroider config via a `availableContentForTypes` configuration + ### App Entrypoint -> app/app.js +In a classic build ember-cli would collect all the of the modules in your app into an entrypoint in the build that would go through and define each of the modules in the require.js AMD registry. There is already an RFC that describes the fact that we want to deprecate this AMD registry, but the key thing for this RFC is that we are trying to think of our app as series of real ES Modules we need to provide some way for the built-in discovery of these modules that allows Ember to still resolve those modules by name (for Dependency Injection concerns like services) + +We are providing this with the virtual module `'@embroider/virtual/compat-modules';`. This means that any bundler plugin that wants to support Ember needs to be able to support virtual module imports. The contents of this file can be obtained by asking the Embroider resolver which collates the list of modules during the Ember prebuild. + +We then pass the list of modules to an updated version of the Ember Resolver (that has already been released ) + +TODO add an example and keep describing + TODO add a comment about eagerness with the compat module import ### Application Config -> app/config/environment.js and config/environment.js From fa33cedb5de61382f2f59697226f20dcb9f44a53 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Fri, 15 Nov 2024 18:14:44 +0100 Subject: [PATCH 63/66] finalise my changes --- text/0977-v2-app-format.md | 297 ++++++++++++++++++++++++++++--------- 1 file changed, 228 insertions(+), 69 deletions(-) diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md index ece34257f6..85c39b06b6 100644 --- a/text/0977-v2-app-format.md +++ b/text/0977-v2-app-format.md @@ -110,100 +110,259 @@ If you are using any other custom `{{content-for}}` section then you will need t ### App Entrypoint -> app/app.js -In a classic build ember-cli would collect all the of the modules in your app into an entrypoint in the build that would go through and define each of the modules in the require.js AMD registry. There is already an RFC that describes the fact that we want to deprecate this AMD registry, but the key thing for this RFC is that we are trying to think of our app as series of real ES Modules we need to provide some way for the built-in discovery of these modules that allows Ember to still resolve those modules by name (for Dependency Injection concerns like services) +In a classic build ember-cli would collect all the of the modules in your app into an entrypoint in the build that would go through and define each of the modules in the require.js AMD registry. There is already an [RFC that describes the fact that we want to deprecate this AMD registry](https://github.com/emberjs/rfcs/blob/strict-es-module-support/text/0938-strict-es-module-support.md), but the key thing for this RFC is that we are trying to think of our app as series of real ES Modules we need to provide some way for the built-in discovery of these modules that allows Ember to still resolve those modules by name (for Dependency Injection concerns like services) We are providing this with the virtual module `'@embroider/virtual/compat-modules';`. This means that any bundler plugin that wants to support Ember needs to be able to support virtual module imports. The contents of this file can be obtained by asking the Embroider resolver which collates the list of modules during the Ember prebuild. -We then pass the list of modules to an updated version of the Ember Resolver (that has already been released ) +We then pass the list of modules to an updated version of the Ember Resolver (that has already been released) which means that the Ember Resolver no longer needs to rely on requirejs.entries to find all of the parts of your application. This set of compat modules also needs to be passed into the `loadInitializers()` from `ember-load-initializers` so that doesn't use AMD for initalizer discovery either. Here is an example of the difference in the `app/app.js` file: -TODO add an example and keep describing +```diff + import Application from '@ember/application'; ++import compatModules from '@embroider/virtual/compat-modules'; + import Resolver from 'ember-resolver'; + import loadInitializers from 'ember-load-initializers'; + import config from 'current-blueprint/config/environment'; -TODO add a comment about eagerness with the compat module import + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; +- Resolver = Resolver; ++ Resolver = Resolver.withModules(compatModules); + } -### Application Config -> app/config/environment.js and config/environment.js +-loadInitializers(App, config.modulePrefix); ++loadInitializers(App, config.modulePrefix, compatModules); +``` -### Test Entrypoint -> tests/index.html and tests/test-helper.js +One very important thing to note is that because we're moving from AMD to real ESM modules we now have a timing change for any code that is executing in the module scope, this code will now be executed eagerly and will not wait until the module is actually consumed by your app. This change happens because AMD inherently lazily executes module code only when that module is consumed, and ES modules are inherently a static graph of modules. -### Explicit Babel Config -> babel.config.cjs +For the most part this change should not affect many people and most of the problems that we noticed related to this change came from addons that had code that had errors in it but was never cleaned up. It was never noticed before because the code was not being exercised by tests or consumers of the addons so most of the time the fix was to just delete the previously inert code. -### Ember Pre-Build Config -> ember-cli-build.js +### Application Config -> app/config/environment.js and config/environment.js -### Explicit Bundler Config -> vite.config.mjs +In a Classic build ember-cli automatically generated a module `app/config/environment.js` in your application build pipeline that is customisable with the config `storeConfigInMeta`. If `storeConfigInMeta` is true (which is the default) then the contents of this module will look for a `` tag in your html and parse out the your previously serialised config object and return the value as the default export from the module. This is what people recieve when they import from `app-name/config/environment`. +This is another example of an Ember-specific complexity in the build system that can be confusing for other build systems. In the new blueprint we propose making the `app/config/environment.js` file exist in your source, and the contents will clearly be loading the config from meta: +```js +import loadConfigFromMeta from '@embroider/config-meta-loader'; -How much of this should be "the path/migration to" as opposed to "this is the end state, details can be part of implementation"? - -1. start with embroider-strictest -2. all blueprint addons must be either in the v2 format, or non-addons entirely (such as qunit-dom's recent change to real `type=module` package) -3. use Vite with Embroider -4. remove unneeded dependencies - - ember-auto-import - - replaced by _the packager's_ own way of processing dependencies - (requires all consumed dependencies to _not_ be v1 addons) - - broccoli-asset-rev - - replaced by _the packager's_ production build mode - - ember-cli-babel - - replaced by actual babel - - ember-cli-clean-css - - replaced by _the packager's_ production build mode - - ember-cli-htmlbars - - replaced by [babel-plugin-ember-template-compilation](https://github.com/emberjs/babel-plugin-ember-template-compilation/) and embroider-provided build plugins - - ember-cli-inject-live-reload - - replaced by _the packager's_ development mode - - ember-cli-sri - - replaced by _the packager's_ production build mode - - ember-cli-terser - - replaced by _the packager's_ production build mode - - ember-fetch - - requires work in `@ember/test-helpers` and `ember-fetch` to make this smooth. - - ember-load-initializers - - tbd - - ember-resolver - - tbd - - loader.js - - require / AMD has been private for a long time, and folks should not be using it. - - -> This is the bulk of the RFC. - -> Explain the design in enough detail for somebody -familiar with the framework to understand, and for somebody familiar with the -implementation to implement. This should get into specifics and corner-cases, -and include examples of how the feature is used. Any new terminology should be -defined here. +export default loadConfigFromMeta('app-name'); +``` -## How we teach this +The serialising of the config into the index.html is still being handled by `{{content-for 'head'}}` and is not going to change as a result of this RFC. -> What names and terminology work best for these concepts and why? How is this -idea best presented? As a continuation of existing Ember patterns, or as a -wholly new one? +One restriction in the new blueprint is that we don't have an automatic implementation for when `storeConfigInMeta` is set to `false`. Our reasoning is that if you have set this setting then you are likely doing something custom and you would need to update `app/config/environment.js` to reflect your custom setup. We don't need to provide any customisation here because this is a user-owned module and you can edit it as you please. -> Would the acceptance of this proposal mean the Ember guides must be -re-organized or altered? Does it change how Ember is taught to new users -at any level? +### Test Entrypoint -> tests/index.html and tests/test-helper.js -> How should this feature be introduced and taught to existing Ember -users? +The `tests/index.html` will have the same treatment as the main `index.html` where the test boot code will now be exposed directly in an inline script so that test booting is not hidden deep in the build pipeline. -## Drawbacks +```html + +``` + +To facilitate this new API the test-helper needs to be changed to essentially "wrap" its contents in a function that can be called rather than it running as a side effect of the import: + +```diff + import Application from 'current-blueprint/app'; + import config from 'current-blueprint/config/environment'; + import * as QUnit from 'qunit'; + import { setApplication } from '@ember/test-helpers'; + import { setup } from 'qunit-dom'; +-import { start } from 'ember-qunit'; ++import { start as qunitStart } from 'ember-qunit'; + ++export function start() { + setApplication(Application.create(config.APP)); + setup(QUnit.assert); + +-start(); ++qunitStart(); + ++} +``` -> Why should we *not* do this? Please consider the impact on teaching Ember, -on the integration of this feature with other existing and planned features, -on the impact of the API churn on existing apps, etc. +This also allows us to load qunit, load all the test files, and then start qunit once all the tests are loaded. The loading of the test files is now also made explicit with the line: -> There are tradeoffs to choosing any path, please attempt to identify them here. +```js +import.meta.glob("./**/*.{js,gjs,gts}", { eager: true }); +``` + +`import.meta.glob` is described in detail in the [Introduce a Wildcard Module Import API RFC](https://rfcs.emberjs.com/id/0939-import-glob). It is natively supported in Vite but it would need to be implemented in any other build system that wants to support building an Ember app. -## Alternatives +### Explicit Babel Config -> babel.config.cjs -> What other designs have been considered? What is the impact of not doing this? +In a classic build ember-cli-babel manages all configurations to babel in a way that is entirely hidden to the end-user. This is nice considering that users don't need to manage this file themselves, but it is also problematic because if anyone wants to customise their babel config they need to rely on extension points provided by both ember-cli and ember-cli-babel and in some cases those extension points may not even be available e.g. it is currently impossible for an app to configure an ast-transform for the ember-template-compiler and people workaround this issue by creating an in-repo addon that does this configuration for them. + +In the new blueprint we will have an explicit `babel.config.cjs` that will come pre-configured with all the babel-plugins that ember-cli-babel would have configured for you. + +Here is the full contents of the proposed babel file: + +```js +const { + babelCompatSupport, + templateCompatSupport, +} = require('@embroider/compat/babel'); + +module.exports = { + plugins: [ + [ + 'babel-plugin-ember-template-compilation', + { + compilerPath: 'ember-source/dist/ember-template-compiler.js', + enableLegacyModules: [ + 'ember-cli-htmlbars', + 'ember-cli-htmlbars-inline-precompile', + 'htmlbars-inline-precompile', + ], + transforms: [...templateCompatSupport()], + }, + ], + [ + 'module:decorator-transforms', + { + runtime: { + import: require.resolve('decorator-transforms/runtime-esm'), + }, + }, + ], + [ + '@babel/plugin-transform-runtime', + { + absoluteRuntime: __dirname, + useESModules: true, + regenerator: false, + }, + ], + ...babelCompatSupport(), + ], + + generatorOpts: { + compact: false, + }, +}; +``` -> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. +You can see that there are two functions being imported from `@embroider/compat/babel`: `babelCompatSupport()` and `templateCompatSupport()`. This collects any extra babel config that is provided by any installed v1 ember-addon and makes sure that it still works with this new config. When an app no longer has any v1 ember-addons these functions can be removed but we will likely be leaving them in the default blueprint for the foreseeable future because they cost nothing if they are not being used. + +### Ember Pre-Build Config -> ember-cli-build.js + +To enable the current stable version of embroider you need to update your Ember Application in `ember-cli-build.js` in a `compatBuild()` function. That function took a plugin for your bundler and an optional config that allowed you to turn on each of the "static flags" of embroider one-by-one + +The "Inversion of Control" version of the blueprint will not use `compatBuild()` since the bundling is not controlled by ember-cli any more. We have implemented a new `prebuild()` function that only takes your Ember application and an optional config: + +```diff + 'use strict'; + + const EmberApp = require('ember-cli/lib/broccoli/ember-app'); ++const { prebuild } = require('@embroider/compat'); + + module.exports = function (defaults) { + const app = new EmberApp(defaults, { + // Add options here + }); + +- return app.toTree(); ++ return prebuild(app); + }; +``` + +Other than not accepting a bundler config as one of the options, the other change in this prebuild function is that **all the static flags are turned on by default**. Also some flags, like `staticEmberSource`, are forced to be on and will throw an error if you try to set them to false. + +### Explicit Bundler Config -> vite.config.mjs + +If you are using the current stable relase of Embroider then Embroider is generating a Webpack config for you automaically. It is possible for you to make some changes via config but the majority of the Webpack config file is hidden from you. + +This RFC proposes that we don't hide the bundler config any more, if you are using Webpack then you will have a Webpack config that will need to have an Embroider plugin configured. + +The blueprint will default to using Vite as a bundler but we will provide the option for Webpack to help people who have customised their Webpack builds by configuring Embroider to transition to the new blueprint format without needing to migrate to Vite. + +Here is the current version of the proposed vite config: + +```js +import { defineConfig } from 'vite'; +import { + resolver, + hbs, + scripts, + templateTag, + optimizeDeps, + compatPrebuild, + assets, + contentFor, +} from '@embroider/vite'; +import { babel } from '@rollup/plugin-babel'; + +const extensions = [ + '.mjs', + '.gjs', + '.js', + '.mts', + '.gts', + '.ts', + '.hbs', + '.json', +]; + +export default defineConfig(({ mode }) => { + return { + resolve: { + extensions, + }, + plugins: [ + hbs(), + templateTag(), + scripts(), + resolver(), + compatPrebuild(), + assets(), + contentFor(), + + babel({ + babelHelpers: 'runtime', + extensions, + }), + ], + optimizeDeps: optimizeDeps(), + server: { + port: 4200, + }, + build: { + outDir: 'dist', + rollupOptions: { + input: { + main: 'index.html', + ...(shouldBuildTests(mode) + ? { tests: 'tests/index.html' } + : undefined), + }, + }, + }, + }; +}); + +function shouldBuildTests(mode) { + return mode !== 'production' || process.env.FORCE_BUILD_TESTS; +} +``` + +## How we teach this + +All of the guides will need to be updated to make sure that we reference the build system correctly. We will also need to make sure that the system we use that automatically builds the tutorial for us can work with the new build system and blueprint. + +It will also probably be worthwhile getting Embroider API documentation added to https://api.emberjs.com/ as one of the listed projects on the left-hand side. + +## Drawbacks -In this section I'll +The only drawback I can see is that this is going to be quite a large change. ## Unresolved questions -### Application config +### Webpack examples -In the current design of the new build we are still using the node-generated config that all ember developers are used to. We have considered unifying the `config/environemnt.js` and `app/config/environment.js` files to reduce complexity in the learning story but +While developing the layout of this new blueprint we have been exclusively working with Vite so we don't have any examples of the "Inversion of Control" layout for a Webpack blueprint. We don't see this as a requirement for progressing with this RFC as we are relatively sure that we will be able to achieve the same layout and only have to swap out the Vite config for a Webpack config. From 822917ff622f4915957150874f271c7f92b8fe25 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Fri, 22 Nov 2024 18:11:30 +0000 Subject: [PATCH 64/66] add sections based on feedback --- text/0977-v2-app-format.md | 50 +++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md index 85c39b06b6..532324f189 100644 --- a/text/0977-v2-app-format.md +++ b/text/0977-v2-app-format.md @@ -52,6 +52,14 @@ Much like the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v Each of the following sections go into detail of all the changes between the current blueprint and the new proposal which is currently being developed at https://github.com/embroider-build/app-blueprint +### Removal of requirejs support + +The default build system that will be used in this new blueprint will be Vite and for the most part Vite requires that your app is described in terms of ES Modules. The default build from `ember-cli` would express all of your modules using AMD and requirejs `define()` statements. There is an open RFC for [Strict ES Module Support](https://github.com/emberjs/rfcs/pull/938) that removes Ember's reliance on AMD to define modules and that RFC would be a requirement for this one i.e. when building with Vite you essentially have no requirejs module support. This means that any addon or application that interacts with requirejs would need to be updated for people to upgrade to this new blueprint. + +### Top level await added + +Since we are now using ES Modules througout the whole application it now becomes possible to use [top-level-await](https://v8.dev/features/top-level-await) in the module-scope of any of your files. This opens up a lot of possibliites for Ember developers and is a great example of how adopting standards helps to bring improvments from the wider ecosystem to Ember developers. + ## Detailed design In this section I'm going to go through each of the changes in the new proposed blueprint, in each section I will do my best to explain the reasoning for why it needs to be like this but if you have any questions or comments please feel free to comment on the RFC and we will try to update that section. @@ -276,7 +284,7 @@ Other than not accepting a bundler config as one of the options, the other chang ### Explicit Bundler Config -> vite.config.mjs -If you are using the current stable relase of Embroider then Embroider is generating a Webpack config for you automaically. It is possible for you to make some changes via config but the majority of the Webpack config file is hidden from you. +If you are using the current stable release of Embroider then Embroider is generating a Webpack config for you automatically. It is possible for you to make some changes via config but the majority of the Webpack config file is hidden from you. This RFC proposes that we don't hide the bundler config any more, if you are using Webpack then you will have a Webpack config that will need to have an Embroider plugin configured. @@ -351,12 +359,48 @@ function shouldBuildTests(mode) { } ``` +### Application metadata -> package.json + +In the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format) we introduced the fact that the package.json `ember-addon` MetaData object should be versioned to identify which addons have been upgraded to the new spec. We will be reusing that concept for v2 apps by requiring the following section to be added to the package.json + +```json +{ + "ember-addon" { + "type": "app", + "version": 2 + } +} +``` + +This will opt Embroider into modern resolving rules so that it can interoperate properly with bundlers. + +### Exports -> package.json + +[Package Exports](https://webpack.js.org/guides/package-exports/) is an addition to the ESM resolving rules that all modern bundlers support. It allows you to configure paths that should be importable from ouside your package, as well as giving you a standard way to "redirect" imports that target your package. + +We already use these semantics in Ember applications when we expect `import SomeComponent from 'app-name/components/some-component'` to actually import the file path `/path/to/app-name/app/components/some-component.js`. In this example you can see that the `/app/` subpath has been added to the location. In ember-cli this semantic is handled in broccoli by actually rewriting paths, but this is one of the main reasons why tooling gets confused by our import paths because it's not using a standard method to define our import paths. + +The new blueprint will add the following exports section to the package.json by default: + +```json +{ + "./tests/*": "./tests/*", + "./*": "./app/*" +} +``` + +This essentially "redirects" all requests to modules in the `app` folder, with the exepction of any path that has `app-name/tests/` at the start. This means that importing your test helpers like `import superHelper from 'app-name/tests/helpers/super-helper'` won't try to import from the path `/path/to/app-name/app/tests/helpers/super-helper.js` + ## How we teach this All of the guides will need to be updated to make sure that we reference the build system correctly. We will also need to make sure that the system we use that automatically builds the tutorial for us can work with the new build system and blueprint. It will also probably be worthwhile getting Embroider API documentation added to https://api.emberjs.com/ as one of the listed projects on the left-hand side. +The majority of this RFC is written from the perspective of someone that is running `ember new` for the first time on a brand new app, but we will need to make sure to write both upgrade guides and appropriate codemods for anyone that is wanting to upgrade their apps from the old blueprints to this new default. We also need to put some consideration into the experience of people using [ember-cli-update](https://github.com/ember-cli/ember-cli-update) to upgrade Ember versions when we make this the new default. + +It's also important to note that this RFC does not represent the new bluerpint for a Polaris application. This is just upgrading our build system to use more modern and standard tools. Any communication around this RFC change should be explicit that this is a **part** of what is needed for Polaris but this blueprint update is not giving you all of polaris. This is a single step in that direction. + ## Drawbacks The only drawback I can see is that this is going to be quite a large change. @@ -366,3 +410,7 @@ The only drawback I can see is that this is going to be quite a large change. ### Webpack examples While developing the layout of this new blueprint we have been exclusively working with Vite so we don't have any examples of the "Inversion of Control" layout for a Webpack blueprint. We don't see this as a requirement for progressing with this RFC as we are relatively sure that we will be able to achieve the same layout and only have to swap out the Vite config for a Webpack config. + +### package.json meta key + +The way that Embroider is currently implemented the Ember MetaData in package.json is set with the key `ember-addon` even for applications. On the one hand it seems good that the applications and addons use the same key for this, but on the other hand it may be confusing that the key for the metadata has the word `addon` in it. We could move both addons and apps to just use the metadata key `ember` but that could create chrun with very little benefit. From 42195cf0f2abd31d2f7589f27fae192047465ed1 Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Sat, 7 Dec 2024 00:11:01 +0000 Subject: [PATCH 65/66] implement feedback into the RFC --- text/0977-v2-app-format.md | 101 ++++++++++++------------------------- 1 file changed, 32 insertions(+), 69 deletions(-) diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md index 532324f189..91a9b49061 100644 --- a/text/0977-v2-app-format.md +++ b/text/0977-v2-app-format.md @@ -40,9 +40,9 @@ and is designed to make Ember apps more compatible with the rest of the JavaScri When ember-cli was created there was no existing JS tooling that met the needs of the Ember Framework. Over the years we have added more and more developer-friendly conventions to our build system that many Ember applications and addons depend on. As the wider JavaScript tooling story has evolved over the years Ember has fallen behind, this is mainly because our custom-built tools have not been keeping up with the wider community and we haven’t been able to directly use any more advanced tooling in our apps. Efforts have been started to improve the situation with the advent of [Embroider](https://github.com/embroider-build/embroider) but the current stable release of Embroider still runs inside ember-cli and is somewhat bound in terms of performance and capability by the underlying technology [broccolijs](https://github.com/broccolijs/broccoli) and some other architectural decisions. -Over the past year the Ember Core Tooling team have been working hard to invert the control between bundlers and ember-cli, which means that instead of ember-cli running a bundler (such as Webpack) as part of its build system the whole Ember build process will essentially become a plugin to the bundler. This means that we can more effectively make use of bundler innovations, performance improvements, and we are more capable of adapting to whatever next generation of build systems come to the Javascript ecosystem. +Over the past year the Ember Core Tooling team have been working hard to invert the control between bundlers and ember-cli, which means that instead of ember-cli running a bundler (such as Webpack in the current Embroider stable version) as part of its build system the whole Ember build process will essentially become a plugin to the bundler. This means that we can more effectively make use of bundler innovations, performance improvements, and we are more capable of adapting to whatever next generation of build systems come to the Javascript ecosystem. -With the Ember build system as a plugin to bundlers (such as Vite or Webpack) we also have the ability to only intervene on things that are Emberisims (i.e. not-standard) and as we work to make Ember more standard we can eventually turn off these ”compatibility plugins”. Compatibility plugins will need to be powered by an “ember prebuild” that collects information about your app and addons and output metadata that the bundler plugins will consume. The intention is that this prebuild will be done automatically for you as part of the bundler plugin setup and you should not have to worry about preforming extra steps. +With the Ember build system as a plugin to bundlers we have the ability to only intervene on things that are Emberisims (i.e. not-standard) and as we work to make Ember more standard we can eventually turn off these ”compatibility plugins”. Compatibility plugins will need to be powered by an “ember prebuild” that collects information about your app and addons and output metadata that the bundler plugins will consume. The intention is that this prebuild will be done automatically for you as part of the bundler plugin setup and you should not have to worry about preforming extra steps. This RFC is not going to describe a new blueprint where you don't need any compatibility plugins (or an ember prebuild) to run an Ember app, this RFC instead is going to propose a new blueprint that has all the compatibility plugins turned on so that it is easiest for most people to upgrade to. Any discussion about a minimal “compatibility-free” blueprint should happen in a later RFC. @@ -52,13 +52,21 @@ Much like the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v Each of the following sections go into detail of all the changes between the current blueprint and the new proposal which is currently being developed at https://github.com/embroider-build/app-blueprint +### Focus on Vite + +The new app blueprint will default to using Vite to power local development and build for production. Vite has been on a meteoric rise in popularity over the past few years, and it represents the state of the art when it comes to Developer Ergonomics. Standardising on such a popular build system will bring the Ember community a lot of benefits but the key areas of improvement that we expect developers to experience are: + +- significantly improved rebuild speeds during local development +- the ability to use "standard" vite plugins with your Ember apps +- significant improvements to debugability of your code in development because Vite serves ES Modules directly to your browser in development + ### Removal of requirejs support The default build system that will be used in this new blueprint will be Vite and for the most part Vite requires that your app is described in terms of ES Modules. The default build from `ember-cli` would express all of your modules using AMD and requirejs `define()` statements. There is an open RFC for [Strict ES Module Support](https://github.com/emberjs/rfcs/pull/938) that removes Ember's reliance on AMD to define modules and that RFC would be a requirement for this one i.e. when building with Vite you essentially have no requirejs module support. This means that any addon or application that interacts with requirejs would need to be updated for people to upgrade to this new blueprint. ### Top level await added -Since we are now using ES Modules througout the whole application it now becomes possible to use [top-level-await](https://v8.dev/features/top-level-await) in the module-scope of any of your files. This opens up a lot of possibliites for Ember developers and is a great example of how adopting standards helps to bring improvments from the wider ecosystem to Ember developers. +Since we are now using ES Modules througout the whole application it now becomes possible to use [top-level-await](https://v8.dev/features/top-level-await) in the module-scope of any of your files. This opens up a lot of possibilities for Ember developers and is a great example of how adopting standards helps to bring improvements from the wider ecosystem to Ember developers. ## Detailed design @@ -258,6 +266,8 @@ module.exports = { You can see that there are two functions being imported from `@embroider/compat/babel`: `babelCompatSupport()` and `templateCompatSupport()`. This collects any extra babel config that is provided by any installed v1 ember-addon and makes sure that it still works with this new config. When an app no longer has any v1 ember-addons these functions can be removed but we will likely be leaving them in the default blueprint for the foreseeable future because they cost nothing if they are not being used. +For people who are familiar with Babel config files you may have noticed that we have not included `@babel/preset-env` in this config. While our browser support has classically been handled by babel and `@babel/preset-env`, Vite has a config option [`build.target`](https://vite.dev/config/build-options#build-target) that controls what browsers you would like to down-compile your code for. This `build.target` config is passed to esbuild which is ultimately in charge of making sure your code runs in your stated targets i.e. in your `config/targets` file. While we are still going to read your `config/targets` file and pass that to the `build.target` config, it's worth noting that esbuild does not support the same range of browsers that `@babel/preset-env` does. This isn't a problem for the default blueprint because it supports all browsers that are part of Ember's official support matrix. We also don't see this as a blocker for adoption of this new blueprint because any applications that have a wider browser support matrix than Vite's `build.target` can provide can just manually configure `@babel/preset-env` in their babel config, now that it's significantly easier to edit your babel config. + ### Ember Pre-Build Config -> ember-cli-build.js To enable the current stable version of embroider you need to update your Ember Application in `ember-cli-build.js` in a `compatBuild()` function. That function took a plugin for your bundler and an optional config that allowed you to turn on each of the "static flags" of embroider one-by-one @@ -286,79 +296,30 @@ Other than not accepting a bundler config as one of the options, the other chang If you are using the current stable release of Embroider then Embroider is generating a Webpack config for you automatically. It is possible for you to make some changes via config but the majority of the Webpack config file is hidden from you. -This RFC proposes that we don't hide the bundler config any more, if you are using Webpack then you will have a Webpack config that will need to have an Embroider plugin configured. - -The blueprint will default to using Vite as a bundler but we will provide the option for Webpack to help people who have customised their Webpack builds by configuring Embroider to transition to the new blueprint format without needing to migrate to Vite. +This RFC proposes that we don't hide the bundler config any more, we will instead have a standard Vite config file that configures the required Embroider plugins. Here is the current version of the proposed vite config: ```js import { defineConfig } from 'vite'; -import { - resolver, - hbs, - scripts, - templateTag, - optimizeDeps, - compatPrebuild, - assets, - contentFor, -} from '@embroider/vite'; +import { extensions, classicEmberSupport, ember } from '@embroider/vite'; import { babel } from '@rollup/plugin-babel'; -const extensions = [ - '.mjs', - '.gjs', - '.js', - '.mts', - '.gts', - '.ts', - '.hbs', - '.json', -]; - -export default defineConfig(({ mode }) => { - return { - resolve: { +export default defineConfig({ + plugins: [ + classicEmberSupport(), + ember(), + // extra plugins here + babel({ + babelHelpers: 'runtime', extensions, - }, - plugins: [ - hbs(), - templateTag(), - scripts(), - resolver(), - compatPrebuild(), - assets(), - contentFor(), - - babel({ - babelHelpers: 'runtime', - extensions, - }), - ], - optimizeDeps: optimizeDeps(), - server: { - port: 4200, - }, - build: { - outDir: 'dist', - rollupOptions: { - input: { - main: 'index.html', - ...(shouldBuildTests(mode) - ? { tests: 'tests/index.html' } - : undefined), - }, - }, - }, - }; + }), + ], }); - -function shouldBuildTests(mode) { - return mode !== 'production' || process.env.FORCE_BUILD_TESTS; -} ``` +This config is defining 2 "compound plugins" that contain all the functionality needed for an Ember app to be built with Vite. We have split them into `classicEmberSupport()` and `ember()` to communicate that some of the plugins could be considered optional if you aren't using classic Ember features e.g. you have converted all your templates to GJS files. + ### Application metadata -> package.json In the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format) we introduced the fact that the package.json `ember-addon` MetaData object should be versioned to identify which addons have been upgraded to the new spec. We will be reusing that concept for v2 apps by requiring the following section to be added to the package.json @@ -403,13 +364,15 @@ It's also important to note that this RFC does not represent the new bluerpint f ## Drawbacks -The only drawback I can see is that this is going to be quite a large change. +### Upgradability -## Unresolved questions +If developers are using ember-cli-update to upgrade their apps there might be a case where in an upcoming version of Ember they will be "opted in" to an Embroider build with Vite. We don't expect this process to be automatic but we do think that we can get most applications across this line with the use of tooling and codemods. One way to mitigate this problem is that we could maintain a "classic blueprint" until the next Ember major release that people could switch to while they are figuring out how to upgrade to Embroider and Vite. -### Webpack examples +### Webpack support -While developing the layout of this new blueprint we have been exclusively working with Vite so we don't have any examples of the "Inversion of Control" layout for a Webpack blueprint. We don't see this as a requirement for progressing with this RFC as we are relatively sure that we will be able to achieve the same layout and only have to swap out the Vite config for a Webpack config. +The blueprint will default to using Vite as a bundler, and we plan to document the process to add support for more bundlers as part of the implementation of this RFC. We had originally intended to provide support for Webpack as a bundler to help people who have already upgraded to the current stable Embroider version and customised their Webpack builds but Webpack support is not trivial to implement. The Ember Tooling Team believes that the benefits of having Vite as the default build experience are so great that we should not delay the implementation of this RFC while we try to backport the Inversion of control implementation of Embroider to Webpack. + +## Unresolved questions ### package.json meta key From fab41119776394da478e089cb75edad653ed810a Mon Sep 17 00:00:00 2001 From: Chris Manson Date: Tue, 10 Dec 2024 18:22:39 +0000 Subject: [PATCH 66/66] update ember-cli-build section --- text/0977-v2-app-format.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md index 91a9b49061..d865c35ad2 100644 --- a/text/0977-v2-app-format.md +++ b/text/0977-v2-app-format.md @@ -270,27 +270,27 @@ For people who are familiar with Babel config files you may have noticed that we ### Ember Pre-Build Config -> ember-cli-build.js -To enable the current stable version of embroider you need to update your Ember Application in `ember-cli-build.js` in a `compatBuild()` function. That function took a plugin for your bundler and an optional config that allowed you to turn on each of the "static flags" of embroider one-by-one +To enable the current stable version of embroider you need to wrap your Ember Application defined in `ember-cli-build.js` in a `compatBuild()` function. The `compatBuild()` function takes a plugin that runs your bundler (i.e. Webpack) as part of the ember-cli pipeline and an optional config that allows you to turn on each of the "static flags" of embroider one-by-one. -The "Inversion of Control" version of the blueprint will not use `compatBuild()` since the bundling is not controlled by ember-cli any more. We have implemented a new `prebuild()` function that only takes your Ember application and an optional config: +In the "Inversion of Control" version of the blueprint we intend to keep the same `compatBuild()` API but the job of the builder will be very different. Instead of Vite running as part of the ember-cli pipeline we are only running a prebuild that collects information about your application and its addons to make that available to the Embroider Vite plugin. When running directly in Vite the builder argument to `compatBuild()` will be inert and will do nothing. + +To continue to support commands like `ember build` or `ember test` we need some way for ember-cli to interact with Vite and allow Vite to build the application and run tests against the built output. Running `ember test` will essentially run Vite once (as a "one shot build" with no watching functionality) using the builder imported from `@embroider/vite` and then run `ember test --path {outdir}` where `{outdir}` will target the build output from Vite. This allows us to continue to support testem and any CI process that people have defined to use `ember build` without needing to update. Here is an example of an updated `ember-cli-build.js` file: ```diff - 'use strict'; - const EmberApp = require('ember-cli/lib/broccoli/ember-app'); -+const { prebuild } = require('@embroider/compat'); - ++const { compatBuild } = require('@embroider/compat'); ++const { builder } = require('@embroider/vite'); + module.exports = function (defaults) { - const app = new EmberApp(defaults, { - // Add options here - }); - + let app = new EmberApp(defaults, {}); - return app.toTree(); -+ return prebuild(app); ++ return compatBuild(app, builder, { /* optional Embroider options */ }); }; ``` -Other than not accepting a bundler config as one of the options, the other change in this prebuild function is that **all the static flags are turned on by default**. Also some flags, like `staticEmberSource`, are forced to be on and will throw an error if you try to set them to false. +The other change that will happen in the next Embroider major release (and will be true for the new blueprint) is that the options passed to `compatBuild()` will have **all the static flags turned on by default**. + +Also some flags, like `staticEmberSource`, `staticAddonTrees`, and `staticAddonTestSuportTrees` are forced to be on and will throw an error if you try to set them to false. This error will give guidance wherever possible and link to relevant documentation. ### Explicit Bundler Config -> vite.config.mjs