Document the separation between private APIs and experimental APIs #47973
Conversation
adamziel
requested review from
ajitbohra,
ryanwelcher,
juanmaguitar and
fabiankaegy
as code owners
adamziel
added
[Type] Developer Documentation
|
Flaky tests detected in 682d859. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4629651383
|
adamziel
changed the title
|
These docs read well to me, thank you! There's some jumping between the terms experimental and private from one section to another. I think I understand the difference (experimental === may change, private === not exported) but I think this could be highlighted a bit more. |
|
@peterwilsoncc I now start this entire section with an explanation of what's a private API and what's an experimental API – I hope it's clearer now! Also cc @ockham @luisherranz – I'd love your review in particular since you're directly interested in applying these ideas. Is the writing clear? Is anything confusing? |
| Experimental APIs are temporary values exported from a module whose existence is either pending future revision or provides an immediate means to an end. | ||
| There are two important API types in the Gutenberg codebase: | ||
|
|
||
| * **Experimental APIs** – they are public APIs that are only shipped in Gutenberg and not merged into WordPress core. Their existence is either pending future revision or provides an immediate means to an end. |
There was a problem hiding this comment.
Personally, I think that experimental APIs that are only meant for the Gutenberg plugin are useless. I think we can omit them.
There was a problem hiding this comment.
@youknowriad Oh! I thought they’re a good way of getting extenders feedback for APIs that are not mature yet?
There was a problem hiding this comment.
The thing I'm not sure that we need anything for that since the Gutenberg plugin is an alpha version. In other words, if we want to ship something into core, there's not specific to be done and if we want to limit something for the Gutenberg plugin for some time, we use IS_GUTENBERG_PLUGIN
In other words, I'm not sure we really need to formalize "experimental APIs" unless there's a way to ship these into core.
There was a problem hiding this comment.
Oh I see! Yeah IS_GUTENBERG_PLUGIN is key. I guess the only value in having an __experimental prefix is that you can find out which APIs may not be in core just by looking at the code of my theme or plugin. Personally I like that, but I'm also happy to remove it from the docs.
There was a problem hiding this comment.
@youknowriad I updated the document – what do you think now?
At first glance, it looks good to me, but I would need to try implementing something real before giving you full feedback on whether it's enough or if something is missing. |
|
Makes sense @luisherranz! I'd say let's get this PR in to make this information visible to everyone and then iterate on it further once you have more feedback. |
|
Yay, thank you @peterwilsoncc! And I'm glad it's helpful. |
| } | ||
| ``` | ||
|
|
||
| ### Exposing private APIs publicly |
There was a problem hiding this comment.
Do we really need this part of the document, seems a bit redundant with plugin only APIs. I don't feel strongly though.
There was a problem hiding this comment.
I only put it there because a few different people asked me that exact question. It's obvious once you make the mental connection, but even I needed some time to figure out this is possible.
What?
Documents the separation between private APIs and experimental APIs. Part of #47785
Rich text preview
cc @youknowriad @mcsf @gziolo @dmsnell @jsnajdr @peterwilsoncc