Make deprecation workflow built in

[NullVoxPopuli]

Propose making deprecation-workflow built in.

Rendered

Summary

This pull request is proposing a new RFC.

To succeed, it will need to pass into the Exploring Stage), followed by the Accepted Stage.

A Proposed or Exploring RFC may also move to the Closed Stage if it is withdrawn by the author or if it is rejected by the Ember team. This requires an "FCP to Close" period.

An FCP is required before merging this PR to advance to Accepted.

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

Exploring Stage Description

This stage is entered when the Ember team believes the concept described in the RFC should be pursued, but the RFC may still need some more work, discussion, answers to open questions, and/or a champion before it can move to the next stage.

An RFC is moved into Exploring with consensus of the relevant teams. The relevant team expects to spend time helping to refine the proposal. The RFC remains a PR and will have an Exploring label applied.

An Exploring RFC that is successfully completed can move to Accepted with an FCP is required as in the existing process. It may also be moved to Closed with an FCP.

Accepted Stage Description

To move into the "accepted stage" the RFC must have complete prose and have successfully passed through an "FCP to Accept" period in which the community has weighed in and consensus has been achieved on the direction. The relevant teams believe that the proposal is well-specified and ready for implementation. The RFC has a champion within one of the relevant teams.

If there are unanswered questions, we have outlined them and expect that they will be answered before Ready for Release.

When the RFC is accepted, the PR will be merged, and automation will open a new PR to move the RFC to the Ready for Release stage. That PR should be used to track implementation progress and gain consensus to move to the next stage.

Checklist to move to Exploring

• The team believes the concepts described in the RFC should be pursued.
• The label S-Proposed is removed from the PR and the label S-Exploring is added.
• The Ember team is willing to work on the proposal to get it to Accepted

Checklist to move to Accepted

• This PR has had the Final Comment Period label has been added to start the FCP
• The RFC is announced in #news-and-announcements in the Ember Discord.
• The RFC has complete prose, is well-specified and ready for implementation.
  • All sections of the RFC are filled out.
  • Any unanswered questions are outlined and expected to be answered before Ready for Release.
  • "How we teach this?" is sufficiently filled out.
• The RFC has a champion within one of the relevant teams.
• The RFC has consensus after the FCP period.

[MrChocolatine]

How and how to?
Perhaps "when and how to"?

[NullVoxPopuli]

The Question:

• do we want to bring in the ember-cli-deprecation-workflow addon?
• or build the entire addon's functionality in to ember-source (behavior / usage would be unchanged)

