[RFC] Adopt formal process for provisional features in JupyterLab core

[telamonian]

Make development of complex features easier and better by allowing for breaking changes in explicitly marked API (eg foo_PROVISIONAL). See #56.

A complete proposal for provisional features is included in this PR.

[blink1073]

I like the overall sentiment. Any comments I have would be about formatting consistency of the document, which you would pick up in an edit pass anyway. Thanks for laying this out!

[saulshanabrook]

I love this! Thank you max.

[vidartf]

+1 on the concept, some comments below:

Note: There are also some more or less formalized docstring directives that can be used (e.g. @alpha/@beta), that would allow a somewhat smoother acceptance of the provisional ones, but with the down-side of being a lot less explicit about it than having it be part of the name.

I think it would also be a good addition to spell out in which cases the _PROVISIONAL suffix cannot be used:

• When adding a non-optional field to an interface (as interfaces are supposed to allow for arbitrary implementation of something, and any third-party implementations of such interfaces would then break).
• When adding a new extension
• Others?

[saulshanabrook]

When adding a new extension

I was curious about this one... Seems like it could go either way, and thinking about adding the new datastore work, maybe to a new extension that is "provisional" at first might be useful?

[vidartf]

I was curious about this one..

To clarify: Previously we've had issues adding a new extension in a minor release. I forget the details, but was under the impression that it could break older minor versions of lab on the same major. On the other hand, if we are adding a new extension (either on a major version, or if we figure out we can do it safely in a minor release), then I would say we can of course add fields in that extension that are provisional, but that I think we cannot safely mark the entire extension as provisional (with the current build setup at least).

[jasongrout]

IIRC, if any old extension depends on the new extension, you get into trouble. If it's completely self-contained (like the log console extension we added in 1.2), I think it doesn't break older minor versions.

[saulshanabrook]

react uses unstable_: facebook/react#18825

[telamonian]

ooo, it looks like React only just recently added the unstable_ thing, a week before I posted this RFC. Interesting...

[saulshanabrook]

@telamonian they are channelling your proposal!

[Daniel15]

For what it's worth, React has used unstable_ for a while. unstable_batchedUpdates has existed for a while and unstable_createPortal used to exist years ago.

What changed recently is that APIs that are only in experimental prerelease builds (ie. not the regular React builds that most people download and use) are now also prefixed with unstable_. Previously, only experimental APIs that existed in stable releases had the unstable_ prefix.

[saulshanabrook]

@Daniel15 Oh good to know. Do you know if they had a discussion on what to name it somewhere we could reference?

My comment was kinda a joke, which is always risky on Github issues... Sarcasm doesn't travel well without context!

[Daniel15]

Do you know if they had a discussion on what to name it somewhere we could reference?

Not sure, sorry.

The Relay team also sometimes use an _UNSTABLE suffix rather than prefix (eg facebook/relay@56ab587, facebook/relay@b1cf05d) but I'm not sure if there's a story behind that either.

Internally at Facebook we sometimes semi-jokingly use DO_NOT_USE_OR_YOU_WILL_GET_FIRED for things that are internal-only and should never be used by users, but have to be exposed for some reason (and I think React may even have one or two of those) 😂