Framework deprecations and userland deprecations

[eccegordo]

You should really strive to make a distinction between deprecations caused by code written by the user or in the app vs code that exists in the framework, addon, or external library such as Ember Data.

Otherwise it is a lot of noise with no clear call to action for the user.

For example:

Take this ember data deprecation:

DEPRECATION: The default behavior of shouldBackgroundReloadAll will change in Ember Data 2.0 to always return false when there is at least one "product-relation" record in the store. If you would like to preserve the current behavior please override shouldReloadAll in you adapter:application and return true.

Good to know, but not something I can directly act upon unless I want to monkey patch Ember Data.

Also, the user experience around deprecation notices on the website is quite confusing.

This page

http://emberjs.com/deprecations/v1.x/

Has no prominent reference. It is like one of those open secrets. But only the insiders know about it. Very hostile to new comers.

Second, the above very useful page is totally divorced from the guides.

Why is there a separate deprecations page here

http://guides.emberjs.com/v1.10.0/deprecations/

And yet none of the other guides have any obvious deprecations navigation.

[mixonic]

Also, the user experience around deprecation notices on the website is quite confusing.

This page

http://emberjs.com/deprecations/v1.x/

Has no prominent reference. It is like one of those open secrets. But only the insiders know about it. Very hostile to new comers.

This page is heavily referenced:

• Many deprecations link directly to the suggest resolution at that URL
• The Ember Inspector links to those same links from the deprecations tab
• The release blog posts link to that page where appropriate for deprecations

Second, the above very useful page is totally divorced from the guides.

Why is there a separate deprecations page here

http://guides.emberjs.com/v1.10.0/deprecations/

And yet none of the other guides have any obvious deprecations navigation.

This is a legacy guide page from the old website. @trek are you +1 to the idea of adding a disclaimer at the top linking to the active URL?

[eccegordo]

Yeah, currently ember inspector is broken for me. Might be something in my app so I am having to use console log output to see deprecations. And can not find the link. Only seems to show up when I boot ember cli and I don't see all deprecation notices their either, like the above.

Also, I would expect to see note about deprecations in the guides so just a link in the side bar that routes back to the main deprecations page would be helpful.

Anyway, upgrade to 1.13 is going relatively smoothly. Good work all around.

[eccegordo]

Here is another not so obvious deprecation notice.

And no link in the console output

[eccegordo]

Here is the problem I am having with ember inspector. I will go file an issue over there.

I believe the problem is that exceptions are being thrown because of bugs in my project. Perhaps it would be useful to have ember inspector have a mode that would temporarily swallow exceptions to get around this particular corner case and review the deprecations.

[rwjblue]

That last error is almost certainly the same thing as #11490. Thanks for reporting in inspector repo.

[eccegordo]

I should clarify on that ember data deprecation. After reading it more closely, the obvious fix is override the shouldReloadAll method in an adapter. That silences the warning in the console.

But I am just wondering if that makes sense. Not even really sure which behavior I would ultimately want, current default or new ember data 2.0 behavior.

I understand why the warning is there. You don't want to catch people off guard when ED changes. But this particular case it seems pretty esoteric.

My desire is to acknowledge the change and hide the deprecation without actually having to add code in userland inside an adapter.

I would personally see this as a "framework" level change. Kind lot of like saying:

Hey we have changed something deep in the framework, your code isn't directly violating this deprecation but we are going to keep the warning here until you upgrade the framework.

The call to action is ambiguous. I am wondering if in the future it makes sense to have some concept of log level for the deprecations, or categories (P1, P2, P3, etc).

That way I could selectively enable or disable certain deprecation notices. Deal with the highly mechanical deprecations first and then deal with the more subtle framework level changes secondly.

This could also dovetail well with the LTS release plans and you could start to classify the deprecations according to their urgency or severity.

Perhaps something like:

PRIVATE    --> Your code uses private API and is subject to change, don't say we didn't warn you
URGENT     --> Your code directly uses API that is being removed next release
IMPORTANT  --> Framework change, or your code relies on API behavior that will change eventually in long term support release
SUGGESTION --> Your code triggers legacy feature or is suboptimal for performance, no change immediately required but you might want to look into it.

[wycats]

@eccegordo thanks so much for the detailed descriptions of your thoughts as you encounter these errors. It will definitely help us to improve both the process for reporting these errors and the errors themselves next time around.

[eccegordo]

@wycats no problem. Overall the upgrade process is going relatively smoothly. I just like to deeply understand the reasons behind a change and make sure I am not just performing cargo cult in my code.

Overall all though I am deeply impressed by the glimmer updates and a lot of the other refinements. A lot of things much faster. Great job everybody for keeping to the announced schedule.

Bright days ahead for sure.

[typeoneerror]

I added a link from the releases page while I was fixing up the CSS for the site a few weeks ago. Happy to add more references if needed. It think the deprecations are obvious if you're a current Ember dev who reads every release blog, but for the new dev, not so clear. emberjs/website#2219

[mixonic]

I think there have been several things that address this issue:

• Some deprecation messages have been improved through the 1.13.x releases
• Some warnings (like they key= one) have been removed
• We've pushed through an RFC exposing an API for customizing deprecation and warning handling. It still needs implementation but it is moving forward. @rwjblue has plans for a backwards compatible addon supporting the proposed API.
• There is a fresh explanation on deprecations and link to the page from builds.

I'm going to close this, but let me know if I've missed anything essential.