RFC: Deprecated vs. Obsolete

Elchi3 commented 7 years ago

We have a few definitions for the terms obsolete and deprecated.

MDN definition for obsolete

On MDN, the term obsolete marks an API or technology that is not only no longer recommended, but also no longer implemented in the browser. [...] For Web standard technology, the API or feature is no longer supported by current, commonly-used browsers. MDN reference

MDN definition for deprecated

On MDN, the term deprecated marks an API or technology that is no longer recommended, but is still implemented and may still work. These technologies will in theory eventually become obsolete and be removed, so you should stop using them. [...] For Web standard technology, the API or feature has been removed or replaced in a recent version of the defining standard. MDN reference

Current BCD definition for obsolete

A boolean value that indicates if the functionality is only kept for compatibility purpose and shouldn't be used anymore. It may be removed from the Web platform in the future. BCD reference

Currently, BCD does not have the term deprecated in the status object.

Request for comments: Should we rename obsolete to deprecated in BCD?

In BCD, version_added and version_removed indicate support ranges and whether support has ended.

I think it isn't necessary to also have "no longer implemented in the browser" as a meaning for obsolete. The current BCD definition for obsolete also doesn't mention this, it is only in the historical MDN meaning, but people get confused by these two definitions.

Further, on MDN, the deprecated meaning includes "is still implemented and may still work". I think in BCD we shouldn't have this as an implicit meaning of deprecated as we have version_added and version_removed for when something is supported or not.

Probably deprecated is the more common term for indicating the recommendation status ("do not use this anymore", "it's no longer recommended", "the spec discourages this", etc). So, I think we should use deprecated instead of obsolete. A definition for deprecated in BCD could be:

A boolean value that indicates if the feature is no longer recommended. It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.

On the Web platform, features are rarely ever removed, because the Web needs to be compatible. For WebExtensions, or other APIs, where deprecated features might actually be removed, I think that deprecated is still a good term, too, as we're not mixing implementation status and recommendation status in our definition.

Motivation

I thought it would be nice to answer why we are thinking about this anyway why it isn't entirely bikeshedding (but somewhat bikeshedding). So here is my take:

Fundamentally, I think BCD should have well defined answers to the two questions "Can I use this?" and "Should I use this?".

For "Can I use this?" (is it possible, how and when?), the support object including version_added and version_removed and caveats like flags, alternative names etc. give you answers.
For "Should I use this?" (is it recommended?), the status object should give you answers.
- if you only want to use non-experimental features, the experimental boolean should be false for you
- if you only want to use web standard features, thestandard_track boolean should be true for you
- if you only want to use features that aren't discouraged to be used (either because the feature is only available still for compat reasons, or is planned to be removed), the deprecated boolean should be false for you.

chrisdavidmills commented 7 years ago

I really like the new definition, and support these thoughts.

One nitpick - in the definition, "purpose" -> "purposes"

I'd like to take this slightly further and remove "obsolete" from MDN altogether. It's kind of a standards thing that you don't see much any more, and it's confusing. So why don't we just get rid of it?

OR. We could replace it with "removed". That's much more obvious and less confusing.

The states we are concerned with would then be:

"Implemented" — it's implemented across browsers. You can use this.
"Non-standard" — it's not a standard. Be careful.
"Experimental" — it's implemented in a few places, but not everywhere, and it's subject to change. Be careful.
"Deprecated" — it's removed from the specs but still available in browsers in a few places (but could be removed at any time). Be very careful.
"Removed" — it's removed from the specs and browsers. You can't use it.

Your above answer definitions seem to nicely cover these cases, and appropriate combinations of them. I'm assuming that removed features are just deleted from the BCD altogether?

snoack commented 7 years ago

I agree that the differentiation between obsolete and deprecated is redundant since there is version_removed. Furthermore, this abstraction is inconsistent, as status is per per feature (not per browser). So if a deprecated feature has only be removed in some browsers, it's ambiguous whether it should be considered obsolete or deprecated. So it seems to make more sense to merge these two statuses, and have version_removed (which is per browser) indicate the feature's browser support.

wbamberg commented 7 years ago

