How should conversion to promise-based be structured?

[jpmedley]

As illustrated by PR #4404, a fair number of API functions have been converted to return promises instead of data. It seems like this should be reflected in the structure of the BCD rather than in a note.

[Elchi3]

Sounds like another case for which we want a data guideline. We are documenting these in #4467

[jpmedley]

So api/Elements.json has a substructure called "returns_a_promise" with its own compatibility tree. If we ever discussed doing it this way, I can't find the conversation. Regardless, it seems like we should make it part of its parent compatibility array. (In other words, another entry in a structure like this.)

[ddbeck]

What's the story for these converted-to-return promise functions? Did they previously take a callback parameter, but now they return promises (and the spec changed to reflect that)?

@jpmedley Are you suggesting something like this?

            "chrome": [
              {
                "version_added": "35",
                "notes": "Returns a promise."
              },
              {
                "version_added": "25",
                "version_removed": "35",
              }
            ]

[jpmedley]

Some did take callbacks. Some didn't. Generally, it should be assumed to be because of a spec change. Our internal development policy is to never go around or thwart the standards process. I won't say it can never happen.

The structure you've suggested looks good to me.

[ddbeck]

OK, yeah, I think the right thing to do changes in specified behavior is to break the continuity of the support statements, when the change in behavior itself is not obviously backwards compatible. I wouldn't suggest this route for something like a required function parameter becoming optional, for example.

For completeness, I suppose the alternatives might be subfeatures: either one for the new specified behavior (like returns_a_promise) or one that's deprecated showing support for the old spec (e.g., uses_a_callback or whatever). Both of these options seem pretty heavyweight and would have the tendency of hiding essential information about the behavior of an API in a subfeature, at least in the case of promises.

[jpmedley]

Your heuristics seem right. I'm unclear on whether you agree with me that returning a promise belongs on the main level.

To be fair, a method that formerly returned void doesn't meat your standard. Unfortunately, a method that formerly returned an object does. I propose we leave this open for a while and see if we can find one of the latter.

[ddbeck]

I'm unclear on whether you agree with me that returning a promise belongs on the main level.

Sorry, yes, I agree with you that it's relevant to the main feature.

And yeah, I think you're right, we should keep an eye out for more promisifications (sorry) and make sure we're on the right track before doing anything just yet.

This also spares me from adding to #4467 right away 😃

[queengooborg]

We've added a guideline for this in #11630 -- see https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines.md#methods-returning-promises-returns_promise. I think we can close this issue accordingly.