From 7b901324eec4785b6aacb6c496d4bef4f06a4a71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Mon, 26 Sep 2022 20:04:06 +1000 Subject: [PATCH 1/8] Add the README.md and CHANGELOG.md files to packages/experiments and use the correct name in package.json --- packages/experiments/CHANGELOG.md | 5 ++++ packages/experiments/README.md | 49 +++++++++++++++++++++++++++++++ packages/experiments/package.json | 2 +- 3 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 packages/experiments/CHANGELOG.md create mode 100644 packages/experiments/README.md diff --git a/packages/experiments/CHANGELOG.md b/packages/experiments/CHANGELOG.md new file mode 100644 index 0000000000000..256046894e354 --- /dev/null +++ b/packages/experiments/CHANGELOG.md @@ -0,0 +1,5 @@ + + +## Unreleased + +– Package created. diff --git a/packages/experiments/README.md b/packages/experiments/README.md new file mode 100644 index 0000000000000..c382e4fbae69b --- /dev/null +++ b/packages/experiments/README.md @@ -0,0 +1,49 @@ +# Experiments + +Private `__experimental` APIs that are not [exposed publicly plugin authors](https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/#respond). + +This package acts as a "dealer" that only allows WordPress packages to use the experimental APIs. + +Each package needs to start by registering itself: + +```js +const { register } = + __dangerousOptInToUnstableAPIsOnlyForCoreModules( + 'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.', + '@wordpress/blocks' + ); +``` + +The function name communicates that plugins are not supposed to use it. To make double and triple sure, the first argument must be that exact consent string, and the second argument must be a known `@wordpress` package that hasn't opted in yet – otherwise an error is thrown. + +Expose a new `__experimental` API as follows: + +```js +export const __experiments = register( { __unstableGetInnerBlocksProps } ) +``` + +Consume the registered `__experimental` APIs as follows: + +```js +// In the @wordpress/block-editor package: +import { __experiments as blocksExperiments } from '@wordpress/blocks'; +const { unlock } = + __dangerousOptInToUnstableAPIsOnlyForCoreModules( + 'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.', + '@wordpress/block-editor' + ); + +const { __unstableGetInnerBlocksProps } = unlock( blocksExperiments ); +``` + +All new experimental APIs should be shipped as **private** using this method. + +The **public** experimental APIs that have already been shipped in a stable WordPress version should +remain accessible via `window.wp`. Please do not create new ones. + +A determined developer who would want to use the private experimental APIs at all costs would have to: + +* Realize a private importing system exists +* Read the code where the risks would be spelled out in capital letters +* Explicitly type out he or she is aware of the consequences +* Pretend to register a `@wordpress` package (and trigger an error as soon as the real package is loaded) diff --git a/packages/experiments/package.json b/packages/experiments/package.json index 85310d8256532..f50546b70c662 100644 --- a/packages/experiments/package.json +++ b/packages/experiments/package.json @@ -1,5 +1,5 @@ { - "name": "@wordpress/dependency-injection", + "name": "@wordpress/experiments", "version": "0.0.1", "description": "Dependency Injection container for WordPress.", "author": "The WordPress Contributors", From de3d71c9e2f3405813c180e2e3e6e94549089c64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Mon, 26 Sep 2022 20:05:17 +1000 Subject: [PATCH 2/8] Remove the consent string from README.md --- packages/experiments/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/experiments/README.md b/packages/experiments/README.md index c382e4fbae69b..ee910585f8b2e 100644 --- a/packages/experiments/README.md +++ b/packages/experiments/README.md @@ -9,7 +9,7 @@ Each package needs to start by registering itself: ```js const { register } = __dangerousOptInToUnstableAPIsOnlyForCoreModules( - 'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.', + '', // See index.js '@wordpress/blocks' ); ``` @@ -29,7 +29,7 @@ Consume the registered `__experimental` APIs as follows: import { __experiments as blocksExperiments } from '@wordpress/blocks'; const { unlock } = __dangerousOptInToUnstableAPIsOnlyForCoreModules( - 'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.', + '', // See index.js '@wordpress/block-editor' ); From 963bf925400caaa952a3ab21c2ff9cfed52dfdc4 Mon Sep 17 00:00:00 2001 From: Adam Zielinski Date: Mon, 26 Sep 2022 20:27:02 +1000 Subject: [PATCH 3/8] Update packages/experiments/package.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- packages/experiments/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/experiments/package.json b/packages/experiments/package.json index f50546b70c662..860ae5ac6d28f 100644 --- a/packages/experiments/package.json +++ b/packages/experiments/package.json @@ -1,7 +1,7 @@ { "name": "@wordpress/experiments", "version": "0.0.1", - "description": "Dependency Injection container for WordPress.", + "description": "Internal experimental APIs for WordPress core.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "keywords": [ From 3ee473a9c78db2ae613170b0c1dd855bc30f47f8 Mon Sep 17 00:00:00 2001 From: Adam Zielinski Date: Mon, 26 Sep 2022 20:27:15 +1000 Subject: [PATCH 4/8] Update packages/experiments/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- packages/experiments/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/experiments/README.md b/packages/experiments/README.md index ee910585f8b2e..f3eb733497b8d 100644 --- a/packages/experiments/README.md +++ b/packages/experiments/README.md @@ -38,8 +38,7 @@ const { __unstableGetInnerBlocksProps } = unlock( blocksExperiments ); All new experimental APIs should be shipped as **private** using this method. -The **public** experimental APIs that have already been shipped in a stable WordPress version should -remain accessible via `window.wp`. Please do not create new ones. +The **public** experimental APIs that have already been shipped in a stable WordPress version should remain accessible via `window.wp`. Please do not create new ones. A determined developer who would want to use the private experimental APIs at all costs would have to: From 1ef32b7a856c06aa1d4c4ff6dc538664d87501c6 Mon Sep 17 00:00:00 2001 From: Adam Zielinski Date: Mon, 26 Sep 2022 20:27:29 +1000 Subject: [PATCH 5/8] Update packages/experiments/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- packages/experiments/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/experiments/README.md b/packages/experiments/README.md index f3eb733497b8d..72a85396f90f0 100644 --- a/packages/experiments/README.md +++ b/packages/experiments/README.md @@ -46,3 +46,11 @@ A determined developer who would want to use the private experimental APIs at al * Read the code where the risks would be spelled out in capital letters * Explicitly type out he or she is aware of the consequences * Pretend to register a `@wordpress` package (and trigger an error as soon as the real package is loaded) + +## Contributing to this package + +This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. + +To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md). + +