It's possible we can do the first, and then the second, but the addon isn't very big (it's just one file, basically)

[geoffreyd]

This is something I'm surprised has t happened sooner. From what I've seen, you kinda had to be 'in the know' to use deprecation-workflow, and it wasn't clear that it was the recommended upgrade approach, at least for those who weren't around during its early days.

+1 for baking it in. Or at least having an ember-cli command that installs it.

[achambers]

RFC Review (1) are in favour of this.

[kategengler]

deprecate calls from ember in production are stripped as part of Ember's build, not the project's, so there would be no way to keep them in production, right now

[kategengler]

Whether in deprecation-workflow or in a new implementation, I think we should also capture options.url and options.for. The other options.since I feel less strongly about but may be nice.

[kategengler]

I'm in favor of this option. While it may not be much code, adding the addon is a quick path.

[ef4]

We discussed this today and people were in favor of swapping the design around to the "just use the existing addon in the default blueprint" because it would be a quick win. We can still do the alternative of building it into ember later.

[apellerano-pw]

I view ember-cli-deprecation-workflow as a criticism of Ember's existing deprecation approach. I think the Addon treats downstream symptoms in Ember itself and doesn't address the root cause. The best question for Ember to ask itself is why do so many people want to silence what is supposed to be a helpful message?

Root causes:

1. Ember deprecation warnings are incredibly verbose, both in their message size and stack trace length. They quickly overwhelm the console which can lead to DevTools performance issues and make CI/CD systems more difficult to use.
2. Ember deprecations appear suddenly. Consider the amount of deprecations added in 1.13, or across the 3.26-3.28 range. You could bump from one LTS to another and take on thousands of warnings overnight.

It's arguable that (2) is now addressed, as both Ember 4.x and 5.x have not created a deprecation deluge. But it's hard to tell if this is intrinsic to the "major version release timeline" changes, or a coincidence from the shrinkage in Ember's maintainership structure the past few years. Were Polaris to solidify in the next 72 weeks, would Ember 6.x contain another large wave of deprecations, to facilitate Ember 7.x removing support for an older Edition? I don't see why not.

One of Ember's strengths is its "batteries-included" nature, and I think that term should only apply when the functionality is provided by ember-source. This is taken into account by the original proposal, but not the blueprint shortcut approach. As the list of packages grows in the Ember project blueprint, it starts to look more and more like competitors' frameworks. But again, I would argue if you're going for a built-in solution, why not address the root causes? The 'usefulness' of ember-cli-deprecation-workflow is not something the framework should be proud of.

In addition, using ember-cli-deprecation-workflow makes Ember upgrades more tedious. After you complete an upgrade, you have to reconfigure your deprecation workflow config so it starts swallowing the new deprecations you just upgraded into. Ember already has a problem getting developers to upgrade, so anything that makes that pole longer should be scrutinized.

Lastly it complicates the onboarding story. This package provides no immediate value to a new learner. When scanning the boilerplate they need to additionally learn to ignore ember-cli-deprecation-workflow's presence. When they do finally need it, what time is really saved for them? All they need to type is ember install ember-cli-deprecation-workflow to catch up.

All this is to say that adding ember-cli-deprecation-workflow to the blueprint doesn't bring value or address root concerns about Ember. All the while increasing both the maintenance burden of the core team as well as the complexity of the framework.

[kategengler]

@apellerano-pw 👋 ember-cli-deprecation-workflow is part of Ember's approach to deprecations. It was created by core team members and is maintained by core team members.

I agree that it was a problem in the 3.x era where many projects silenced every deprecation for the three years of 3.x releases. Projects that chose to do so were left with many deprecations to deal with to reach 4.0. We hope we've addressed this with the new Major Version release cadence policy. Under this policy, a major lasts about 18 months. Deprecations targeting the next major must land within the first 60 weeks of major version (before the x.10). By having less time for deprecations to land, there should be fewer for a particular major version. Contributors are also well aware of the pain of 1.13 and 3.28 and we keep that in mind when accepting and implementing deprecation RFCs.

All deprecations need to be RFC'd. Deprecation RFCs go through all the RFC stages. It isn't a small effort to land a deprecation Ember. For example, In the lead up to 5.10, we hoped to land the deprecation of import Ember from 'ember', but we realized there were too many things in the ecosystem that would need to be updated. We also have tooling planned for "enabling" deprecations in advance of them being enabled by default (under a simplification of the Deprecation Staging RFC).

ember-cli-deprecation-workflow is useful beyond just silencing deprecations and ignoring them for an entire major version: I often use it as a tool to work through deprecations one-by-one (silencing all but one, dealing with it, and moving on).

The messages that go with Ember deprecations strive to have enough detail that they are actionable. They also link out to a deprecation guide. The stack enables the user to find the origin of the deprecation.

It may be annoying to need to update the deprecation workflow upon upgrade, but I don't see an alternative. We cannot hide deprecations on upgrade -- that would have the same problems as silencing them and ignoring them. We cannot avoid adding all deprecations if we want to move this framework forward.

Adding the addon to the blueprint was deemed to be less work for maintainers than building it in directly while also achieving the goal of making the addon more widely known and building it into the guides.

[apellerano-pw]

I think the most pressing question still unanswered is what is the upside of including ember-cli-deprecation-workflow in the blueprint? What use cases does it enhance above and beyond people reading the existing documentation?

Given that there are downsides to including it:

• Boilerplate Ember app is now more complicated, distracting new learners from Ember's core functionality
• Maintenance burden rises, as bugs or incompatibilities in this other package can now become blockers to ember-source releases.

Another approach could be to improve the existing documentation, in terms of quality or discoverability. Although I think the documentation is good already, and only a couple of clicks away from the Ember guide homepage.

If the cost to internalize a deprecation workflow is too high, I think the next strongest option is to do nothing.

[NullVoxPopuli]

I mean, I'm happy to "just" implement all of this in ember-source.
The commitment to compatibility that inclusion in ember-source signals is unparalleled.

There may be some goofiness that might need to happen with build time behavior with complicates things -- but it's probably better to work through it.

does it enhance above and beyond people reading the existing documentation?

there is overwhelming evidence that the average person doesn't read or glosses over messages in the console.

the deprecation-workflow (regardless of where it lives), provides a way for folks-who-pay-attention to minimize console spew for those who easily gloss over the messages.

[acorncom]

Regarding the question "what is the upside of including ember-cli-deprecation-workflow in the blueprint?"

Cons stated above

• maintenance burden rises
• yet another package in the package.json file / blueprints get larger

Of these two, the maintenance burden comment isn't that great and as a community I think we've been content with it so far (happy to have someone correct me on that). package.json continuing to expand is a reasonable criticism, there has been discussion of adding a meta package for Ember at some point, is that something we think we'd realistically want to do down the road?

But a few thoughts on the pros side of things (coming from a teaching background / former Learning Team member perspective):

• adding the package as a default to the blueprint allows folks to skim the package.json and think "hmm, what is that?". Think of it as another possible way of learning how an Ember app functions. Some folks do indeed read the guides from top to bottom, but I continue to be amazed watching other folks just jump in and learn piecemeal as they need
• keeping the workflow process out as a separate add-on gives devs interested in a deeper understanding of how things work an entry point into a piece of the system they might want to access/adjust

The latter pro is one I find an interesting counter-argument to the "let's just bake this into the framework". Under the hood, ember-cli-deprecation-workflow relies heavily on the use of registerDeprecationHandler. If I'm a developer interested in hooking into that behavior / adjusting it myself, the existence of that function is fascinating to know about and provides an immediate entry point into what I might want to do in some other way (including hooking up reporting to internal corporate dashboards).

If we bake the functionality in all the way to the framework, I think we make that single method quite a bit harder to find. Does it still exist in Ember source? You bet. Is it still documented in the api docs? Of course. But most folks I've mentored / taught Ember over the last 10 years might feel comfortable poking around an add-on that does approximately what they want, but often haven't ever dived into reading ember-source.

To me, Ember's addon ecosystem (past and future) provides a useful set of real-world examples of the breadth of high-to-low-level apis that actually do exist under the hood that allow a myriad of interesting capabilities.

Whether we choose to bake this particular one into the framework is less material to me, but I think we'd be ill-served to bake a bunch of our core-addons into the framework. Having our lower-level plumbing apis exposed and tested by these addons still seems quite useful.