Docs: Clarify "Experimental and Unstable APIs" guidelines #14557
Conversation
aduth
requested review from
ajitbohra,
chrisvanpatten,
gziolo,
mkaz,
oandregal,
notnownikki and
youknowriad
as code owners
There was a problem hiding this comment.
In general I like these proposed changes (hence the approval). How does this impact the automatic docs generation? I think I've noticed a few cases where auto-docs generation has picked up prefixed functions and thus would violate these guidelines. It's possible that's already been rectified somewhere but just thought I'd bring it up.
By default, it's meant to ignore anything containing these keywords: gutenberg/bin/update-readmes.js Line 52 in 98a19b6
I'll defer to @nosolosw on this. |
|
|
||
| ```js | ||
| export { __unstableDoAction } from './api'; | ||
| export { __experimentalDoExcitingExperimentalAction } from './api'; | ||
| export { __unstableDoTerribleAwfulAction } from './api'; |
There was a problem hiding this comment.
Love this example ❤️
Related, is there any way of telling ESLint that __exeperminental* and __unstable* prefixes are fine? It yells when you try to use. It is fine but a little bit annoying to use such method. At least for experimental, it could be less strict.
There was a problem hiding this comment.
Related, is there any way of telling ESLint that
__exeperminental*and__unstable*prefixes are fine? It yells when you try to use. It is fine but a little bit annoying to use such method. At least for experimental, it could be less strict.
Could you share an example? I think I've seen it before where we use the non-conventional unstable__Whatever, but with the correct, leading underscores, it doesn't trip ESLint's camelcase rule:
There was a problem hiding this comment.
It looks like I followed the wrong usage (unstable__bootstrapServerSideBlockDefinitions) in the first place 🤣
There was a problem hiding this comment.
I like all clarifications included in this PR.
I was wondering whether we should replace unstable keyword with something scarier:
export { __WILL_BE_REMOVED_doTerribleAwfulAction } from './api';I'm not sure about the correct phrasing but sharing how it could be visually explained to the observers who won't read docs but will feel a strong desire to use such API method :)
Just checked for unstable/experimental in Markdown files, and this is what I've found. experimental:
unstable:
Of those, only Please, if you see any export that shouldn't be auto-documented, ping me and I'll get to fix it! :) |
There was a previous Core JS agenda item on this exact point:
https://make.wordpress.org/core/2019/01/29/javascript-chat-summary-january-29-2019/ In the meeting, it seemed generally agreed upon that there was not a need for changing the name. I'm happy to revisit it, but also think that (a) changing conventions is painful, (b) there's no perfect solution and the current convention is a reasonable middle-ground and (c) with new encouragement as of this pull request, unstable APIs should be very short-lived and not commonly encountered. |
I totally get your point and respect the previous decision made. It's fine to proceed as is and that's why I added my ✅ Ideally we don't have to use these prefixes at all rather than spend too much time thinking how to name them 😅 |
This pull request seeks to clarify the wording of the Coding Guidelines "Experimental and Unstable APIs" section, toward the goals of:
__experimentalis to be removed from its exposed name)