From 0ea76c2ffb2273ac2c9b9172f4c31c3ba84daae6 Mon Sep 17 00:00:00 2001 From: piinthecloud Date: Wed, 4 Sep 2024 19:11:35 +0200 Subject: [PATCH] fixes and updates (#51144) * fixes and updates * add changelog * update quotes * fix broken whitespace * Update plugins/woocommerce/changelog/update-contrib-docs-and-fixes Co-authored-by: Karol Manijak <20098064+kmanijak@users.noreply.github.com> --------- Co-authored-by: Jacklyn Biggin Co-authored-by: Karol Manijak <20098064+kmanijak@users.noreply.github.com> --- .../configuring_special_tax_scenarios.md | 2 +- docs/contributing-docs/contributing-docs.md | 6 ++++++ docs/docs-manifest.json | 14 +++++++------- .../guide-large-store.md | 8 ++++---- docs/performance/performance-best-practices.md | 2 +- .../register-product-collection.md | 8 ++++---- docs/theme-development/template-structure.md | 6 +++--- docs/ux-guidelines-extensions/navigation.md | 5 +---- .../changelog/update-contrib-docs-and-fixes | 4 ++++ .../src/StoreApi/docs/guiding-principles.md | 2 +- 10 files changed, 32 insertions(+), 25 deletions(-) create mode 100644 plugins/woocommerce/changelog/update-contrib-docs-and-fixes diff --git a/docs/code-snippets/configuring_special_tax_scenarios.md b/docs/code-snippets/configuring_special_tax_scenarios.md index 1dc991844d8..34a92b2a640 100644 --- a/docs/code-snippets/configuring_special_tax_scenarios.md +++ b/docs/code-snippets/configuring_special_tax_scenarios.md @@ -38,7 +38,7 @@ function big_apple_get_tax_class( $tax_class, $product ) { Some merchants may require different tax rates to be applied based on a customer role to accommodate for wholesale status or tax exemption. -To enable this functionality, add the following snippet to your child theme's functions.php file or via a code snippet plugin. In this snippet, users with “administrator” capabilities will be assigned the **Zero rate tax class**. Adjust it according to your requirements. +To enable this functionality, add the following snippet to your child theme's functions.php file or via a code snippet plugin. In this snippet, users with "administrator" capabilities will be assigned the **Zero rate tax class**. Adjust it according to your requirements. ```php ) symbol named references. diff --git a/docs/docs-manifest.json b/docs/docs-manifest.json index 6ef73f9e485..76b99e36923 100644 --- a/docs/docs-manifest.json +++ b/docs/docs-manifest.json @@ -414,7 +414,7 @@ "menu_title": "Configuring special tax scenarios", "tags": "code-snippet, tax", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/code-snippets/configuring_special_tax_scenarios.md", - "hash": "acce5111eb917b7381d9bdcb260c72870e89d723195b86522050032741c5107c", + "hash": "c2459568db70b97d9a901c83eecb7737746499fe03cc84133aab3cf981b5c96a", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/code-snippets/configuring_special_tax_scenarios.md", "id": "a8ab8b6734ba2ac5af7c6653635d15548abdab2a" }, @@ -594,7 +594,7 @@ "post_title": "Contributing Technical Documentation", "menu_title": "Contributing Docs", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/contributing-docs/contributing-docs.md", - "hash": "ee2eed4bc33ccbc4a84a2c73ee503f2df5a92183013e3f703bb439edab0a3fe3", + "hash": "6733ba23f82a6e784ef10e2862aa3afd8a61e32181e157f67ccabfc8354aa989", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/contributing-docs/contributing-docs.md", "id": "71c1a72bfd4d5ae6aa656d4264b1bf3beb6eca1c" } @@ -939,7 +939,7 @@ "menu_title": "Enable HPOS for large stores", "tags": "how-to", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/high-performance-order-storage/guide-large-store.md", - "hash": "8bcae74d27e3a4ee9a902719c7e8d5aec4a4d82d7c14acd8665a72b9d4758181", + "hash": "1e144ac0d0a7c869093533bf94a1f218a42930a3f3edcbcfdd1210448243a992", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/high-performance-order-storage/guide-large-store.md", "id": "b6156ac7b77d75022867e9ebb968bc9c1c35f0da" }, @@ -1033,7 +1033,7 @@ "menu_title": "Performance best practices", "tags": "reference", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/performance/performance-best-practices.md", - "hash": "5af1f4e4085e85a1693390f40e238cbd6a4a0b7d5d304afdda935c34fed97c64", + "hash": "3c49b5553e99b64ecdbdad565866479f7af5e474dbbcc9aa36d711c02d8b0906", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/performance/performance-best-practices.md", "id": "35bda1cd7068d6179a9e46cca8d7dc2694d0df96" } @@ -1451,7 +1451,7 @@ { "post_title": "Template structure & Overriding templates via a theme", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/theme-development/template-structure.md", - "hash": "ff781eff7998ea93723f644bddd4f6da6f73c635bcfc3cd46950f03a8b83b26c", + "hash": "0d026ed5e9706b97dd03d6f7dc86aeb580b11549fa99c9d6f906bbca6f136a01", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/theme-development/template-structure.md", "id": "34bfebec9fc45e680976814928a7b8a1778af14e" }, @@ -1554,7 +1554,7 @@ "post_title": "WooCommerce Extension Guidelines - Navigation", "menu_title": "Navigation", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/ux-guidelines-extensions/navigation.md", - "hash": "f14cbd3750451934d173ec43aa996067699bdd8fc05f5c34097d1967a79145db", + "hash": "9c5313a31ebe26909a2cfaaa0bcfcdc9d5a0855ac0ddb9808832524be313ebb6", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/ux-guidelines-extensions/navigation.md", "id": "9922abbcea787a91b3360f49fa53d5402a604e6b" }, @@ -1804,5 +1804,5 @@ "categories": [] } ], - "hash": "2ecf48b6181dae0526b3858df889bce4e6ee425e10f2c43d151771d845c5a948" + "hash": "cbe507d24f0d6ae827c01a98fd2d7c6e8db74053a7b3db869c6941dd7442d250" } \ No newline at end of file diff --git a/docs/high-performance-order-storage/guide-large-store.md b/docs/high-performance-order-storage/guide-large-store.md index 75583f42615..dd2b40d159e 100644 --- a/docs/high-performance-order-storage/guide-large-store.md +++ b/docs/high-performance-order-storage/guide-large-store.md @@ -87,7 +87,7 @@ Also, we didn't see a noticeable negative performance impact when keeping synchr ### Switch to HPOS as authoritative -It's time to switch to HPOS. Go to **WooCommerce > Settings > Advanced > Features** and set HPOS to be authoritative (select “**Use the WooCommerce orders tables**"). +It's time to switch to HPOS. Go to **WooCommerce > Settings > Advanced > Features** and set HPOS to be authoritative (select "**Use the WooCommerce orders tables**"). As mentioned above, don't turn off synchronization yet. If there are any issues, the system can be instantaneously reverted to the posts table, resulting in no downtime. @@ -107,7 +107,7 @@ We disable sync on read first because it demands more resources. If your site is ### Switch off sync on write -If everything is working as expected, you can disable sync on write as well. Given sync on read was already disabled, you can disable sync altogether from the settings. As usual, go to **WooCommerce > Settings > Advanced > Features**, and uncheck **“Enable compatibility mode"**. +If everything is working as expected, you can disable sync on write as well. Given sync on read was already disabled, you can disable sync altogether from the settings. As usual, go to **WooCommerce > Settings > Advanced > Features**, and uncheck **"Enable compatibility mode"**. On our high-volume site, we fully disabled sync after 1 week. We still run some manual synchronization (via `wp wc cot sync`) periodically so that we have the opportunity to fall back to posts immediately should anything happen. @@ -118,11 +118,11 @@ Now with synchronization fully disabled, test out various critical flows, check ### Review: Phase 3 Checklist 1. [ ] Plan to be online and monitoring your live site for a period of time. -2. [ ] Enable synchronization with posts set as authoritative: in **WooCommerce > Settings > Advanced > Features** > select “**Use the WordPress posts tables**". +2. [ ] Enable synchronization with posts set as authoritative: in **WooCommerce > Settings > Advanced > Features** > select "**Use the WordPress posts tables**". 3. [ ] Start migration via CLI using the `wp wc cot sync` command. 4. [ ] Monitor for errors during migration; halt or resume as necessary. 5. [ ] Verify migrated data integrity using the verify command `wp wc cot verify_cot_data`. -6. [ ] Enable synchronization with HPOS set as authoritative: in **WooCommerce > Settings > Advanced > Features** > select “Use the **WooCommerce orders tables**". +6. [ ] Enable synchronization with HPOS set as authoritative: in **WooCommerce > Settings > Advanced > Features** > select "Use the **WooCommerce orders tables**". 7. [ ] Test all critical flows, perform checkouts with multiple payment methods, and verify order data accuracy. 8. [ ] Monitor support tickets for any issues. 9. [ ] Disable synchronization on read using the provided snippet: `add_filter( 'woocommerce_hpos_enable_sync_on_read', '__return_false' );` diff --git a/docs/performance/performance-best-practices.md b/docs/performance/performance-best-practices.md index a88896370c4..b47f828754e 100644 --- a/docs/performance/performance-best-practices.md +++ b/docs/performance/performance-best-practices.md @@ -20,7 +20,7 @@ For WooCommerce extensions, performance optimization means ensuring that your co ## Benchmarking Performance -Setting clear performance benchmarks is essential for development and continuous improvement of WooCommerce extensions. A recommended performance standard is achieving a Chrome Core Web Vitals "Performance" score of 90 or above on Woo Express, using tools like the [Chrome Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/). +Setting clear performance benchmarks is essential for development and continuous improvement of WooCommerce extensions. A recommended performance standard is achieving a Chrome Core Web Vitals "Performance" score of 90 or above on a simple Woo site, using tools like the [Chrome Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/). ### Using Accessible Tools for Benchmarking diff --git a/docs/product-collection-block/register-product-collection.md b/docs/product-collection-block/register-product-collection.md index 9f96f791262..677668ba71e 100644 --- a/docs/product-collection-block/register-product-collection.md +++ b/docs/product-collection-block/register-product-collection.md @@ -6,20 +6,20 @@ tags: how-to # Register Product Collection -The `__experimentalRegisterProductCollection` function is part of the `@woocommerce/blocks-registry` package. This function allows third party developers to register a new collection. This function accepts most of the arguments that are accepted by [Block Variation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation). +The `__experimentalRegisterProductCollection` function is part of the `@woocommerce/blocks-registry` package. This function allows third party developers to register a new collection. This function accepts most of the arguments that are accepted by [Block Variation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation). > [!WARNING] > It's experimental and may change in the future. Please use it with caution. **There are two ways to use this function:** -1. Using `@woocommerce/dependency-extraction-webpack-plugin` in a Webpack configuration: This will allow you to import the function from the package & use it in your code. For example: +1. Using `@woocommerce/dependency-extraction-webpack-plugin` in a Webpack configuration: This will allow you to import the function from the package & use it in your code. For example: ```tsx import { __experimentalRegisterProductCollection } from "@woocommerce/blocks-registry"; ``` -2. Using the global `wc` object: This will allow you to use the function using the global JS object without importing it. For example: +2. Using the global `wc` object: This will allow you to use the function using the global JS object without importing it. For example: ```tsx wc.wcBlocksRegistry.__experimentalRegisterProductCollection({ @@ -113,7 +113,7 @@ __experimentalRegisterProductCollection({ }); ``` -As you can see in the example above, we are registering a new collection with the name `woocommerce/product-collection/my-custom-collection` & title `My Custom Collection`. Here is screenshot of how it will look like: +As you can see in the example above, we are registering a new collection with the name `woocommerce/product-collection/my-custom-collection` & title `My Custom Collection`. Here is screenshot of how it will look like: ![image](https://github.com/woocommerce/woocommerce/assets/16707866/7fddbc02-a6cd-494e-b2f4-13dd5ef9cf96) ### Example 2: Register a new collection with a preview diff --git a/docs/theme-development/template-structure.md b/docs/theme-development/template-structure.md index 4688eb53875..888cd31ca11 100644 --- a/docs/theme-development/template-structure.md +++ b/docs/theme-development/template-structure.md @@ -22,7 +22,7 @@ Below is video walkthrough showing how one may go about updating the template fi ## Template list -The various template files on your WooCommerce site can be found via an FTP client or your hosts file manager, in `/wp-content/plugins/woocommerce/templates/`. Below are links to the current and earlier versions of the WooCommerce template files on Github, where you can view the code exactly as it appears in those files: +The various template files on your WooCommerce site can be found via an FTP client or your hosts file manager, in `/wp-content/plugins/woocommerce/templates/`. Below are links to the current and earlier versions of the WooCommerce template files on Github, where you can view the code exactly as it appears in those files: | Latest Version | Files | | -------------- | ----- | @@ -96,7 +96,7 @@ Below are the links to the files of all major previous WooCommerce versions: ## Changing Templates via Hooks -When you open a template file, you will notice they all contain _hooks_ that allow you to add/move content without needing to edit template files themselves. Hooks are a way for one piece of code to interact/modify another piece of code at specific, pre-defined spots. This method allows implementing a code snippet that “hooks” into a particular a theme location. It avoids upgrade issues, as the template files can be left completely untouched and doesn't require a child theme to be configured. +When you open a template file, you will notice they all contain _hooks_ that allow you to add/move content without needing to edit template files themselves. Hooks are a way for one piece of code to interact/modify another piece of code at specific, pre-defined spots. This method allows implementing a code snippet that "hooks" into a particular a theme location. It avoids upgrade issues, as the template files can be left completely untouched and doesn't require a child theme to be configured. Let's take a look at [/wp-content/plugins/woocommerce/templates/emails/admin-new-order.php](https://github.com/woocommerce/woocommerce/blob/8.9.0/plugins/woocommerce/templates/emails/admin-new-order.php) and see what a hook looks like. Starting on line 30, we see the following code, which is responsible for producing the order details section of the New Order email. @@ -137,7 +137,7 @@ The copied file will now override the WooCommerce default template file, so you --- -**Note** A (desirable) side-effect of your templates being upgrade-safe is that WooCommerce core templates will update, but your custom overrides will not. You may occassionally see notices in your System Status report that says, e.g. “version 3.5.0 is out of date. The core version is 3.7.0″. Should that happen, follow the Fixing Outdated WooCommerce Templates guide to bring them in line. +**Note** A (desirable) side-effect of your templates being upgrade-safe is that WooCommerce core templates will update, but your custom overrides will not. You may occassionally see notices in your System Status report that says, e.g. "version 3.5.0 is out of date. The core version is 3.7.0". Should that happen, follow the Fixing Outdated WooCommerce Templates guide to bring them in line. --- diff --git a/docs/ux-guidelines-extensions/navigation.md b/docs/ux-guidelines-extensions/navigation.md index 428d63bdca9..52b43a9b556 100644 --- a/docs/ux-guidelines-extensions/navigation.md +++ b/docs/ux-guidelines-extensions/navigation.md @@ -7,10 +7,7 @@ menu_title: Navigation Examples: -- If your extension is extending a component within WooCommerce, it should live within either the Extensions navigation drawer (in Woo Express stores), or directly within that category's section. - -Extensions drawer (Woo Express) -![Navigation extensions drawer](https://developer.woocommerce.com/docs/wp-content/uploads/sites/3/2024/01/Image-1224x572-1.png) +- If your extension is extending a component within WooCommerce, it should live directly within that category's section. ![Navigation category](https://developer.woocommerce.com/docs/wp-content/uploads/sites/3/2024/01/Image-1242x764-1.png) diff --git a/plugins/woocommerce/changelog/update-contrib-docs-and-fixes b/plugins/woocommerce/changelog/update-contrib-docs-and-fixes new file mode 100644 index 00000000000..8103b856e85 --- /dev/null +++ b/plugins/woocommerce/changelog/update-contrib-docs-and-fixes @@ -0,0 +1,4 @@ +Significance: minor +Type: dev + +Update docs diff --git a/plugins/woocommerce/src/StoreApi/docs/guiding-principles.md b/plugins/woocommerce/src/StoreApi/docs/guiding-principles.md index 0ce28e33ecb..277c0090b4d 100644 --- a/plugins/woocommerce/src/StoreApi/docs/guiding-principles.md +++ b/plugins/woocommerce/src/StoreApi/docs/guiding-principles.md @@ -22,7 +22,7 @@ Well-defined schema also provides a layer of security, as it enables us to valid When defining schema, take note of the [WordPress REST API handbook](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/) which documents available properties and types, as well as the [JSON schema standard](http://json-schema.org/). In addition to this: - Properties should use snake_case 🐍 -- Ambiguous terms should be avoided, and property names should try to use understandable language, rather than “WooCommerce” terminology or setting names +- Ambiguous terms should be avoided, and property names should try to use understandable language, rather than "WooCommerce" terminology or setting names - Properties should be defined using US English, but the descriptions of fields should be localized - Multiple types are permitted, for example, using a `null` type if a value is not applicable - `sanitize_callback` and `validate_callback` are encouraged where possible to ensure data is received in the correct format before processing requests