API maturity policy

[boneskull]

To my knowledge, there is no documented policy around API maturity (or stability). I think we need one, though I'm not sure how detailed it needs to be.

Shooting from the hip:

Experimental APIs

• What are the requisite condition(s) for considering a new API "experimental"?
• How is an API flagged as experimental (there's currently a convention of a leading underscore)?
• I assume "experimental" means it could be removed. Does removal of an experimental API need to happen in a major release? Do we need to soft-deprecate beforehand?

Stable APIs

• What are the requisite condition(s) for considering a new API "stable"?
• What sort of timing or process is involved in the "graduation" of an API from experimental to stable?

Note

I'm making the assumption that unless an API is born "stable", the only way for an API to become "stable" would be a one-way, irreversible promotion from "experimental."

Legacy and Deprecated APIs

• Should we consider some APIs to be "locked" (or "legacy") in that we do not expect further changes to them?
• Should we consider deprecated APIs in such a policy? If so, what would be the process around removing these APIs? We already use the @deprecated tag in places, but there's no clear path to actual removal.

Note

I assume "stable" APIs can move to "deprecated" or "legacy". "Experimental" APIs could also move to "deprecated." This is like a small, angry state machine.

Documentation

• Should we document API maturity outside of the sources, and how? It might be reasonable to do this via custom tags in TypeDoc (@deprecated is already supported).
• The whole point of this issue is to land an API maturity/stability policy, which needs to live somewhere. Where?

Relevant Examples

Experimental Preload Hooks

Ref: #2915 / #3132

@endo/compartment-mapper's _preload was requested by @kriskowal to be considered "experimental", and that is indicated by the leading underscore in the option. Since _redundantPreloadHook is nonsensical without the existence of _preload, it too was named with a leading underscore.

How can these become stable APIs?

Deprecated compartmentMapForNodeModules

@endo/compartment-mapper exports compartmentMapForNodeModules which has been deprecated (as an exported name) for at least a year (or intended as such; originally only the CompartmentMapForNodeModulesOptions type was flagged deprecated, which wasn't quite right). It's recommended to use mapNodeModules instead.

What's the process of striking compartmentMapForNodeModules from the exports of @endo/compartment-mapper?

Note

compartmentMapForNodeModules is still called internally by mapNodeModules, so it won't be removed, but rather just not exported (and CompartmentMapForNodeModulesOptions will be moved out of the external-facing types module).

Compartment Options

The signature of the Compartment constructor was changed at some point (before my time; at least two years prior). In order to use the new signature, a developer must provide the __options__: true flag within the first parameter (an options bag).

This example mentions "until SES and XS implementations converge." A naive search of XS surfaces no use of __options__.

How can we move forward with dropping this "temporary affordance?" Feedback from the Moddable team sounds helpful here.

Prior Art

• Node.js' Stability Index Documentation