This all makes sense to me.

In general, we should avoid including things like "some browsers might not support this" in any definition of terms like experimental and deprecated, because the details compat data should describe the current state of support.

Where terms like deprecated are useful is where they give some indication of the future: web developers should care about the future as well as the present, and the detailed compat data can't tell them this. So knowing that future runtimes are (more) likely to drop support for a feature is good information.

I like your definition of "deprecated", and would support using it as the MDN definition as well as the BCD one, and would also support removing "obsolete", as Chris suggested.

snoack commented 7 years ago

Where terms like deprecated are useful is where they give some indication of the future

Doesn't that apply as well to experimental, as semantics and availability of experimental features are matter to change in the future? For example look at flexbox, where the syntax changed 2 times while it was experimental technology, before we ended up with the final standard. In other instances experimental features got completely removed from the standard and implementations later.

wbamberg commented 7 years ago

Yes, it absolutely does apply to experimental as well.

a2sheppy commented 7 years ago

I concur that the term "deprecated" should be used to essentially mean (in simple terms) "no longer considered accepted practice" or something like that, and that "obsolete" isn't needed thanks to the version added and removed information provided by BCD.

I think the two terms stem from a time when we focused primarily on Firefox, so "deprecated" meant "planned for removal from Firefox" and "obsolete" meant "removed from Firefox."

jpmedley commented 7 years ago

I don't think it affects what you're doing, but you all should know that Chrome uses deprecation as a preamble to removal. https://developers.google.com/web/updates/2017/06/chrome-60-deprecations#deprecation_policy

Joe Medley | Technical Writer, Chrome DevRel | jmedley@google.com | 816-678-7195 If an API's not documented it doesn't exist.

On Thu, Jun 22, 2017 at 8:43 AM, Eric Shepherd notifications@github.com wrote:

I concur that the term "deprecated" should be used to essentially mean (in simple terms) "no longer considered accepted practice" or something like that, and that "obsolete" isn't needed thanks to the version added and removed information provided by BCD.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/mdn/browser-compat-data/issues/265#issuecomment-310419672, or mute the thread https://github.com/notifications/unsubscribe-auth/AH0vi1qJeDEVkOUZamG19dkdM211JP2Wks5sGoufgaJpZM4OAt82 .

Elchi3 commented 7 years ago

Thanks all! It's really valuable to get these terms and policy sorted out after all.

For BCD, we've made the suggested change in #268.

For MDN, I'll open a thread in our discourse forum to make more people aware of this and we'll change MDN's usage policy of "obsolete" and "deprecated" depending on the outcome of that thread. Several here have suggested to use the definition we agreed here on MDN as well, so lets see!

Thanks again!

a2sheppy commented 7 years ago

@Elchi3 -- Did that thread get started? If so, adding a link here might be helpful.

I ask because this is something I may want to address on pages I touch with the SEO project work, since I need to move deprecated stuff aside in certain places and that kind of thing. Might be helpful to have this decision made and finalized. I posted about this on Discourse here: https://discourse.mozilla.org/t/deprecated-obsolete/19098/5 (while trying to get a feel for how to proceed on these article updates I'm doing for SEO).

Elchi3 commented 7 years ago

@a2sheppy Looks like I forgot about this. We can use your thread to make a call. I think BCD's terms make sense for MDN overall.

a2sheppy commented 7 years ago

I agree. Let’s go with “deprecated” and deprecate “obsolete.” :)

Eric Shepherd Senior Technical Writer, MDN MDN: https://developer.mozilla.org/ Blog: https://www.bitstampede.com/

On September 14, 2017 at 5:55:27 AM, Florian Scholz ( notifications@github.com) wrote:

@a2sheppy https://github.com/a2sheppy Looks like I forgot about this. We can use your thread to make a call. I think BCD's terms make sense for MDN overall.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/mdn/browser-compat-data/issues/265#issuecomment-329433720, or mute the thread https://github.com/notifications/unsubscribe-auth/ABkL31onc8tO_6uIHKZ0XNxLp-sdVEObks5siPgLgaJpZM4OAt82 .

mdn / browser-compat-data