JerryScript API maintenance (removal, experimental)

[zherczeg]

Recent changes in the API revealed that we have no strict policy for removing API or introducing experimental API. It would be good to have some policy rules for that. My suggestions:

Deprecating an API: we already have a JERRY_DEPRECATED_API define and we should add this to deprecated functions. After the label is added the function will be removed 4 months later.

Experimental API: we should add a prefix to these functions (e.g. jerry_new_, jerry_exp_) and these functions can be changed without further notice. Use them at your own risk. For example I would add this prefix to all debugger functions now, and could be used for providing an API for snapshot merging.

[akosthekiss]

My two cents:

Deprecation usually works well if you have some kind of releases. Especially if you have a well-defined release versioning scheme, where you and your users know exactly what to expect, what may and what may not change between various versions. Like in semver, where you know that an API breaking change (like the removal of an API function) may only change on major version increments. Calendar-timed deprecation without releases is a bit strange to me. (IMHO, it will be hard to keep the timing. And if we don't keep it strict, why to set it as a policy?)

As for experimental API, I'm not sure that prefixing functions is the best way. That would cause a name change when an experimental function becomes stable. Which could require updates by engine users too often. An alternative might be to have a dedicated header, like jerryscript-experimental.h, which contains all experimental declarations and IS NOT included by the main jerryscript.h. If an engine user is happy to take the risks and use bleeding edge, s/he has to explicitly include the experimental header, too. If a user includes jerryscript.h only, then s/he has access to the stable API only. And changing a function from experimental to stable means moving the declaration from jerryscript-experimental.h to jerryscript.h.

I think that when we talk about deprecation/stabilization/experimental APIs, we cannot avoid talking about release models, versioning, and stability guarantees. (Semver is already mentioned, but that's not the only possibility.) The "responsible developer me" and the "lazy developer me" are struggling right now. From library user perspective, it is a sane expectation to have a reliable API that does not require a lot of maintenance as the library evolves. From the engine's developer perspective, it is sometimes quite a burden to stick to some legacy API. And since this project has minimal binary size among its goals, it is more that just laziness to remove old API as soon as possible.

I would not be completely against a periodic release scheme (releases every month, quarter, 6 months, or ...):

• we would have releases (which we practically don't have right now),
• we could have release-tied deprecation (e.g., if a function is marked as deprecated in a release then it may be removed in the next),
• therefore legacy API could vanish from binary quite fast,
• but users would still have some kind of stability guarantees (or, at least, could point at a given release name/number what is known to work for them).

IMO this would suite the JerryScript project better than semver, because based on its history, we would quickly either increase major version only because of breaking changes (or would produce releases very rarely to avoid that).

[LaszloLango]

An alternative might be to have a dedicated header, like jerryscript-experimental.h, which contains all experimental declarations and IS NOT included by the main jerryscript.h.

I can accept this.

I think that when we talk about deprecation/stabilization/experimental APIs, we cannot avoid talking about release models, versioning, and stability guarantees.

I highly agree with you. Periodic releases in every 6 months sounds good to me.

[martijnthe]

Re. release + versioning: I would be in favor of adopting adopting semver to indicate API changes (including ABI/bytecode changes). Experimental APIs would not be counted, unless they change an existing API / change bytecode version. I'd also be in favor of "rolling releases". Why not version/tag it, say every two weeks or so? Re. stability guarantees, I think the current development process is already tuned to make master pretty stable from a bug point of view (jerry-core at least). The one "achilles heel" that comes to mind though are the ports. Because there's no automated builds / testing there, it's hard to make stability claims about them without investing time into testing QA'ing them (either manually or automatically).

Re. "experimental API": I like this concept. It enables us to get broader feedback on the APIs before (which usually does not happen in the design nor implementation phases, but only after a change has landed...) and to improve and iterate on the design "in the wild".
I don't like the idea of a _experimental symbol/type name pre/post-fix. Because if the API design does not change, people still need to update their projects when the pre/post-fix is dropped.
I also don't like the idea of putting them into a special header. It will make it harder for people to discover and use the new APIs. Also, people potentially need make meaningless changes to their project when the API is moved from the experimental header to another one.

How about adding an warning that can be opted-out, i.e. something like:

#ifndef JERRY_DISABLE_WARN_EXPERIMENTAL
#  define JERRY_EXPERIMENTAL __attribute__((warning("This API is experimental. See https://jerryscript.net/experimental")))
#endif

/**
 * Please give us feedback on this API here:
 * https://github.com/jerryscript-project/jerryscript/issues/XYZ
 */
void jerry_some_fancy_api(void) JERRY_EXPERIMENTAL;

[akosthekiss]

Re. "experimental API": deprecation is also handled with attributes, so marking up experimental functions with attributes can work with me.

(But a short comment on "people potentially need make meaningless changes to their project when the API is moved from the experimental header to another one": I don't think that's right. Moving a function from "jerryscript-experimental.h" to "jerryscript.h", as envisioned above, can have no effect on the user code if signature/semantics haven't changed because "jerryscript.h" must always be included in a project using JerryScript.)

[glistening]

I am happy for this issue on deprecated/experimental feature
+1 for not using prefix to experimental functions
+1 for using attribute for experimental/deprecated features

[martijnthe]

Moving a function from "jerryscript-experimental.h" to "jerryscript.h", as envisioned above, can have no effect on the user code if signature/semantics haven't changed because "jerryscript.h" must always be included in a project using JerryScript.)

Hmm, I'm but what about experimental port functions, or experimental functions that are not declared in jerryscript.h, like the debugger ones?

[akosthekiss]

As for debugger experimental functions, they are all in jerryscript.h. After some recent refactorings, jerryscript.h became a "grouping header", including jerryscript-core.h, jerryscript-snapshot.h, and jerryscript-debugger.h. So, the whole API is accessible by including jerryscript.h (and actually, the user doesn't even have to know about all the other -core, -snapshot, -debugger headers). Only jerryscript-port.h remains separated.

As for experimental port functions, I'm not sure what that would be? Can we have anything like that? I mean, with any of the above mentioned approaches. If we put experimental port functions into a separate header and the port implementation does not include it and does not implement them, we will get an incomplete port with which jerry will not work. But the same holds for attributed functions, too, with an addition that the compilation of jerry itself will be full of warnings (because warning attributes will fire at the call sites).

Anyway, I'm not pushing the separate header approach (as stated above, attributes are fine by me). And it seems that currently the attributes get the majority of votes. (Just note my comment on experimental port functions.)

[zherczeg]

Is there an attrbute for that? Or just create an empty define and put it before the function declaration? Optical warning :)

[zherczeg]

Attribute similar to deprecated, but not something which warns, since it stops compilation with -werror. So just a hint, that is why an empty define is acceptable for me. The define is visible to the user but does not have any side effect.

[martijnthe]

So just a hint, that is why an empty define is acceptable for me. The define is visible to the user but does not have any side effect.

Works for me :)

[rerobika]

#3104 has been accepted by the maintainers/community and currently there is no (and hopefully there will be no) deprecated (without major API version change)/experimental API functions. In my opinion the issue can be closed finally.