Code is Poetry.

From f963c984d4d81653534f4062c72d7d68087c7e6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Mon, 26 Sep 2022 20:33:06 +1000 Subject: [PATCH 6/8] Adjust two more mentions of the injections package --- packages/experiments/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/experiments/package.json b/packages/experiments/package.json index 860ae5ac6d28f..9f27183fb1be9 100644 --- a/packages/experiments/package.json +++ b/packages/experiments/package.json @@ -10,11 +10,11 @@ "dom", "utils" ], - "homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/dependency-injection/README.md", + "homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/experiments/README.md", "repository": { "type": "git", "url": "https://github.com/WordPress/gutenberg.git", - "directory": "packages/injection" + "directory": "packages/experiments" }, "bugs": { "url": "https://github.com/WordPress/gutenberg/issues" From dd25d57a6a40b276db51d60744991a3df61434ea Mon Sep 17 00:00:00 2001 From: Adam Zielinski Date: Tue, 27 Sep 2022 09:39:19 +1000 Subject: [PATCH 7/8] Update packages/experiments/README.md Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com> --- packages/experiments/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/experiments/README.md b/packages/experiments/README.md index 72a85396f90f0..fbdaf59fd0a92 100644 --- a/packages/experiments/README.md +++ b/packages/experiments/README.md @@ -47,6 +47,10 @@ A determined developer who would want to use the private experimental APIs at al * Explicitly type out he or she is aware of the consequences * Pretend to register a `@wordpress` package (and trigger an error as soon as the real package is loaded) +Dangerously opting in to using these APIs by theme and plugin developers is not recommended. Furthermore, the WordPress Core philosophy to strive to maintain backward compatibility for third-party developers **does not apply** to experimental APIs registered via this package. + +The consent string for opting in to these APIs may change at any time and without notice. This change will break existing third-party code. Such a change may occur in either a major or minor release. + ## Contributing to this package This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. From c9a5f680900856fff46b0e5edf28db1d53aea009 Mon Sep 17 00:00:00 2001 From: Adam Zielinski Date: Tue, 27 Sep 2022 09:39:26 +1000 Subject: [PATCH 8/8] Update packages/experiments/README.md Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com> --- packages/experiments/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/experiments/README.md b/packages/experiments/README.md index fbdaf59fd0a92..fe6221588ecc1 100644 --- a/packages/experiments/README.md +++ b/packages/experiments/README.md @@ -9,7 +9,7 @@ Each package needs to start by registering itself: ```js const { register } = __dangerousOptInToUnstableAPIsOnlyForCoreModules( - '', // See index.js + '', // See index.js, this may change without notice. '@wordpress/blocks' ); ```