Title: Proposal: Stop merging experimental APIs from Gutenberg to WordPress Core Author: Adam Zieliński Published: August 10, 2022 Last modified: July 17, 2023 --- [ ](https://profiles.wordpress.org/zieladam/) [Adam Zieliński](https://profiles.wordpress.org/zieladam/) 12:02 pm _on_ August 10, 2022 Tags: [core ( 756 )](https://make.wordpress.org/core/tag/core/), [editor ( 223 )](https://make.wordpress.org/core/tag/editor/), [gutenberg ( 553 )](https://make.wordpress.org/core/tag/gutenberg/), [proposal ( 40 )](https://make.wordpress.org/core/tag/proposal/)    # Proposal: Stop merging experimental APIs from Gutenberg to WordPress Core This call for feedback will be open for the next four weeks until September 7th. I propose a way of harmonizing the process of merging new APIs from the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. to the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. Right now, the two projects have very different policies, confusing contributors and sparking lively discussions on every major WordPress release.  ## Today, experimental APIs are merged to Core and sometimes removed later To date, [280 experimental APIs were merged from the Gutenberg plugin to WordPress Core](https://github.com/WordPress/gutenberg/issues/40316). That’s problematic, and here’s why. WordPress values backward compatibility. Upgrading to a new version should not break the plugins and themes, so WordPress public APIs these plugins and themes depend on are maintained across major versions. As [the WordPress handbook states](https://developer.wordpress.org/block-editor/contributors/code/backward-compatibility/): > Historically, WordPress has been known for preserving backward compatibility across > versions.  The Gutenberg plugin values agility. It’s the safe space where new experiments are planted and grow into stable features without the same stability constraints. It is okay to ship a prototype, learn from it, and then start over again. New functions under active development often include the __experimental prefix in their name to indicate they may change at any point and shouldn’t be relied upon. Removing the obsolete code also makes the JavaScriptJavaScript JavaScript or JS is an object- oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. [https://www.javascript.com](https://www.javascript.com/) bundle smaller and reduces the editor loading time. As [the Gutenberg plugin handbook states](https://developer.wordpress.org/block-editor/contributors/code/coding-guidelines/#experimental-and-unstable-apis): > Experimental and unstable APIs are temporary values exported from a module whose > existence is either pending future revision or provides an immediate means to > an end. In the Gutenberg plugin, it’s fine to remove these experimental APIs. In WordPress, it’s not. Unfortunately, many have already been released with major WordPress versions. ## Tomorrow, experimental APIs could be restricted to the Gutenberg plugin and never merged to Core Let’s remove the experimental prefix before merging new APIs into WordPress Core. This way: * Core can deliver the expected level of Backwards Compatibility * The Gutenberg plugin can retain the freedom to remove the experimental APIs as needed * The experimental APIs would get audits * [It would make the release easier](https://github.com/WordPress/gutenberg/issues/40548) **Wouldn’t stabilizing every APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. before the release slow down new features?** The goal isn’t to stabilize. It’s to avoid adding public experimental APIs to WordPress core. Here’s two alternatives to stabilizing: * Ship a private API instead of a public experimental API. [Here’s how](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#comment-43619), and [here’s a proposed system for private cross-package APIs](https://github.com/WordPress/gutenberg/pull/43386). * Exclude the in-progress features from production builds using feature flags. **What if a stable feature depends on an experimental feature?** Then it isn’t actually stable. Let’s stabilize the dependencies first (or make them private). **What about the existing experimental APIs?** Most of those already merged to Core would get a stable alias. It would preserve BC and shouldn’t noticeably affect the bundle size. Some will need a different treatment; let’s discuss that case-by-case. **What if an existing experimental API already in Core needs to be removed?** Does it? If so, let’s consider that on a case-by-case basis. There are established Core practices like contacting plugin authors, writing make Core posts, preferring soft deprecations, and so on. I don’t expect to see many instances of this. **What if a future stable Gutenberg plugin API really needs to be removed ****_after_**** it’s released in Core?** Yes, it will happen. Let’s acknowledge and embrace it. Some good reasons were mentioned [in the GitHub discussion](https://github.com/WordPress/gutenberg/issues/40316), and the future will surprise us with many new ones. Again, let’s follow the established Core practices. For example, [deprecated.php](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php) shows that removing a function body is sometimes okay as long as the name keeps working. **What are the downsides?** I can see three: * Some Gutenberg plugin features will get merged into the Core later that they currently would be. The total amount of the development work won’t change, but the merging timeline will. That could be a good thing. Using the Gutenberg plugin is the intended way of accessing the upcoming features early. * Refactoring Gutenberg plugin APIs will be difficult once they get shipped with Core. In reality, that’s already the case. * Risk: Surgically removing all the Gutenberg plugin work spanning multiple WordPress releases from pre-release merges may become too complex. It would halt the merges entirely. If this risk does materialize, the merge guidelines will need to be adjusted again. If you see any other downsides, please speak out! **What alternatives have been considered?** * Keep not acting on the problem. * Use the same Backwards Compatibility policy for both WordPress and the Gutenberg plugin – which would make both projects worse off. * Find a way to ship the experimental APIs with Core as “internal” and unavailable to plugin authors – which [has been explored](https://github.com/WordPress/gutenberg/pull/41278) without a successful resolution. Unfortunately, neither is viable, [as explained in more detail in the GitHub discussion](https://github.com/WordPress/gutenberg/issues/40316#issuecomment-1203123251). ## If this resonates with you, speak out before September 7th! Policies don’t contribute to the Gutenberg plugin. People do. This proposal will only work if we, the contributors, believe it’s the right thing to do. Please share your thoughts under this post or [in the GitHub discussion ](https://github.com/WordPress/gutenberg/issues/40316)– even if it’s just “I like it.” All opinions are welcome, especially if you are not convinced about this proposal. This call for feedback will be open until September 7th. _Props to Birgit Pauli-Haack_ ([@bph](https://profiles.wordpress.org/bph/)), _Grzegorz Ziółkowski (_[**_@gziolo_**](https://profiles.wordpress.org/gziolo/)_), and Hector Prieto (_[@priethor](https://profiles.wordpress.org/priethor/)) _for their help in putting this proposal together._ [#editor](https://make.wordpress.org/core/tag/editor/) [#gutenberg](https://make.wordpress.org/core/tag/gutenberg/) [#core](https://make.wordpress.org/core/tag/core/) [#proposal](https://make.wordpress.org/core/tag/proposal/) ### Share this: * [ Threads ](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/?share=threads) * [ Mastodon ](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/?share=mastodon) * [ Bluesky ](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/?share=bluesky) * [ X ](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/?share=x) * [ Facebook ](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/?share=facebook) * [ LinkedIn ](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/?share=linkedin) 1. ![](https://secure.gravatar.com/avatar/4dfad80d8f9d884b2c7c39d304c339b2ae573d178e2e5ec3e9150299b25fe744? s=32&d=mm&r=g) 2. [Damon Cook](https://profiles.wordpress.org/colorful-tones/) 12:51 pm _on_ August 10, 2022 3. I feel this might get a little more traction if someone were to wrangle up links to the codebase of what and where _experimental APIs currently exist. 🤔 4. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 1:17 pm _on_ August 10, 2022 * Here’s the latest audit for WordPress 6.0 with all the __experimental APIs listed: [https://github.com/WordPress/gutenberg/issues/39977](https://github.com/WordPress/gutenberg/issues/39977) - ![](https://secure.gravatar.com/avatar/bf1bf4a08dcd6494ede244fd890adf356950d5e7d98c1a92c5f52371af3a7f2b? s=32&d=mm&r=g) - [turtlepod](https://profiles.wordpress.org/turtlepod/) 3:02 pm _on_ August 10, 2022 - wow… that’s a lot of experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. - ![](https://secure.gravatar.com/avatar/4dfad80d8f9d884b2c7c39d304c339b2ae573d178e2e5ec3e9150299b25fe744? s=32&d=mm&r=g) - [Damon Cook](https://profiles.wordpress.org/colorful-tones/) 9:16 am _on_ August 11, 2022 - Holy cannoli! That is quite a bit more than I imagined. - I agree with the overall proposal. If it goes in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., then it should be stable. 5. ![](https://secure.gravatar.com/avatar/f4ebf9368b7a3af8c3f46bd5b92e0d517eecc3150090e49598271a63ebccb83f? s=32&d=mm&r=g) 6. [Florian TIAR](https://profiles.wordpress.org/mista-flo/) 2:07 pm _on_ August 10, 2022 7. +1 on this, it just makes sense in fact, experimentation should be enabled at the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. level only. 8. ![](https://secure.gravatar.com/avatar/5d499534bfc21eaf9fa55506d50ffa01881d9a6cba58935552d3a8ac45944c29? s=32&d=mm&r=g) 9. [Nick Diego](https://profiles.wordpress.org/ndiego/) 2:43 pm _on_ August 10, 2022 10. Ignoring the technical aspects for a moment, I wholeheartedly agree with this approach. From an educational perspective, teaching folks how to build with these new techniques gets tricky when your teaching examples use `__experimental` APIs as they do not instill confidence. 😅 I am thinking primarily of blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. supports, many of which have been in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. for a very long time but are still prefixed as `__experimental`. 11. ![](https://secure.gravatar.com/avatar/5769f777927e07dbaf0d2356f67bca268e81f9b2e072da84d52465037217f235? s=32&d=mm&r=g) 12. [Bernie Reiter](https://profiles.wordpress.org/bernhard-reiter/) 3:13 pm _on_ August 10, 2022 13. Thanks Adam, this makes a lot of sense to me! 14. As the Editor Tech Co-lead for WP 6.1 (and I wholly plan to use these words to prefix all my comments from now on until release day 😉 ), I appreciate that you set the deadline for this discussion to September 7, [well before Beta 1](https://make.wordpress.org/core/2022/06/23/wordpress-6-1-planning-roundup/). 15. It does make me wonder, would it mean we should vet all existing `__experimental` APIs in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. ahead of WP 6.1 (and stabilize or remove them)? Or did you have a longer timeline in mind for this to happen? 16. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 11:08 am _on_ August 11, 2022 * [@bernhard-reiter](https://profiles.wordpress.org/bernhard-reiter/) For 6.1 let’s just focus on avoiding introducing new __experimental APIs. Stabilizing/ removing the existing ones could take a while. How long? My guess is as good as yours. * ![](https://secure.gravatar.com/avatar/b16e8d6d080a80522401b555b6aae73f95964a6ce490b70ef719f61251b56488? s=32&d=mm&r=g) * [Daniel Richards](https://profiles.wordpress.org/talldanwp/) 7:17 am _on_ August 15, 2022 * There’s a finality to stabilizing experimental APIs, so I don’t think it’s something that should be rushed into 6.1. * This will be a decision that there should be ample time to reflect on. * There’s going to be very little benefit to acting on this quickly anyway, the status quo of `__experimental` APIs has already been established, and they won’t really be going anywhere if we’re considering them stable. 17. ![](https://secure.gravatar.com/avatar/6d1a93cff6def54f06c7d5848b68e5b3dbc1308682a6567598c4a655f0942439? s=32&d=mm&r=g) 18. [Pablo Postigo](https://profiles.wordpress.org/poliuk/) 3:24 pm _on_ August 10, 2022 19. Thanks for putting this together Adam. I like the proposal, and I consider it will benefit both CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. & the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party.. 20. ![](https://secure.gravatar.com/avatar/89e470d01e796cd2a0c01bec6b71b8183a6a6a176513e740e3ee29894e60711a? s=32&d=mm&r=g) 21. [robglidden](https://profiles.wordpress.org/robglidden/) 4:43 pm _on_ August 10, 2022 22. I have hit __experimental APIs and they are a confusing headache. Please remove them all, and don’t allow any more. 23. * ![](https://secure.gravatar.com/avatar/6845456dbc9056f20a4cd50a6b95db78f2ae31df5c0601c613ee5b8939c41a82? s=32&d=mm&r=g) * [Jon Brown](https://profiles.wordpress.org/jb510/) 6:24 pm _on_ August 10, 2022 * I agree. All __experimental APIs are bloat that never should have made it into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and they all ought to ALL be removed from core. They only should have ever existed in the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party.. 24. ![](https://secure.gravatar.com/avatar/b1738118b1515a2c312e90b71dc041a57a90db61144063f36de6b27587b507d6? s=32&d=mm&r=g) 25. [Toro_Unit (Hiroshi Urabe)](https://profiles.wordpress.org/toro_unit/) 7:18 pm _on_ August 10, 2022 26. If it is to be merged into the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., it must be a non- experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. 27. It is very puzzling that an experimental API is shipped as is. If it remains an experimental API, I do not believe it should be merged into core. This situation is very confusing to theme and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. authors, and frankly, I am confused myself. 28. * ![](https://secure.gravatar.com/avatar/b1738118b1515a2c312e90b71dc041a57a90db61144063f36de6b27587b507d6? s=32&d=mm&r=g) * [Toro_Unit (Hiroshi Urabe)](https://profiles.wordpress.org/toro_unit/) 7: 20 pm _on_ August 10, 2022 * For APIs that have already been merged into the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., we believe it is better to remove “__experimental”. 29. ![](https://secure.gravatar.com/avatar/5612a0b1e26e958b7cb153ad8d69325be61525b2bba4819361bb69f127ec34b4? s=32&d=mm&r=g) 30. [mrwweb](https://profiles.wordpress.org/mrwweb/) 8:22 pm _on_ August 10, 2022 31. I’m very much in favor of this approach. I build custom themes and have a few simple plugins. For both, I have found myself somewhat frequently forced to deal with experimental APIs and the difficulties of keeping up to date with them when features are put in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. that can only be turned off, adjusted, or extended through an experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. 32. I’d call out this bit as the most important reason I think doing this makes sense: 33. > What if a stable feature depends on an experimental feature? > Then it isn’t actually stable. Let’s stabilize the dependencies first. 34. * ![](https://secure.gravatar.com/avatar/b16e8d6d080a80522401b555b6aae73f95964a6ce490b70ef719f61251b56488? s=32&d=mm&r=g) * [Daniel Richards](https://profiles.wordpress.org/talldanwp/) 7:36 am _on_ August 15, 2022 * I think the statement could do with clarification. * Notably ‘APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.’ is missing from that statement, and it’s what’s being discused. * I think it’s fine for a user-facing feature to be released, but supported by APIs that are under flux. I would go as far as suggesting that the majority of software development works like this, APIs change from one version to the next. WordPress is an outlier in supporting forever backwards compatibility. 35. ![](https://secure.gravatar.com/avatar/33212bff2915bd72792772a2d3203abe0402352b6be6ba65081036f10560c6e6? s=32&d=mm&r=g) 36. [justlevine](https://profiles.wordpress.org/justlevine/) 9:13 pm _on_ August 10, 2022 37. +1. A return to this sort of stability in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. would go a long way to regaining some developer goodwill. 38. * ![](https://secure.gravatar.com/avatar/4fc1e0aa20cfcba9afa49baebd6492426e4be58b716f2c8d78e783e138bc429f? s=32&d=mm&r=g) * [Stefano Garuti](http://garuti.it) 10:11 pm _on_ August 10, 2022 * I wholly agree. We absolutely regain the old confidence in the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. reliability. This constantly moving target that:s become the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor just need to be left in Guenberg. Seid in other words: if it’s experimental it isn’t core. If it’s in core, it clearly isn’t experimental anymore… 39. ![](https://secure.gravatar.com/avatar/5cd07f7bca6e9d0992c0635218e4aee9f65c674b45fbd8142b01a0e20b08363b? s=32&d=mm&r=g) 40. Anonymous User 6:07 am _on_ August 11, 2022 41. I agree with this proposal. 42. ![](https://secure.gravatar.com/avatar/de86c6b1fbf06589812d260f883f390ad8d62cbc41a4535578171c8cf644d663? s=32&d=mm&r=g) 43. [Maggie Cabrera](https://profiles.wordpress.org/onemaggie/) 11:23 am _on_ August 11, 2022 44. I agree with this, it makes a lot of sense that what goes on CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is not experimental, both in the short and in the long run, but specially the latter. 45. * ![](https://secure.gravatar.com/avatar/64b51769e7b80312023eb6c3f766cb512cf79adf7265812b15442f9573a9a056? s=32&d=mm&r=g) * [Tran Ngoc Tuan Anh](https://profiles.wordpress.org/rilwis/) 11:51 am _on_ August 11, 2022 * I agree with this. Adding more features via experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is cool, but removing them is a big problem. In this case, we should not merge them in the first place. All APIs that are merged should be stable. 46. ![](https://secure.gravatar.com/avatar/eaeeb93f1266ce3b9054ad2ab1d7b60e2d61547272b18b7281209dc50bc1f53e? s=32&d=mm&r=g) 47. [Renatho (a11n)](https://profiles.wordpress.org/renathoc/) 12:37 pm _on_ August 11, 2022 48. Totally agree! I’m just a little worried about that because in Sensei we use some of them in order to create some more advanced experiences in our blocks. Some of them wouldn’t have a workaround AFAIK. 49. > Then it isn’t actually stable. Let’s stabilize the dependencies first. 50. One of the points we were considering to check if we really want to assume the risk is how much time it’s around. So I imagine long-life features will probably be stabilized, right? 51. I’d like to list here some of the experimental/unstable features we’re using. 52. * `__unstableMarkNextChangeAsNotPersistent` from blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor store. * `__experimentalUseInnerBlocksProps` from block editor store. * `__experimentalGetPatternsByBlockTypes` from block editor store. * `__experimentalBorder` from block supports. * `__experimentalIsRenderedInSidebar` from ColorPalette * `__experimentalColors` from block supports. * `__experimentalConvert` from block transforms. * `__experimentalGetParsedPattern` from block editor store. * `__experimentalUseFocusOutside` from wordpress/compose. * `__experimentalGetLastBlockAttributeChanges` from block editor store. 53. Maybe some of them can already have a stable version, but honestly, I didn’t check it while writing this post. 54. > What if an existing experimental APIAPI An API or Application Programming Interface > is a software intermediary that allows programs to interact with each other > and share data in limited, clearly defined ways. already in CoreCore Core is > the set of software required to run WordPress. The Core Development Team builds > WordPress. needs to be removed? 55. Start doing it for the new experimental unstable features from now could be an option? 56. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 1:55 pm _on_ August 11, 2022 * > So I imagine long-life features will probably be stabilized, right? * They will be discussed case-by-case, but yes – that’s the idea! It’s all about making WordPress more reliable. * At a risk of sounding controversial, there never was an effective incentive to stabilize the existing __experimental APIs. This proposal creates one. * > Start doing it for the new experimental unstable features from now could > be an option? * I just propose following the established CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. practices every time there’s a need to remove an APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. from core. I’m not suggesting removing the existing APIs. Au contraire – the idea is to stabilize them. * ![](https://secure.gravatar.com/avatar/eaeeb93f1266ce3b9054ad2ab1d7b60e2d61547272b18b7281209dc50bc1f53e? s=32&d=mm&r=g) * [Renatho (a11n)](https://profiles.wordpress.org/renathoc/) 3:20 pm _on_ August 11, 2022 * > At a risk of sounding controversial, there never was an effective incentive > to stabilize the existing __experimental APIs. This proposal creates one. * Agree! * > I’m not suggesting removing existing APIs. Au contraire – the idea is to > stabilize them. * Perfect! =) * ![](https://secure.gravatar.com/avatar/ca481b56965d51c2202d6b74d3e6567908a142d529dc39061546a1acef255af2? s=32&d=mm&r=g) * [Lovro Hrust](https://profiles.wordpress.org/lovor/) 8:20 am _on_ August 14, 2022 * Indeed, there is a stable version of `__experimentalUseInnerBlocksProps` named useInnerBlocksProps. There is a developer notice about this. 57. ![](https://secure.gravatar.com/avatar/d49139aae88b36b005da13cd5acf63b1904c3066d020ba0480cb8986d50f9d44? s=32&d=mm&r=g) 58. [Juliette Reinders Folmer](https://profiles.wordpress.org/jrf/) 2:09 pm _on_ August 11, 2022 59. Hear Hear ! Finally…. 60. ![](https://secure.gravatar.com/avatar/4b66853c11bd212a5e7fc757d5a239131f300e8bbdcce8c4327c63023f8221d3? s=32&d=mm&r=g) 61. [Carlos Bravo](https://profiles.wordpress.org/cbravobernal/) 2:53 pm _on_ August 11, 2022 62. Thanks, Adam! 63. I agree with the proposal, and I cannot find more downsides than those mentioned above. 64. ![](https://secure.gravatar.com/avatar/8013a62d7397c006bae48b96d6832a573ea71a7d5d3597fe584210567b508c05? s=32&d=mm&r=g) 65. [Justin Tadlock](https://profiles.wordpress.org/greenshady/) 5:15 pm _on_ August 11, 2022 66. Definitely agree. If it goes into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., it should no longer be considered experimental. Theme and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. developers should expect reliable APIs. 67. ![](https://secure.gravatar.com/avatar/2ada113f1a81801cf4421e0b5af53c08bab45292957545dc68753ac5147b7c6f? s=32&d=mm&r=g) 68. [Tom J Nowell](https://profiles.wordpress.org/tjnowell/) 5:24 pm _on_ August 11, 2022 69. +10000 70. It’s always deeply unnerving looking at stable shipped code and finding it full of experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. calls that haven’t changed in months/years. A good number of those APIs should be promoted to stable or trimmed from the next major coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. release 71. ![](https://secure.gravatar.com/avatar/11177b397354c97025f395594f49e10041be4497df46e5d8b1f5b7ca4b063a3a? s=32&d=mm&r=g) 72. [Phil Johnston](https://profiles.wordpress.org/johnstonphilip/) 5:26 pm _on_ August 11, 2022 73. I could not agree more with this! Yes yes yes. CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. should be stable, dependable, predictable, and backwards compatible, through and through. 74. ![](https://secure.gravatar.com/avatar/24a5ca8b960821795fd5f6c0f70ce94a84e0ee71fea4beeee394fa66995ae838? s=32&d=mm&r=g) 75. [Peter Wilson](https://profiles.wordpress.org/peterwilsoncc/) 10:55 pm _on_ August 11, 2022 76. To reiterate my comment from the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) issue, I support this. Thanks Adam for writing the proposal. 77. ![](https://secure.gravatar.com/avatar/d5bebe65a302020ad03fc720d285907ee3914b5478093900e0daf0d2cc4cd24c? s=32&d=mm&r=g) 78. [Jorge Costa](https://profiles.wordpress.org/jorgefilipecosta/) 9:25 am _on_ August 12, 2022 79. Part of the issue with too many experimental APIs is that we can not share code between our packages without it being exposed to everyone. Some experimental APIs are not really experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. but artifacts that should be coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. only and not used by plugins and themes as there are better API’s for them. For example, suppose we want to add a new feature to blocks that will be iterative build across multiple versions and whose ideal API we don’t know yet. In that case, we add things to the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor package that our core blocks use, but there is nothing we can do to make a third-party pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress. org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. also not be able to use the same unstable API. I think to remove experimental APIs from core, we need a way that allows us to share code between packages that is just internal while a feature is being built. There were proposals for that in the past [https://github.com/WordPress/gutenberg/pull/41278](https://github.com/WordPress/gutenberg/pull/41278). In my opinion, we should ramp up that work and see where it goes before deciding on this. 80. I agree that experimental APIs are overused, and we should try to stabilize old experimental APIs that are there and should already be stable. We should make a considerable effort to reduce the number of experimental APIs and, on each core version, stabilize what we can and think is stable without any possibility of being unrequited in the future. But I don’t think we should go from an extreme where we may be using more experimental APIs than needed to the other extreme where we don’t have any experimental API’s in the core at all. We should try to remove them at the maximum but leave the door open to have experimental API’s in sporadic cases where we want broad feedback from the community on those APIs. Although the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) plugin is supposed to be where things are deeply tested, most APIs are only subject to real exhaustive testing by plugins and themes when they are added to the core. As a result, we can see that multiple issues on some APIs or back-compatibility issues only were reported when things went to the core and were not reported while on the plugin. 81. These are just my personal thoughts on the topic, and I will happily accept any decision. 82. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 1:59 pm _on_ August 22, 2022 * [@jorgefilipecosta](https://profiles.wordpress.org/jorgefilipecosta/) this new proposal addresses most of your concerns: * [Limit access to experimental APIs to WordPress codebase](https://github.com/WordPress/gutenberg/pull/43386) * I’d love to hear your thoughts on that. 83. ![](https://secure.gravatar.com/avatar/028ce05e0837e534b23aac17966d05820d6a0dc71a3f01bacf18a777e9e0a456? s=32&d=mm&r=g) 84. [Nik Tsekouras](https://profiles.wordpress.org/ntsekouras/) 9:59 am _on_ August 12, 2022 85. I agree with [@jorgefilipecosta](https://profiles.wordpress.org/jorgefilipecosta/) here and especially with this part: 86. > But I don’t think we should go from an extreme where we may be using more experimental > APIs than needed to the other extreme where we don’t have any experimental > APIAPI An API or Application Programming Interface is a software intermediary > that allows programs to interact with each other and share data in limited, > clearly defined ways.’s in the coreCore Core is the set of software required > to run WordPress. The Core Development Team builds WordPress. at all. 87. There has been so much discussion around this with good points from both side and while I might not have a great WP history knowledge, I was wondering why we should not consider: 88. 1. Treat existing APIs like stable and act on it(rename, etc..) 2. Be a lot more wary on new experimental APIs and avoid them if possible 3. If some times, especially in the big features like site editing, we can’t avoid it, let it in but first make all the required changes to documentation that these should not be used and that are subject to change. 89. The third point has already been mentioned in comments([ex](https://github.com/WordPress/gutenberg/issues/40316#issuecomment-1134309838)) but I don’t think folks focused on it much. There was the argument that this information was quite hidden in blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor docs, so can we change this and make this a lot more prominent and make it clear with other means like make.core posts, etc..? 90. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 10:37 am _on_ August 12, 2022 * [@ntsekouras](https://profiles.wordpress.org/ntsekouras/) @jorgefilipecosta I agree it’s sometimes hard to avoid shipping these “private” functions. This proposal would lead to merging them later in their lifecycle once the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. settles down. Which specific APIs could be problematic like that in 6.1? * Really all I’m saying is that WordPress promises a level of backwards compatibility that the __experimental APIs don’t stand up to. * There are only two ways to respect that policy: - Stop breaking the BC guarantees - Change the BC guarantees * This proposal is about the former. If you think the latter is a viable option, I encourage you to start that discussion. * Perhaps this proposal will slow new features down so much that we’ll have no other choice than to adjust the BC guarantees. Or perhaps it won’t. There’s only one way to find out. * > I think to remove experimental APIs from coreCore Core is the set of software > required to run WordPress. The Core Development Team builds WordPress., > we need a way that allows us to share code between packages that is just > internal while a feature is being built. > [https://github.com/WordPress/gutenberg/pull/41278](https://github.com/WordPress/gutenberg/pull/41278). > In my opinion, we should ramp up that work and see where it goes before > deciding on this. * @jorgefilipecosta This would be the best of both worlds. Having both truly private APIs AND highly backwards compatible public API sounds amazing. In a way, it’s separate from this proposal because shipping truly private APIs wouldn’t affect the WordPress public API. * If you’re enthusiastic about this idea, I highly encourage you to pick up that PR and see how far you can get. - ![](https://secure.gravatar.com/avatar/d5bebe65a302020ad03fc720d285907ee3914b5478093900e0daf0d2cc4cd24c? s=32&d=mm&r=g) - [Jorge Costa](https://profiles.wordpress.org/jorgefilipecosta/) 12:07 pm _on_ August 12, 2022 - Hi [@zieladam](https://profiles.wordpress.org/zieladam/), - > This proposal would lead to merging them later in their lifecycle once > the APIAPI An API or Application Programming Interface is a software > intermediary that allows programs to interact with each other and share > data in limited, clearly defined ways. settles down. Which specific APIs > could be problematic like that in 6.1? - Sometimes merging them later is not the best option. There is a planning and due dates for the features. We may just be delaying features we know we want and are ready until we think an API is perfect. We can easily see some examples: * We want sections to have names. It is a feature we want to ship to our users. But we don’t really know if names should be part of a more abstract metadata concept, so in [https://github.com/WordPress/gutenberg/pull/42605/](https://github.com/WordPress/gutenberg/pull/42605/), we have an experimental __experimentalHasBlockMetadataSupport. Having it as experimental allows people to try and pass feedback. Should we just delay shipping a feature for our coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks that is ok to use and is something we want because we are not sure about the concepts it is built on? When will that delay stop? * We want to provide a zoomed-out view to our users. That zoomed-out view will be iterated a lot and based on feedback, we will change it with time. So are we sure the selector __unstableIsWithinBlockOverlay [https://github.com/WordPress/gutenberg/pull/41156/](https://github.com/WordPress/gutenberg/pull/41156/) is something that makes sense and will always be needed ? I don’t think we are sure about that selector, but I also don’t think that is a reason to delay the feature. - > Really all I’m saying is that WordPress promises a level of backwards > compatibility that the __experimental APIs don’t stand up to. > There are only two ways to respect that policy: > * Stop breaking the BC guarantees > * Change the BC guarantees - WordPress PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher code has “* access private” markers for functions, classes etc. for a long time. The artifacts with these markers are not covered by the backwards compatibility promises. And plugins can still risk and use them, knowing they may break at any time. - I see the __experimental, and __unsable prefixes as the same in the JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. [https://www.javascript.com](https://www.javascript.com/) world, functions with these prefixes should not be used by plugins, themes, and website builders. If they are used, there is a risk of breaking things. In cases they are used, there is a need to check on each upgrade if they still work. - So I don’t see changes to __experimental and __unsable as breaking BC guarantees; in the same way, changing things with “* access private” is not breaking BC guarantees. We can add the “* access private” to the things still experimental in JavaScript to align with what core PHP was doing. - > [@jorgefilipecosta](https://profiles.wordpress.org/jorgefilipecosta/) > This would be the best of both worlds. Having both truly private APIs > AND highly backwards compatible public API sounds amazing. In a way, > it’s separate from this proposal because shipping truly private APIs > wouldn’t affect the WordPress public API. - If there are cases where something is __experimental to allow code sharing between packages, I think as part of the work to remove __experimental APIs from code, there needs to be a solution to share code between packages without exposing it. Otherwise, what will happen if we decide to remove __experimental APIs from the core and we don’t have a solution to share code privately? Are we going to expose something as part of our public API that is supposed to be just for internal usage and should not be there? What other options do we have? * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 1:45 pm _on_ August 12, 2022 * > We have an experimental __experimentalHasBlockMetadataSupport. * What is experimental about that selector? Could it be named `hasBlockMetadataSupport`? Also, it seems like it’s only used in the `blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-editor` package – perhaps it could be shipped there as a non-exported private function? * > Having it as experimental allows people to try and pass feedback. * Will shipping that in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. generate a better feedback than exposing it in the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. alone? * Say plugin authors pass their feedback after using this feature in their plugins. Then this function gets removed in 6.2. Then all these plugins break. * > We want to provide a zoomed-out view to our users. That zoomed-out > view will be iterated a lot and based on feedback, we will change > it with time. So are we sure the selector __unstableIsWithinBlockOverlay > [https://github.com/WordPress/gutenberg/pull/41156/](https://github.com/WordPress/gutenberg/pull/41156/) > is something that makes sense and will always be needed ? I don’t > think we are sure about that selector, but I also don’t think that > is a reason to delay the feature. * That selector is only used in the block-editor package, it could be a private and non-exported APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and then it wouldn’t even need the `__unstable` prefix. * > WordPress PHPPHP The web scripting language in which WordPress is > primarily architected. WordPress requires PHP 7.4 or higher code has“* > access private” markers for functions, classes etc. for a long time. * That is an interesting point! Have you seen many examples of these functions being removed in practice? Also cc [@peterwilsoncc](https://profiles.wordpress.org/peterwilsoncc/) who might have thoughts about that. - ![](https://secure.gravatar.com/avatar/d5bebe65a302020ad03fc720d285907ee3914b5478093900e0daf0d2cc4cd24c? s=32&d=mm&r=g) - [Jorge Costa](https://profiles.wordpress.org/jorgefilipecosta/) 3:01 pm _on_ August 12, 2022 - > What is experimental about that selector? Could it be named `hasBlockMetadataSupport`? > Also, it seems like it’s only used in the `blockBlock Block is > the abstract term used to describe units of markup that, composed > together, form the content or layout of a webpage using the WordPress > editor. The idea combines concepts of what in the past may have > achieved with shortcodes, custom HTML, and embed discovery into > a single consistent API and user experience.-editor` package – > perhaps it could be shipped there as a non-exported private function? - It is experimental in the sense that we don’t know if we are going to have a metadata system. So if we don’t have a metadata system, that selector stops existing and is removed. Off course, we could name it hasBlockMetadataSupport, but later, if we don’t have the metadata concept, code using that selector breaks. If it was experimental or unstable, it was clear it should not have been used in the first place. - > Will shipping that in CoreCore Core is the set of software required > to run WordPress. The Core Development Team builds WordPress. generate > a better feedback than exposing it in the GutenbergGutenberg The > Gutenberg project is the new Editor Interface for WordPress. The > editor improves the process and experience of creating new content, > making writing rich content much simpler. It uses ‘blocks’ to add > richness rather than shortcodes, custom HTML etc. > [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) > pluginPlugin A plugin is a piece of software containing a group > of functions that can be added to a WordPress website. They can > extend functionality or add new features to your WordPress websites. > WordPress plugins are written in the PHP programming language and > integrate seamlessly with WordPress. These can be free in the WordPress. > org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) > or can be cost-based plugin from a third-party. alone? - Historically there is much wider feedback once an APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. arrives in the core than before. - > Say plugin authors pass their feedback after using this feature > in their plugins. Then this function gets removed in 6.2. Then > all these plugins break. - The function was something experimental and should not have been used by production plugins in the first place. Plugins could try it on their development setups and pass feedback but using it in production was never advisable. If it was used by production plugins, the users of that function should at least check on each release if the function was still there. - > That selector is only used in the block-editor package, it could > be a private and non-exported API and then it wouldn’t even need > the `__unstable` prefix. - Do we have the concept of private selectors and actions? Even inside the same package, there is not a simple way to create a selector or action without it being public. So how can we make it a private non-exposed API? * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 12:55 pm _on_ August 15, 2022 * > Plugins could try it on their development setups and pass feedback * @jorgefilipecosta What other ways of getting feedback have been explored? Where did they fall short? * I know @annezazu did a developer outreach quite a few times, I wonder if that would work here. Giving the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. more visibility as “WordPress early access” could also help. * > If it was experimental or unstable, it was clear it should not > have been used in the first place. * This isn’t what happens in practice. Developers do use these APIs and their plugins and themes do get broken when the experimental code is removed. That’s real-world feedback. * The prefix as a deterrent didn’t work the way we hoped it would. When that happens to features and APIs, they get removed or reinvented. * > Do we have the concept of private selectors and actions? * Yes! The most basic idea is to encapsulate the selector logic using ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. [https://reactjs.org](https://reactjs.org/) hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.: * ```notranslate function useIsWithinBlockOverlay( clientId ) { return useSelect( ( select ) => { const selectors = select( blockEditorStore ); let parent = selectors.getBlockRootClientId( clientId ); while ( !!parent ) { if ( hasActiveBlockOverlayActive( selectors, parent ) ) { return true; } parent = selectors.getBlockRootClientId( parent ); } return false; }); } ``` * If you need the same low-level access to the store state as you have in the selector, you can get it like this: * ```notranslate const registry = useRegistry(); console.log(registry.stores['core/block-editor'].store.getState()); ``` * useRegistry also allows you to dispatch custom actions: * ```notranslate const registry = useRegistry(); console.log(registry.stores['core/block-editor'].store.dispatch({ type: 'BEFORE_SAVE' })); ``` * In the store, you can encapsulate selector logic using [thunks](https://developer.wordpress.org/block-editor/how-to-guides/thunks/): * ```notranslate export function toggleFeature( scope, featureName ) { return function ( { select, registry } ) { const currentValue = select.isFeatureActive( scope, featureName ); const doubleTemperature = select( ( temperature ) => temperature * 2 ); const error = registry.select( 'core' ).getLastEntitySaveError( 'root', 'menu', menuId ); }; } ``` * Thunks also allow you to dispatch custom actions without making them part of the public APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.: * ```notranslate const myAction = ( id ) => ({ dispatch }) => { dispatch({ type: 'BEFORE_SAVE', id, record }); } ``` * CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.-data does that a lot. * ![](https://secure.gravatar.com/avatar/700febabf646717b35cab3a3bbc42e405237922fccda8b01ad07cde219de62bd? s=32&d=mm&r=g) * [Tonya Mork](https://profiles.wordpress.org/hellofromtonya/) 1:38 pm _on_ August 15, 2022 * I wonder in regards to internal-only usage code: * Has the past practice of deprecating privately marked internal- only code been incorrectly applied for too strict of an interpretation of the Backwards Compatibility (BC) Promise? * Maybe. * Should internal-only code forever be BC maintained? If yes, why? * IMO, privately marked internal-only functionality should not be included in the BC Promise unless .. big disclaimer coming .. unless it changes the behavior of non-internal functionality in a non-BC way. * > WordPress PHPPHP The web scripting language in which WordPress > is primarily architected. WordPress requires PHP 7.4 or higher > code has “* access private” markers for functions, classes etc. > for a long time. The artifacts with these markers are not covered > by the backwards compatibility (BC) promise. And plugins can > still risk and use them, knowing they may break at any time. * I agree. * Let me share my thinking. * Marking as `private` means _internal CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. only usage_. Though these may be publicly exposed( because of the nature of internal usage across different APIs and functionality), the intent is to denote each as for Core only usage. In other words, do not invoke or consume this functionality outside of Core. (again IMO) * > This is true but often developers end up using them anyway * What if a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. or theme uses these? There’s a risk to users and a likelihood that these will be used outside of Core. I agree with [@peterwilsoncc](https://profiles.wordpress.org/peterwilsoncc/). Though extenders are technically able to access and invoke (due to the nature of the programming language and architectural design), if `private` is viewed through the lens of “this code is for internal- only usage”, then the developer externally using them assumes the risks and is responsible for maintaining their code. * **Bigger picture** * I think the bigger picture here is an open discussion to gain a collective understanding of: - Can or should Core have its own internal functionality that is publicly exposed but is marked for internal only usage? - If yes, must this code be forever backwards compatible? * If yes to the first question but no to the second question, then the scope of this proposal changes to focus on the experimental, external usage APIs. - ![](https://secure.gravatar.com/avatar/24a5ca8b960821795fd5f6c0f70ce94a84e0ee71fea4beeee394fa66995ae838? s=32&d=mm&r=g) - [Peter Wilson](https://profiles.wordpress.org/peterwilsoncc/) 11:11 pm _on_ August 15, 2022 - [@hellofromtonya](https://profiles.wordpress.org/hellofromtonya/) I think the future of private markers in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is a separate discussion. The history is they have been soft deprecated. * ![](https://secure.gravatar.com/avatar/ca481b56965d51c2202d6b74d3e6567908a142d529dc39061546a1acef255af2? s=32&d=mm&r=g) * [Lovro Hrust](https://profiles.wordpress.org/lovor/) 8:17 am _on_ August 14, 2022 * Perhaps I am missing something, but I want to share my thoughts on this: If experimental APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is defined as internal coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. API, not meant to be used by non-core developers, because they can change with time, this is fine with me. Similar thing already exists in WordPress PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher codebase, functions prefixed by `_`. However, if experimental API provides some developer friendly essential feature, a **stable ** API should be exported from experimental, so developers can use it, and even if experimental API changes, **the interface** which stable API provides will not. I developed 60+ blocks, some pretty complex, interacting with store, parent blocks and custom REST points and managed mostly to stay away from experimental API. * ![](https://secure.gravatar.com/avatar/24a5ca8b960821795fd5f6c0f70ce94a84e0ee71fea4beeee394fa66995ae838? s=32&d=mm&r=g) * [Peter Wilson](https://profiles.wordpress.org/peterwilsoncc/) 12:03 am _on_ August 15, 2022 * > WordPress PHPPHP The web scripting language in which WordPress is > primarily architected. WordPress requires PHP 7.4 or higher code has“* > access private” markers for functions, classes etc. for a long time. > The artifacts with these markers are not covered by the backwards > compatibility promises. And plugins can still risk and use them, knowing > they may break at any time. * This is true but often developers end up using them anyway so they’re moved to deprecated.php if they’re deprecated. (There’s about 20 instances of `@private` in the file.) * **In short: the same mistake has been made in WordPress-Develop.** * As a case in point the function `_doing_it_wrong()` and `_deprecated_*()` functions were initially marked private but the delegation was removed in [#48251](https://core.trac.wordpress.org/ticket/48251). Partly because the functions were useful, partly because they were so commonly used: * > I have not been able to discover why they were marked as private in > the first place, but not withstanding that, they are widely used by > plugins (13249 matches) and themes (13512 matches) anyway. * It’s similar a similar case with the _private_ class `WP_List_Table`. Practically, WP CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. [can’t change the API](https://wpdirectory.net/search/01GAFB7ZVSW2RFWH2FVPW3NN3Y). * From the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor Handbook: * > Backward compatibility guarantees only apply to the production packages[ > shipped as WordPress scripts], as updates happen through WordPress > upgrades. * This is one of the reasons I have been pushing for the dropping of these experimental APIs and support this proposal. The promise has been made once these developer APIs have shipped. - ![](https://secure.gravatar.com/avatar/3c745a9e2a73a1c941c806f982029dc440f0b09ac256aa27e8219e509a557678? s=32&d=mm&r=g) - [Héctor Prieto](https://profiles.wordpress.org/priethor/) 12:36 pm _on_ August 12, 2022 - For context, what’s preventing pursuing the concept on [https://github.com/WordPress/gutenberg/pull/41278](https://github.com/WordPress/gutenberg/pull/41278)? [@gziolo](https://profiles.wordpress.org/gziolo/), what challenges did you find when exploring it? Are there any technical blockers, or was the idea dropped mainly due to lack of engagement and support? 91. ![](https://secure.gravatar.com/avatar/496b8d78333d03512679c1c1d343cb82f563f5beb4d0f6f9368c0c95b95ed3cc? s=32&d=mm&r=g) 92. [Paul Gibbs](https://profiles.wordpress.org/djpaul/) 12:07 pm _on_ August 12, 2022 93. I agree with this proposal. 94. ![](https://secure.gravatar.com/avatar/3b04b6a0e3f18167632b7fc0ff0848ca2175b966fff7df8deed31d69416c8699? s=32&d=mm&r=g) 95. [David Baumwald](https://profiles.wordpress.org/davidbaumwald/) 2:31 pm _on_ August 12, 2022 96. Thanks for putting this together [@zieladam](https://profiles.wordpress.org/zieladam/)! 97. I fully support this as-is. CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. should be stable and the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. is where iteration to stabilize things should happen. If the plugin is not getting enough wide-reaching testing to iterate on its own, that’s the plugin’s problem, not Core. 98. ![](https://secure.gravatar.com/avatar/b16e8d6d080a80522401b555b6aae73f95964a6ce490b70ef719f61251b56488? s=32&d=mm&r=g) 99. [Daniel Richards](https://profiles.wordpress.org/talldanwp/) 6:38 am _on_ August 15, 2022 100. This is a difficult issue, because I absolutely see and agree with both sides of the argument: 101. * On one hand it is unsustainable to have so many __experimental APIs. A lot of the __experimental (and __unstable) APIs are very stagnant, and that’s a particular problem. In addition to that, they’re confusing for pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party./theme developers, they’re undocumented for contributors, and against the backwards compatibility philosophy of WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. * On the other hand, there’s a strong desire for shipping GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) features and bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes faster, and using an evolving and iterative approach to feature development. 102. I don’t agree with the methodology proposed here, specifically the process of stabilizing every APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. before merge in WordPress core. I think it would lead to Gutenberg development essentially revolving around WordPress releases, and the thing that most WordPress contributors know is that releases are a long, stressful and complicated process. I think this becomes even worse if every API has to be migrated to stable prior to release. It would result in slower development and less iteration (because iteration actually isn’t possible). It cannot be underestimated how much work actually happens in the Gutenberg project and how much extra overhead this introduces. 103. I agree with [@ntsekouras](https://profiles.wordpress.org/ntsekouras/) and [@jorgefilipecosta](https://profiles.wordpress.org/jorgefilipecosta/)‘ s comments that it’d be good to at least explore other options, ideally something where __experimental APIs are not made public from the start. I left a comment about [using feature flags](https://github.com/WordPress/gutenberg/issues/40316#issuecomment-1203635340) more on the issue, which I think would help in terms of shifting the onus to implementation time rather than release time. It would be a lot of work though, and would require contributors to be very aware of how features are implemented. I’d like to see other ideas too, and will continue to think about it. 104. Something still needs to be done about the existing APIs, and I agree they should be assessed on a case-by-case basis. 105. * ![](https://secure.gravatar.com/avatar/121e7ab195ec67c6a14b0940f9cbc4c9a732adeaaa1457e1af8e8855a17d0c98? s=32&d=mm&r=g) * [Andrei Draganescu](https://profiles.wordpress.org/andraganescu/) 9:53 am _on_ August 15, 2022 * I think this is a great proposal. For me the area where it lacks **strong arguments** is around quickly dismissing this: * > Find a way to ship the experimental APIs with CoreCore Core is the set of > software required to run WordPress. The Core Development Team builds WordPress. > as “internal” and unavailable to pluginPlugin A plugin is a piece of software > containing a group of functions that can be added to a WordPress website. > They can extend functionality or add new features to your WordPress websites. > WordPress plugins are written in the PHP programming language and integrate > seamlessly with WordPress. These can be free in the WordPress.org Plugin > Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) > or can be cost-based plugin from a third-party. authors – which has been > tried and did not get much traction. * Was, umm, _traction_ the problem? Because if so, it makes no sense 🙂 We need a technical solution, with or without traction. * In my opinion, having a way to continue to merge unstable GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) code, but in a way in which it is not global and easily accessible, is **ideal**. If this turns out to be _impossible_, then this proposal is the next best thing. * If this proposal is not accepted, then, I believe, a need appears to redefine what WordPress means by backward compatibility. This definitely should not be an impossible task: to amend the project’s definition of BC. * To wrap, this discussion’s highlight on _too many experimental APIs_ is a separate discussion, and that (a process that encourages stabilizing or deprecating) is not solved even if this moves forward as is. - ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) - [zieladam](https://profiles.wordpress.org/zieladam/) 1:58 pm _on_ August 15, 2022 - > Was, umm, traction the problem? Because if so, it makes no sense 🙂 We > need a technical solution, with or without traction. - [@andraganescu](https://profiles.wordpress.org/andraganescu/) [@gziolo](https://profiles.wordpress.org/gziolo/) explored [“private exports”](https://github.com/WordPress/gutenberg/pull/41278) to make shipping experimental private APIs more convenient. It’s an implementation of this proposal, not a fundamentally different path forward. - [@peterwilsoncc](https://profiles.wordpress.org/peterwilsoncc/) noted a few technical obstacles in [his comment](https://github.com/WordPress/gutenberg/pull/41278#issuecomment-1145442652). Perhaps they’re not show-stoppers and could be resolved if someone volunteered to step in and explore it further. Would you like to champion this idea? - > If this proposal is not accepted, then, I believe, a need appears to > redefine what WordPress means by backward compatibility. - Agreed! I don’t see a way to have both deep backwards compatibility and experimental APIs. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 1:46 pm _on_ August 15, 2022 * > I think it would lead to GutenbergGutenberg The Gutenberg project is the > new Editor Interface for WordPress. The editor improves the process and > experience of creating new content, making writing rich content much simpler. > It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. > > [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) development > essentially revolving around WordPress releases * [@talldanwp](https://profiles.wordpress.org/talldanwp/) Major features already revolve around WordPress releases. The widgets editor, the navigation blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience., the WebFonts APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. have all involved great collective effort targeted at this or that major WordPress release. * > I agree with @ntsekouras and @jorgefilipecosta‘s comments that it’d be good > to at least explore other options, ideally something where __experimental > APIs are not made public from the start. * That would be great! It would effectively implement this proposal, too. by ensuring no new public experimental APIs get merged to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. Private experimental APIs are fine. In fact, all private APIs seem effectively experimental to me as they can be removed or refactored at any time. * > I think this becomes even worse if every API has to be migrated to stable > prior to release. It would result in slower development and less iteration( > because iteration actually isn’t possible). * Manually migrating every API on every WordPress release would indeed be too much. But how about stabilizing only a selected few? * I hope to not see dozens of new experimental APIs in the first place. The __experimental prefix is overused. Many __experimental APIs don’t need to be exported or experimental in the first place. * Furthermore, not all __experimental APIs need to be shipped with the next major WordPress release. Perhaps your feature flags idea could help keep them out of production builds with a flip of a switch. I keep thinking about alternatives, too. * This proposal would increase the stabilization work’s priority, but it wouldn’t generate more work. The stabilization work is there anyway. * > Something still needs to be done about the existing APIs, and I agree they > should be assessed on a case-by-case basis. * Agreed! - ![](https://secure.gravatar.com/avatar/b16e8d6d080a80522401b555b6aae73f95964a6ce490b70ef719f61251b56488? s=32&d=mm&r=g) - [Daniel Richards](https://profiles.wordpress.org/talldanwp/) 8:59 am _on_ August 17, 2022 - > Major features already revolve around WordPress releases. The widgets > editor, the navigation blockBlock Block is the abstract term used to > describe units of markup that, composed together, form the content or > layout of a webpage using the WordPress editor. The idea combines concepts > of what in the past may have achieved with shortcodes, custom HTML, and > embed discovery into a single consistent API and user experience., the > WebFonts APIAPI An API or Application Programming Interface is a software > intermediary that allows programs to interact with each other and share > data in limited, clearly defined ways. have all involved great collective > effort targeted at this or that major WordPress release. - The two of those that I’m most familiar with are good examples, because development spanned multiple WordPress releases and changed considerably over those releases. It’s a speculative comment, but I think the features that were launched either wouldn’t have been possible or would have been severely hindered by having to stabilize APIs upon reaching the first WordPress release. - Anyway, I think the main thing is that I agree with the goal, but there could be more effort in looking at alternative solutions. - A call for contribution into exploring options is an idea. Most of the efforts so far have been driven by motivated individuals rather than a well structured group. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 10:40 am _on_ August 17, 2022 * > I think the features that were launched either wouldn’t have been > possible or would have been severely hindered by having to stabilize > APIs upon reaching the first WordPress release. * I agree with you here. I don’t think stabilizing them would be helpful. The WebFonts APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. avoided that by making virtually every public function private. The Widgets editor, on the other hand, was disabled before one of the releases, but the APIs it shipped weren’t. I’d rather see them removed from the production builds via feature flags or some other mean. * > A call for contribution into exploring options is an idea. Most of > the efforts so far have been driven by motivated individuals rather > than a well structured group. * +1 106. ![](https://secure.gravatar.com/avatar/fa9bb9feab2f2f97662e7b07c9deaf0aca3ec7c037840a8cc3563ec022f77048? s=32&d=mm&r=g) 107. [Miguel Fonseca](https://profiles.wordpress.org/mcsf/) 2:16 pm _on_ August 15, 2022 108. While I agree that the proliferation of unchecked experimental APIs is an unsustainable issue, I am concerned that this proposal hinges on an all-or-nothing solution, underestimates how core contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. [https://core.trac.wordpress.org](https://core.trac.wordpress.org) and the roadmap would be affected, and fuels the oversimplification of a technical debate instead of countering controversy with nuance — the most salient point being the conflation of interface stability with feature stability. 109. * **APIs differ in nature.** Functions are easy to scrutinise, and easier to gate. But many of the things we call APIs aren’t functions: there are actions, schema keys, metadata — methods of communication that rely on data and message protocols rather than explicit function calling. Not acknowledging this variety creates the illusion that the technical implications of this proposal are almost trivial. - Note: as I was drafting this reply, I saw a few comments about trying to prevent interfaces from becoming public in the first place (“ideally something where _\_\_experimental_ APIs are not made public from the start.”). While this may work very well at times, I’d be careful to not sacrifice the design of a solution in the name of limiting exposure. It’s something to weigh on a case by case basis. * **APIs differ in scope.** The term APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is overloaded, especially the initial _P_: some interfaces are decidedly public, some are decidedly private, but for many other interfaces the scope sits somewhere in between — a reflection of the [modular architecture](https://riad.blog/2020/01/28/embrace-the-modularity/) of the project. I’ll explain. Traditional PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher-based code in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. also needs to manage public and private interfaces, but its monolithic architecture and PHP’s class system combine to give it more tools to restrict access to internals. In contrast, GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) is shaped by a very special set of constraints. It is, all at once: a constellation of independent NPM packages but also a large immersive application; a stage for continuous iteration but also for consolidation in harmony with Core; a “modern” client-first application but also an integral piece of WordPress’s server-driven machinery (rendering, settings, etc.); a Web-first application but also an open architecture to power mobile applications; etc. By definition, it cannot be as tightly locked down as Core’s PHP pieces. A lot of interfaces are thus akin to [IPC](https://en.wikipedia.org/wiki/Inter-process_communication): their goal is to facilitate communication across components, but they are not a contract with third parties. * **Experimental interfaces can support stable features.** To me, this is the most important point. Jorge has [already made this argument](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#comment-43602) but, looking at both the initial proposal and the [response](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#comment-43604) to Jorge, I feel that this has been approached as a false dichotomy. When a user feature is released that relies on these “public APIs”, that neither implies that the feature is less stable nor that the APIs should be stabilised. Any piece of software concedes that implementation details may change in order to better satisfy a stable interface. Per my reasoning in the previous sections, our experimental interfaces — which often don’t come in the form of easy-to- gate functions — reflect choices of internal models, algorithms, and separation of concerns. In this sense, they are definitely implementation details that we should reserve the right to validate, improve or discard — for the benefit of stable features, good abstractions and actually public APIs. 110. I am not sure what the right way forward is, but I think a counterproposal should include: 111. * Making a more formal distinction between **experimental** and **internal/unstable** interfaces: the former represent interfaces that could eventually benefit everyone; the latter are meant to stay private, regardless of whether they may change in two weeks or two years. * Recognising that sometimes time is needed to validate an **experimental** API, even if that means merging to Core, with all the added scrutiny that that entails. The problem is ensuring follow-up: after a number of months, contributors must make the decision to either stabilise it or discard it. How do we fix that flow? * Exploring possible technical solutions to **restrict access** to private interfaces. However, this shouldn’t be done with the expectation that this problem is solvable just with technical solutions. It’s important to figure out why the_\_\ _experimental_ and _\_\_unstable_ prefixes aren’t adequate deterrents. * Encouraging a healthy questioning of new interfaces. This does **not** mean discouraging any new interfaces nor compromising the architecture just to restrict access. It means that, when reviewing work that includes API changes, authors and reviewers should have an honest conversation about **what the goal of the interface is**, in the short and long terms, who it is for, how it relates to other interfaces and with the product roadmap, etc. * Acknowledging that experimental interfaces can support stable features and** dismantling the underlying misconception** that the adjectives “experimental” or “unstable” are an assessment of (lower) quality. * Recognising that the issue is complex: yes, we have too many experimental APIs out there left unchecked or under-documented. But the flawed system that caused this has also given contributors room to focus on quality (of product, of architecture, of actual APIs) while remaining agile. This doesn’t mean that we shouldn’t change anything: no, we have to fix the problem somehow, but we need to **be clear about the trade-offs** of the before and after. * Lastly, as a bonus, devise a better system for pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. authors who are willing to experiment with interfaces subject to change. For example, are there best practices of graceful degradation / **progressive enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature.** that we could establish, so that evergreen plugins can better tolerate changing or missing experimental interfaces? Can we **develop a better feedback cycle** so that core developers learn from third-party use? 112. * ![](https://secure.gravatar.com/avatar/a2690bc3e7ef0350cac88e27809169288b0086b1714707655fd2635026a0670b? s=32&d=mm&r=g) * [Robert Anderson](https://profiles.wordpress.org/noisysocks/) 1:38 am _on_ August 16, 2022 * > Exploring possible technical solutions to restrict access to private interfaces. * An idea [@talldanwp](https://profiles.wordpress.org/talldanwp/) and I had last night while chatting is: could we _explicitly_ add functions to the ` wp` global instead of _implicitly_ doing it via webpack. * ```notranslate // Available for consumers of this package using npm: export { Button, __experimentalGrid }; // Available for WordPress plugins using wp global: wp.Button = Button; ``` - ![](https://secure.gravatar.com/avatar/fa9bb9feab2f2f97662e7b07c9deaf0aca3ec7c037840a8cc3563ec022f77048? s=32&d=mm&r=g) - [Miguel Fonseca](https://profiles.wordpress.org/mcsf/) 2:19 pm _on_ August 16, 2022 - Technically, that seems doable. And maybe — who knows — that turns out to be a very effective hurdle. Part of me feels weird about it, though: we’d be using different sieves for consumers of the NPM packages and those of WP’s traditional environment. Does it complicate the official “scope” of an interface? And what of the distinction between experimental and internal/ unstable/private? Does it say something about developer expectations varying depending on the dev environment? I have no idea. 🙂 * ![](https://secure.gravatar.com/avatar/b16e8d6d080a80522401b555b6aae73f95964a6ce490b70ef719f61251b56488? s=32&d=mm&r=g) * [Daniel Richards](https://profiles.wordpress.org/talldanwp/) 9:21 am _on_ August 17, 2022 * I think there’s some power in being able to decide what’s publicly available on the wp namespace. And without using prefixes. * But I agree about the difference between package users and `wp` global variable users. An idea is that we could produce different builds (‘ stable’ and ‘internal’) by using different entry points in packages. Stable would correspond to what’s in the `wp` global. But I have a lot of doubt about a proposal like this because there are so many nuances. * As you say in your other comment, these APIs aren’t just functions. Selectors, actions, properties and parameters also don’t fall under a neat solution. - ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) - [zieladam](https://profiles.wordpress.org/zieladam/) 10:46 am _on_ August 17, 2022 - > Selectors, actions, properties and parameters also don’t fall under > a neat solution. - In my other comment I [described a way to create private per-package selectors and actions](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#comment-43619). It doesn’t solve sharing them between the packages, though. 113. ![](https://secure.gravatar.com/avatar/a2690bc3e7ef0350cac88e27809169288b0086b1714707655fd2635026a0670b? s=32&d=mm&r=g) 114. [Robert Anderson](https://profiles.wordpress.org/noisysocks/) 2:13 am _on_ August 16, 2022 115. I’m okay with limiting `__experimental` and `__unstable` to the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress. org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. in principle but I’d first like to see a technical solution to how we can write interfaces (functions, selectors, actions, etc.) that CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) can use but that third party plugins cannot use. 116. I can’t support this proposal until then because otherwise it will mean that we either delay shipping features (waiting for APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. stabilisation) or increase technical debt (maintaining lots of legacy poorly thought out APIs). Either option, in the long term, results in a slower development cycle. WordPress can’t afford to slow down if it is to remain relevant. 117. * ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) * [zieladam](https://profiles.wordpress.org/zieladam/) 12:05 pm _on_ August 17, 2022 * > I’d first like to see a technical solution to how we can write interfaces( > functions, selectors, actions, etc.) that CoreCore Core is the set of software > required to run WordPress. The Core Development Team builds WordPress. and > GutenbergGutenberg The Gutenberg project is the new Editor Interface for > WordPress. The editor improves the process and experience of creating new > content, making writing rich content much simpler. It uses ‘blocks’ to add > richness rather than shortcodes, custom HTML etc. > [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) > can use but that third party plugins cannot use. * I just had an idea about private functions – see the related [GitHub PR](https://github.com/WordPress/gutenberg/pull/41278#issuecomment-1217900813). * Also, I described a way to [create private per-package selectors and actions](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#comment-43619) in my other comment. 118. ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) 119. [zieladam](https://profiles.wordpress.org/zieladam/) 1:45 pm _on_ August 19, 2022 120. I see many concerns that stabilizing the __experimental APIs on every release is not viable and will significantly slow down the development. I agree. I don’t think stabilizing is always the answer. There are many ways to avoid merging public __experimental APIs into WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.: 121. * Create private APIs, not public experimental APIs. [Here’s one way to do it](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#comment-43619), and [here’s a PR that proposes private cross-package APIs](https://github.com/WordPress/gutenberg/pull/43386). * Exclude the features in progress from the production builds, e.g. using feature flags * Stabilize the APIs that are production-ready * Remove the abandoned APIs * …probably even more 122. ![](https://secure.gravatar.com/avatar/e1a850bca164e3d29c1d8ae8117fa4b341ed150ea4d8ab29a285726c944c453b? s=32&d=mm&r=g) 123. [Marius L. J.](https://profiles.wordpress.org/clorith/) 4:34 pm _on_ August 20, 2022 124. I’ve already voiced my agreement on the GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the‘ pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. [https://github.com/](https://github.com/) ticketticket Created for both bug reports and feature development on the bug tracker. that we definitely should move forward with a more backwards compatible approach to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. releases, but I’ll take it a step further, to ensure that all backwards compatibility is considered/discussed here; 125. Will this new proposed backwards compatible re-enforcement be limited to the use of unstable/experimental APIs in the JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. code, or will it be extended to the whole GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) codebase, such as (but not limited to): 126. * HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. markup of blocks (new designs means themes may need to redo styling) * Core-provided styling (if core adds/removes styling, themes need to then be ahead of the curve to modify how they reactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. [https://reactjs.org](https://reactjs.org/) to this) * Non-JS APIs and behavior (such as the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher function `register_block_type`/`register_block_type_from_metadata`) 127. These are areas which have in the past also broken that compatibility promise, where an update has suddenly led to site styling breaking, because core shipped a new default class and style for background colors in buttons, or blocks being reported as not existing in the editor because `register_block_type` now requires that a blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. be registered both in JS and PHP, and that this registration of declare all attributes identically (making two quick examples for emphasis only). 128. ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) 129. [zieladam](https://profiles.wordpress.org/zieladam/) 1:25 pm _on_ August 22, 2022 130. I published this proposal to help WordPress deliver on its Backwards Compatibility promise. 131. **But what exactly is the WordPress Backwards Compatibility promise?** 132. If it is to almost never remove a public APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. from WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., then there’s just one way to comply: stop merging public __experimental APIs into WordPress core. 133. However, this isn’t the shared understanding among the contributors here. Some said it’s okay to ship and remove an occasional __experimental API, and other said it’s not okay to do it. 134. **So is it okay to remove public APIs from the WordPress core, or is it not?** 135. I don’t think this proposal can be settled without finding canonical answers to these larger questions. This means more discussion, for sure, but then what?** How will we know when the debate is settled?** In other projects, contributors vote on RFCs. What happens in WordPress? 136. * ![](https://secure.gravatar.com/avatar/e7b27b178ff5a141aa26976d2f17272a6483508f92d4fc6a210bcf8df560921f? s=32&d=mm&r=g) * [Courtney Robertson](https://profiles.wordpress.org/courane01/) 7:13 pm _on_ August 23, 2022 * [@francina](https://profiles.wordpress.org/francina/) had a somewhat related post about decision making: [https://make.wordpress.org/community/2017/08/31/decision-making-process-discussion-summary-and-proposal/](https://make.wordpress.org/community/2017/08/31/decision-making-process-discussion-summary-and-proposal/) 137. ![](https://secure.gravatar.com/avatar/7d5dd0067aa748d9648f44813a03eaeebc1a153764693749a4add2e82e308535? s=32&d=mm&r=g) 138. [George Hotelling](https://profiles.wordpress.org/revgeorge/) 6:02 pm _on_ September 12, 2022 139. While not a complete solution, I believe we should add a label in the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress. org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. and theme directories to indicate which add-ons use unstable APIs. 140. One of the problems that [@zieladam](https://profiles.wordpress.org/zieladam/) proposes addressing is that plugins and themes are using unstable APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. When a 3rd party uses one of these APIs it may break with little or no notice, which can frustrate end users. WordPress has a reputation for bending over backward to stop things from breaking from an upgrade. Experimental APIs used outside of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. can break that trust. 141. At the same time, if we do not ship any experimental APIs we cannot iterate as quickly as we are currently doing. 142. Adding a label would serve as notice to the end-user that the plugin/blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience./theme they are installing may break when WordPress or GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) updates. I see this similar to how app stores will block apps that use internal APIs. 143. This approach does not _stop_ 3rd parties from using unstable APIs but the label provides them an incentive not to use them. It also empowers site owners to know what kind of code they are installing. If there is no other way for a plugin to accomplish what they want, they can still use it, but they will get some sort of “unstable” label in the directory. This should be made scary enough that the authors look for another way to achieve their goal, or open issues requesting stabilizing the API they want. 144. One potential downside is that it may tacitly endorse unstable APIs, which can lead to more plugins and themes using those APIs. End users will be surprised when things break on upgrade and blame WordPress instead of the 3rd-party author. 145. People may get overly comfortable installing “unstable” plugins because they use rarely-changing experimental APIs. When the API does change and their site breaks, they will be upset. “We tried to warn you with the label” will be neither comforting nor helpful. 146. Still, I think it’s better that we tell people when they are installing unstable code. 147. ![](https://secure.gravatar.com/avatar/82f8b6f87f741a78784d7453f52734516053272d36325c5cf23b24df0baffe8d? s=32&d=mm&r=g) 148. [zieladam](https://profiles.wordpress.org/zieladam/) 6:30 am _on_ October 28, 2022 149. This was quite a discussion, thank you everyone! 150. Accommodating everyone’s goals isn’t easy, but I believe there is a way forward. 151. The new [`@wordpress/experiments`](https://github.com/WordPress/gutenberg/pull/43386) package enables sharing internal private APIs across the `@wordpress` packages without calling them experimental and exposing as public. This way GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) can remain the agile garden of innovation and still only ship the stable APIs to WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. 152. Tactically speaking, the experiments package is a low-level building blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.. There is [an ongoing effort](https://github.com/WordPress/gutenberg/pull/44521) to provide specific helpers for private selectors, private actions, private ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. [https://reactjs.org](https://reactjs.org/) components, and so on. I hope it will be the catalyst for a WordPress release where all new APIs are stable. 153. A comment in an old post can only reach so many people. In November I will write another post to expand on these ideas (I am travelling at the moment). Comments are closed. # Post navigation [← Standardize npm script naming in the Gutenberg project](https://make.wordpress.org/core/2022/08/10/standardize-npm-script-naming-in-the-gutenberg-project/) [Dev Chat Summary, August 10, 2022 →](https://make.wordpress.org/core/2022/08/10/dev-chat-summary-august-10-2022/)