-
Notifications
You must be signed in to change notification settings - Fork 4.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs: Clarify "Experimental and Unstable APIs" guidelines #14557
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It looks like I followed the wrong usage (unstable__bootstrapServerSideBlockDefinitions
) in the first place 🤣
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
__experimental
is to be removed from its exposed name)