From b903a70b4d0caa2f2be057650065e30e8395804f Mon Sep 17 00:00:00 2001 From: ramonjd Date: Mon, 21 Nov 2022 16:37:37 +1100 Subject: [PATCH 1/4] Initial commit. --- packages/style-engine/CONTRIBUTING.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 packages/style-engine/CONTRIBUTING.md diff --git a/packages/style-engine/CONTRIBUTING.md b/packages/style-engine/CONTRIBUTING.md new file mode 100644 index 0000000000000..897c3fe33a61a --- /dev/null +++ b/packages/style-engine/CONTRIBUTING.md @@ -0,0 +1,20 @@ +# Contributing + +This document contains information you might need to know when extending or debugging Style Engine code. + +## Workflow and build tooling + +The Style Engine PHP and Javascript (JS) files exist inside the `style-engine` package. + +In order to use the Style Engine in the Block Editor, these files must be compiled (in the case of JS) and copied to the build folder. + +When running the `npm run dev` script for example, webpack watches out for changes and will recompile/copy files as necessary if any changes are detected according to the rules in [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js). + +No other configuration is required for JS: webpack will compile and export the Style Engine code as it does with all dependencies listed in [package.json](https://github.com/WordPress/gutenberg/tree/HEAD/package.json). + +The PHP files for packages, however, have a couple of extra steps during the build process: + +1. Functions with the `wp_` prefix are replaced with `gutenberg_`. So, for example, `wp_some_function` becomes `gutenberg_some_function` in the build directory. The reason for this is so that the Block Editor can call Style Engine functions that may have evolved since, or have not yet been included in, any WordPress release. +2. + +## Testing From f3bf421ae0506c945638902e73b4ef13857d62b8 Mon Sep 17 00:00:00 2001 From: ramonjd Date: Mon, 21 Nov 2022 17:32:50 +1100 Subject: [PATCH 2/4] Adding `@group` to style engine tests so they can be run altogether Finishing up first draft of CONTRIBUTING.md notes --- packages/style-engine/CONTRIBUTING.md | 20 ++++++++++++++++++- packages/style-engine/README.md | 2 ++ ...-wp-style-engine-css-declarations-test.php | 1 + .../class-wp-style-engine-css-rule-test.php | 1 + ...s-wp-style-engine-css-rules-store-test.php | 1 + .../class-wp-style-engine-processor-test.php | 1 + phpunit/style-engine/style-engine-test.php | 2 ++ 7 files changed, 27 insertions(+), 1 deletion(-) diff --git a/packages/style-engine/CONTRIBUTING.md b/packages/style-engine/CONTRIBUTING.md index 897c3fe33a61a..9d8b6fddcd0da 100644 --- a/packages/style-engine/CONTRIBUTING.md +++ b/packages/style-engine/CONTRIBUTING.md @@ -15,6 +15,24 @@ No other configuration is required for JS: webpack will compile and export the S The PHP files for packages, however, have a couple of extra steps during the build process: 1. Functions with the `wp_` prefix are replaced with `gutenberg_`. So, for example, `wp_some_function` becomes `gutenberg_some_function` in the build directory. The reason for this is so that the Block Editor can call Style Engine functions that may have evolved since, or have not yet been included in, any WordPress release. -2. +2. For the same reasons, classes are given a `_Gutenberg` suffix: `WP_Style_Engine` becomes `WP_Style_Engin_Gutenberg`. The [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js) contains a static list of PHP classes (`bundledPackagesPhpConfig`) that have to be copied and renamed during build. If you create a new PHP class in the Style Engine package, you should add your classname to the `replaceClasses` array. + +Remember: all PHP functions and methods inside the Style Engine package should use `wp_/WP_` prefixes. + +When updating existing PHP functions or methods, it's important to check the Block Editor codebase for calls to the equivalent `wp_` functions or classes as they may have to be updated to refer to `gutenberg_` or `_Gutenberg` in order for the updates to take effect. ## Testing + +[JS unit tests](https://github.com/WordPress/gutenberg/tree/HEAD/packages/style-engine/src/test) are stored next to the source code in the `style-engine` package directory. + +To start the JS unit tests, run: + +`npm run test:unit packages/style-engine/src/test/` + +[PHP unit tests](https://github.com/WordPress/gutenberg/tree/HEAD/phpunit/style-engine) on the other hand are located in the `phpunit` directory. + +In order to test the latest version of the Style Engine and avoid conflicts with existing Core equivalents, all PHP unit tests call the `gutenberg_` functions and `_Gutenberg` classes. Therefore, the PHP files should be parsed and copied to the build folder before running tests. During development, this will happen as part of the `npm run dev` script. You can also trigger a build by executing `npm run build`. + +To start the PHP unit tests, run: + +`npm run test:unit:php -- --group style-engine` diff --git a/packages/style-engine/README.md b/packages/style-engine/README.md index 317e48e0c37c4..999fab2aa835e 100644 --- a/packages/style-engine/README.md +++ b/packages/style-engine/README.md @@ -19,6 +19,8 @@ Upcoming tasks on the roadmap include, but are not limited to, the following: For more information about the roadmap, please refer to [Block editor styles: initiatives and goals](https://make.wordpress.org/core/2022/06/24/block-editor-styles-initiatives-and-goals/) and the [Github project board](https://github.com/orgs/WordPress/projects/19). +If you're making changes or additions to the Style Engine, please take a moment to read the [notes on contributing](https://github.com/WordPress/gutenberg/tree/HEAD/packages/style-engine/CONTRIBUTING.md). + ## Backend API ### wp_style_engine_get_styles() diff --git a/phpunit/style-engine/class-wp-style-engine-css-declarations-test.php b/phpunit/style-engine/class-wp-style-engine-css-declarations-test.php index 5380cc81d5831..011de140d0892 100644 --- a/phpunit/style-engine/class-wp-style-engine-css-declarations-test.php +++ b/phpunit/style-engine/class-wp-style-engine-css-declarations-test.php @@ -9,6 +9,7 @@ /** * Tests registering, storing and generating CSS declarations. * + * @group style-engine * @coversDefaultClass WP_Style_Engine_CSS_Declarations_Gutenberg */ class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase { diff --git a/phpunit/style-engine/class-wp-style-engine-css-rule-test.php b/phpunit/style-engine/class-wp-style-engine-css-rule-test.php index 26ea41c7ce830..02482c70e4d84 100644 --- a/phpunit/style-engine/class-wp-style-engine-css-rule-test.php +++ b/phpunit/style-engine/class-wp-style-engine-css-rule-test.php @@ -9,6 +9,7 @@ /** * Tests for registering, storing and generating CSS rules. * + * @group style-engine * @coversDefaultClass WP_Style_Engine_CSS_Rule_Gutenberg */ class WP_Style_Engine_CSS_Rule_Test extends WP_UnitTestCase { diff --git a/phpunit/style-engine/class-wp-style-engine-css-rules-store-test.php b/phpunit/style-engine/class-wp-style-engine-css-rules-store-test.php index 700f63c556c25..8529bff78e22c 100644 --- a/phpunit/style-engine/class-wp-style-engine-css-rules-store-test.php +++ b/phpunit/style-engine/class-wp-style-engine-css-rules-store-test.php @@ -9,6 +9,7 @@ /** * Tests for registering, storing and retrieving a collection of CSS Rules (a store). * + * @group style-engine * @coversDefaultClass WP_Style_Engine_CSS_Rules_Store_Gutenberg */ class WP_Style_Engine_CSS_Rules_Store_Test extends WP_UnitTestCase { diff --git a/phpunit/style-engine/class-wp-style-engine-processor-test.php b/phpunit/style-engine/class-wp-style-engine-processor-test.php index cfbde08704bdc..18392f5156fcc 100644 --- a/phpunit/style-engine/class-wp-style-engine-processor-test.php +++ b/phpunit/style-engine/class-wp-style-engine-processor-test.php @@ -9,6 +9,7 @@ /** * Tests for compiling and rendering styles from a store of CSS rules. * + * @group style-engine * @coversDefaultClass WP_Style_Engine_Processor_Gutenberg */ class WP_Style_Engine_Processor_Test extends WP_UnitTestCase { diff --git a/phpunit/style-engine/style-engine-test.php b/phpunit/style-engine/style-engine-test.php index 5f4c57453e8a8..66d8dd6286527 100644 --- a/phpunit/style-engine/style-engine-test.php +++ b/phpunit/style-engine/style-engine-test.php @@ -8,6 +8,8 @@ /** * Tests for registering, storing and generating styles. + * + * @group style-engine */ class WP_Style_Engine_Test extends WP_UnitTestCase { /** From 851c4dc0900af4e5dd2cd22ce173bd3f612534ab Mon Sep 17 00:00:00 2001 From: ramonjd Date: Mon, 21 Nov 2022 17:40:34 +1100 Subject: [PATCH 3/4] Formattings --- packages/style-engine/CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/style-engine/CONTRIBUTING.md b/packages/style-engine/CONTRIBUTING.md index 9d8b6fddcd0da..923ae255e1ff2 100644 --- a/packages/style-engine/CONTRIBUTING.md +++ b/packages/style-engine/CONTRIBUTING.md @@ -6,7 +6,7 @@ This document contains information you might need to know when extending or debu The Style Engine PHP and Javascript (JS) files exist inside the `style-engine` package. -In order to use the Style Engine in the Block Editor, these files must be compiled (in the case of JS) and copied to the build folder. +In order to use the Style Engine in the Block Editor, these files must be compiled (in the case of JS) and copied to the build folder. When running the `npm run dev` script for example, webpack watches out for changes and will recompile/copy files as necessary if any changes are detected according to the rules in [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js). @@ -31,7 +31,9 @@ To start the JS unit tests, run: [PHP unit tests](https://github.com/WordPress/gutenberg/tree/HEAD/phpunit/style-engine) on the other hand are located in the `phpunit` directory. -In order to test the latest version of the Style Engine and avoid conflicts with existing Core equivalents, all PHP unit tests call the `gutenberg_` functions and `_Gutenberg` classes. Therefore, the PHP files should be parsed and copied to the build folder before running tests. During development, this will happen as part of the `npm run dev` script. You can also trigger a build by executing `npm run build`. +In order to test the latest version of the Style Engine and avoid conflicts with existing Core equivalents, all PHP unit tests call the `gutenberg_` functions and `_Gutenberg` classes. + +Therefore, Style Engine PHP source files should be parsed and copied to the build folder before running tests. During development, this will happen as part of the `npm run dev` script. You can also trigger a build by executing `npm run build`. To start the PHP unit tests, run: From 80e01691d7ced548a906d994997c634e6951b32c Mon Sep 17 00:00:00 2001 From: Ramon Date: Mon, 21 Nov 2022 17:58:28 +1100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Andrew Serong <14988353+andrewserong@users.noreply.github.com> --- packages/style-engine/CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/style-engine/CONTRIBUTING.md b/packages/style-engine/CONTRIBUTING.md index 923ae255e1ff2..70bfddb8eb501 100644 --- a/packages/style-engine/CONTRIBUTING.md +++ b/packages/style-engine/CONTRIBUTING.md @@ -8,16 +8,16 @@ The Style Engine PHP and Javascript (JS) files exist inside the `style-engine` p In order to use the Style Engine in the Block Editor, these files must be compiled (in the case of JS) and copied to the build folder. -When running the `npm run dev` script for example, webpack watches out for changes and will recompile/copy files as necessary if any changes are detected according to the rules in [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js). +When running the `npm run dev` script for example, webpack watches out for changes and will recompile/copy files as necessary if any changes are detected according to the rules in the [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js). No other configuration is required for JS: webpack will compile and export the Style Engine code as it does with all dependencies listed in [package.json](https://github.com/WordPress/gutenberg/tree/HEAD/package.json). The PHP files for packages, however, have a couple of extra steps during the build process: 1. Functions with the `wp_` prefix are replaced with `gutenberg_`. So, for example, `wp_some_function` becomes `gutenberg_some_function` in the build directory. The reason for this is so that the Block Editor can call Style Engine functions that may have evolved since, or have not yet been included in, any WordPress release. -2. For the same reasons, classes are given a `_Gutenberg` suffix: `WP_Style_Engine` becomes `WP_Style_Engin_Gutenberg`. The [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js) contains a static list of PHP classes (`bundledPackagesPhpConfig`) that have to be copied and renamed during build. If you create a new PHP class in the Style Engine package, you should add your classname to the `replaceClasses` array. +2. For the same reasons, classes are given a `_Gutenberg` suffix: `WP_Style_Engine` becomes `WP_Style_Engine_Gutenberg`. The [packages webpack config](https://github.com/WordPress/gutenberg/tree/HEAD/tools/webpack/packages.js) contains a static list of PHP classes (`bundledPackagesPhpConfig`) that have to be copied and renamed during build. If you create a new PHP class in the Style Engine package, you should add your class name to the `replaceClasses` array. -Remember: all PHP functions and methods inside the Style Engine package should use `wp_/WP_` prefixes. +Remember: all PHP functions and methods inside the Style Engine package should use `wp_/WP_` prefixes. Usage outside of the package in Gutenberg can reference the `gutenberg` prefixes or suffixes from the built files. When updating existing PHP functions or methods, it's important to check the Block Editor codebase for calls to the equivalent `wp_` functions or classes as they may have to be updated to refer to `gutenberg_` or `_Gutenberg` in order for the updates to take effect. @@ -29,7 +29,7 @@ To start the JS unit tests, run: `npm run test:unit packages/style-engine/src/test/` -[PHP unit tests](https://github.com/WordPress/gutenberg/tree/HEAD/phpunit/style-engine) on the other hand are located in the `phpunit` directory. +[PHP unit tests](https://github.com/WordPress/gutenberg/tree/HEAD/phpunit/style-engine) are located in the root `phpunit` directory. In order to test the latest version of the Style Engine and avoid conflicts with existing Core equivalents, all PHP unit tests call the `gutenberg_` functions and `_Gutenberg` classes.