From 8a9bcd4d13e230c12d0d8d8d4eb911dba01a5736 Mon Sep 17 00:00:00 2001 From: Niels Lange Date: Tue, 30 May 2023 13:30:36 +0700 Subject: [PATCH] Adjust contributor docs (https://github.com/woocommerce/woocommerce-blocks/pull/9622) * Adjust contributor docs * Adjust contributor docs --- .../.github/CONTRIBUTING.md | 2 +- plugins/woocommerce-blocks/README.md | 2 +- .../assets/js/base/components/README.md | 2 +- .../assets/js/editor-components/README.md | 2 +- plugins/woocommerce-blocks/docs/README.md | 17 +++--- .../docs/contributors/README.md | 33 +++++------ .../{contributing => }/block-assets.md | 19 +++---- .../{contributing => }/coding-guidelines.md | 3 +- .../docs/contributors/components.md | 3 +- .../docs/contributors/contributing/README.md | 26 --------- .../{contributing => }/css-build-system.md | 3 +- .../documentation-guidelines.md | 55 +++++++++---------- .../{contributing => }/e2e-guidelines.md | 25 ++++++--- .../{contributing => }/folder-structure.md | 3 +- .../{contributing => }/getting-started.md | 45 +++++++-------- .../javascript-build-system.md | 7 +-- .../{contributing => }/javascript-testing.md | 16 +++--- .../storybook-and-components.md | 9 ++- .../docs/designers/theming/README.md | 3 +- 19 files changed, 125 insertions(+), 150 deletions(-) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/block-assets.md (87%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/coding-guidelines.md (99%) delete mode 100644 plugins/woocommerce-blocks/docs/contributors/contributing/README.md rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/css-build-system.md (98%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/documentation-guidelines.md (75%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/e2e-guidelines.md (76%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/folder-structure.md (99%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/getting-started.md (80%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/javascript-build-system.md (94%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/javascript-testing.md (89%) rename plugins/woocommerce-blocks/docs/contributors/{contributing => }/storybook-and-components.md (91%) diff --git a/plugins/woocommerce-blocks/.github/CONTRIBUTING.md b/plugins/woocommerce-blocks/.github/CONTRIBUTING.md index eeaedccd294..ac7d5023b32 100644 --- a/plugins/woocommerce-blocks/.github/CONTRIBUTING.md +++ b/plugins/woocommerce-blocks/.github/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thanks for your interest in contributing to WooCommerce Blocks! -If you wish to contribute code, to get started we recommend first reading our [Getting Started Guide](../docs/contributors/contributing/getting-started.md). +If you wish to contribute code, to get started we recommend first reading our [Getting Started Guide](../docs/contributors/getting-started.md). All other documentation for contributors can be found [in the docs directory](../docs/README.md). diff --git a/plugins/woocommerce-blocks/README.md b/plugins/woocommerce-blocks/README.md index df3c9d73207..31a96f220c8 100644 --- a/plugins/woocommerce-blocks/README.md +++ b/plugins/woocommerce-blocks/README.md @@ -66,7 +66,7 @@ Run through the ["Writing Your First Block Type" tutorial](https://developer.wor For deeper dive, try looking at the [core blocks code,](https://github.com/WordPress/gutenberg/tree/master/packages/block-library/src) or see what [components are available.](https://github.com/WordPress/gutenberg/tree/master/packages/components/src) -To begin contributing to the WooCommerce Blocks plugin, see our [getting started guide](./docs/contributors/contributing/getting-started.md) and [developer handbook](./docs/README.md). +To begin contributing to the WooCommerce Blocks plugin, see our [getting started guide](./docs/contributors/getting-started.md) and [developer handbook](./docs/README.md). Other useful docs to explore: diff --git a/plugins/woocommerce-blocks/assets/js/base/components/README.md b/plugins/woocommerce-blocks/assets/js/base/components/README.md index 3e4c68c26eb..cafa6b8117c 100644 --- a/plugins/woocommerce-blocks/assets/js/base/components/README.md +++ b/plugins/woocommerce-blocks/assets/js/base/components/README.md @@ -2,4 +2,4 @@ These are shared components used in WooCommerce blocks, and may be used in the store front end (shopper experience) as well as the editor or admin dashboard. -See [_Components & Storybook_](../../../../docs/contributors/contributing/storybook-and-components.md) doc for more information. +See [_Components & Storybook_](../../../../docs/contributors/storybook-and-components.md) doc for more information. diff --git a/plugins/woocommerce-blocks/assets/js/editor-components/README.md b/plugins/woocommerce-blocks/assets/js/editor-components/README.md index 4fd4c3e2cd7..ffb4186351f 100644 --- a/plugins/woocommerce-blocks/assets/js/editor-components/README.md +++ b/plugins/woocommerce-blocks/assets/js/editor-components/README.md @@ -4,7 +4,7 @@ These are shared components used in WooCommerce blocks for the editor (Gutenberg Many of our blocks need rich, smart components to provide an interface for selecting or configuring blocks with WooCommerce data. Often there are multiple blocks that need such components. Components in this collection are used in multiple blocks, and may include logic for working with Woo data specifically (e.g. products, shipping methods, product categories). -See [Storybook & Components](../../../docs/contributors/contributing/storybook-and-components.md) doc for more information. +See [Storybook & Components](../../../docs/contributors/storybook-and-components.md) doc for more information. diff --git a/plugins/woocommerce-blocks/docs/README.md b/plugins/woocommerce-blocks/docs/README.md index 631fff09c6e..5f6529f0859 100644 --- a/plugins/woocommerce-blocks/docs/README.md +++ b/plugins/woocommerce-blocks/docs/README.md @@ -17,14 +17,14 @@ The WooCommerce Blocks Handbook provides documentation for designers and develop > Want to contribute to the WooCommerce Blocks plugin? The following documents offer information that can help you get started. -- [Contributing](contributors/contributing/README.md) - - [Getting Started](contributors/contributing/getting-started.md) - - [Coding Guidelines](contributors/contributing/coding-guidelines.md) - - [Block Script Assets](contributors/contributing/block-assets.md) - - [CSS Build System](contributors/contributing/css-build-system.md) - - [JavaScript Build System](contributors/contributing/javascript-build-system.md) - - [JavaScript Testing](contributors/contributing/javascript-testing.md) - - [Storybook & Components](contributors/contributing/storybook-and-components.md) +- [Contributing](contributors/README.md) + - [Getting Started](contributors/getting-started.md) + - [Coding Guidelines](contributors/coding-guidelines.md) + - [Block Script Assets](contributors/block-assets.md) + - [CSS Build System](contributors/css-build-system.md) + - [JavaScript Build System](contributors/javascript-build-system.md) + - [JavaScript Testing](contributors/javascript-testing.md) + - [Storybook & Components](contributors/storybook-and-components.md) ## Internal developers @@ -151,4 +151,3 @@ The following tutorials from [developer.woocommerce.com](https://developer.wooco 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/README.md b/plugins/woocommerce-blocks/docs/contributors/README.md index 455b6d1d1fa..54615cf240b 100644 --- a/plugins/woocommerce-blocks/docs/contributors/README.md +++ b/plugins/woocommerce-blocks/docs/contributors/README.md @@ -2,37 +2,39 @@ If you're a developer or contributor eager to get started with WooCommerce Block Development, this documentation folder is your perfect starting point. -## Getting Started +## Navigating this section -The [Getting Started](contributing/getting-started.md) guide is your first step in this journey. This document provides comprehensive information about the tooling you'll need and the process of creating builds during the development phase. +### [Getting Started](getting-started.md) -## Coding Guidelines +The [Getting Started](getting-started.md) guide is your first step in this journey. This document provides comprehensive information about the tooling you'll need and the process of creating builds during the development phase. -A set of guidelines exist to ensure development consistency and quality. The [Coding Guidelines](contributing/coding-guidelines.md) doc is your resource for understanding these best practices. +### [Coding Guidelines](coding-guidelines.md) -## JavaScript Testing +A set of guidelines exist to ensure development consistency and quality. The [Coding Guidelines](coding-guidelines.md) doc is your resource for understanding these best practices. -Testing plays a crucial role in development. Our [JavaScript Testing](contributing/javascript-testing.md) guide will walk you through the process of running automated JavaScript tests, providing a robust framework to ensure your code meets the requisite standards. +### [JavaScript Testing](javascript-testing.md) -## End-to-End (E2E) Testing Guidelines +Testing plays a crucial role in development. Our [JavaScript Testing](javascript-testing.md) guide will walk you through the process of running automated JavaScript tests, providing a robust framework to ensure your code meets the requisite standards. -The [E2E Testing Guidelines](contributing/e2e-guidelines.md) document offers a detailed understanding of the best practices related to End-to-End tests. E2E testing is a critical aspect of ensuring overall system integrity and functionality. +### [E2E Testing Guidelines](e2e-guidelines.md) -## Developing Components and Storybook +The [E2E Testing Guidelines](e2e-guidelines.md) document offers a detailed understanding of the best practices related to End-to-End tests. E2E testing is a critical aspect of ensuring overall system integrity and functionality. + +### [Developing Components (& Storybook)](components.md) For insight into our reusable components, their usage, and how to test them in Storybook, refer to the [Developing Components (& Storybook)](components.md) guide. -## Block Script Assets +### [Block Script Assets](block-assets.md) -The [Block Script Assets](contributing/block-assets.md) document elucidates how Block Script Assets are loaded and used in the development process. This guide is vital to understanding the role of script assets in block development. +The [Block Script Assets](block-assets.md) document elucidates how Block Script Assets are loaded and used in the development process. This guide is vital to understanding the role of script assets in block development. -## JavaScript Build System +### [JavaScript Build System](javascript-build-system.md) -Our [JavaScript Build System](contributing/javascript-build-system.md) guide offers a detailed explanation of how JavaScript files are built. This is a crucial read for understanding the behind-the-scenes operations of your code. +Our [JavaScript Build System](javascript-build-system.md) guide offers a detailed explanation of how JavaScript files are built. This is a crucial read for understanding the behind-the-scenes operations of your code. -## CSS Build System +### [CSS Build System](css-build-system.md) -Last but not least, to get an insight into how CSS is built, refer to the [CSS Build System](contributing/css-build-system.md) guide. A firm grasp of this will ensure your CSS files meet the standards and quality expected. +Last but not least, to get an insight into how CSS is built, refer to the [CSS Build System](css-build-system.md) guide. A firm grasp of this will ensure your CSS files meet the standards and quality expected. --- @@ -41,4 +43,3 @@ Last but not least, to get an insight into how CSS is built, refer to the [CSS B 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/README.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/block-assets.md b/plugins/woocommerce-blocks/docs/contributors/block-assets.md similarity index 87% rename from plugins/woocommerce-blocks/docs/contributors/contributing/block-assets.md rename to plugins/woocommerce-blocks/docs/contributors/block-assets.md index 824748f0196..63f2a916cc3 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/block-assets.md +++ b/plugins/woocommerce-blocks/docs/contributors/block-assets.md @@ -2,14 +2,14 @@ ## Table of contents -- [When are assets needed?](#when-are-assets-needed) -- [Choosing Handles for Assets (and scripts in general)](#choosing-handles-for-assets-and-scripts-in-general) -- [Using the `AbstractBlock` class](#using-the-abstractblock-class) - - [AbstractBlock::render](#abstractblockrender) - - [AbstractBlock::enqueue_editor_assets](#abstractblockenqueue_editor_assets) - - [AbstractBlock::enqueue_assets](#abstractblockenqueue_assets) - - [AbstractBlock::enqueue_data](#abstractblockenqueue_data) -- [woocommerce_shared_settings deprecated filter](#woocommerce_shared_settings-deprecated-filter) +- [When are assets needed?](#when-are-assets-needed) +- [Choosing Handles for Assets (and scripts in general)](#choosing-handles-for-assets-and-scripts-in-general) +- [Using the `AbstractBlock` class](#using-the-abstractblock-class) + - [AbstractBlock::render](#abstractblockrender) + - [AbstractBlock::enqueue_editor_assets](#abstractblockenqueue_editor_assets) + - [AbstractBlock::enqueue_assets](#abstractblockenqueue_assets) + - [AbstractBlock::enqueue_data](#abstractblockenqueue_data) +- [woocommerce_shared_settings deprecated filter](#woocommerce_shared_settings-deprecated-filter) [Block Types](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/src/BlockTypes) are often responsible for enqueuing script assets that make blocks functional on both the front-end and within the editor. Additionally, some block scripts require extra data from the server and thus have extra dependencies that need to be loaded. @@ -95,7 +95,6 @@ wc.wcSettings.getSetting( 'key' ); [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/block-assets.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/coding-guidelines.md b/plugins/woocommerce-blocks/docs/contributors/coding-guidelines.md similarity index 99% rename from plugins/woocommerce-blocks/docs/contributors/contributing/coding-guidelines.md rename to plugins/woocommerce-blocks/docs/contributors/coding-guidelines.md index f55f5c624e0..70a095e6a24 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/coding-guidelines.md +++ b/plugins/woocommerce-blocks/docs/contributors/coding-guidelines.md @@ -179,7 +179,6 @@ Notice in the worst case scenario we would have increased selector specificity b [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/coding-guidelines.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/components.md b/plugins/woocommerce-blocks/docs/contributors/components.md index 71081ad3673..cb17a0281c8 100644 --- a/plugins/woocommerce-blocks/docs/contributors/components.md +++ b/plugins/woocommerce-blocks/docs/contributors/components.md @@ -46,7 +46,6 @@ If you're stuck, copy source of an existing story to get started. [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/components.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/README.md b/plugins/woocommerce-blocks/docs/contributors/contributing/README.md deleted file mode 100644 index 416eb02547f..00000000000 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Contributing - -This folder contains documentation for developers and contributors looking to get started with WooCommerce Block Development. - -| Document | Description | -|----------------------------------------------------------|------------------------------------------------------------------------------------------| -| [Getting Started](getting-started.md) | This doc covers tooling and creating builds during development. | -| [Coding Guidelines](coding-guidelines.md) | This doc covers development best practices. | -| [Block Script Assets](block-assets.md) | This doc explains how Block Script Assets are loaded and used. | -| [CSS Build System](css-build-system.md) | This doc explains how CSS files are built. | -| [JavaScript Build System](javascript-build-system.md) | This doc explains how JavaScript files are built. | -| [JavaScript Testing](javascript-testing.md) | This doc explains how to run automated JavaScript tests. | -| [E2E Testing Guidelines](e2e-guidelines.md) | This doc covers development best practices about E2E tests. | -| [Storybook & Components](storybook-and-components.md) | This doc outlines where our reusable components live, and how to test them in Storybook. | - - - - ---- - -[We're hiring!](https://woocommerce.com/careers/) Come work with us! - -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/README.md) - - - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/css-build-system.md b/plugins/woocommerce-blocks/docs/contributors/css-build-system.md similarity index 98% rename from plugins/woocommerce-blocks/docs/contributors/contributing/css-build-system.md rename to plugins/woocommerce-blocks/docs/contributors/css-build-system.md index 30103e6189a..0402b368542 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/css-build-system.md +++ b/plugins/woocommerce-blocks/docs/contributors/css-build-system.md @@ -31,7 +31,6 @@ Webpack config is split between several files, some relevant ones for the CSS bu [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/css-build-system.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/documentation-guidelines.md b/plugins/woocommerce-blocks/docs/contributors/documentation-guidelines.md similarity index 75% rename from plugins/woocommerce-blocks/docs/contributors/contributing/documentation-guidelines.md rename to plugins/woocommerce-blocks/docs/contributors/documentation-guidelines.md index 1daca2aa9cb..445d3ef1408 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/documentation-guidelines.md +++ b/plugins/woocommerce-blocks/docs/contributors/documentation-guidelines.md @@ -2,32 +2,32 @@ ## Table of contents -- [Use active instead of passive voice](#use-active-instead-of-passive-voice) - - [Example](#example) -- [Use the personal pronoun β€œyou”](#use-the-personal-pronoun-you) -- [Don’t use gendered pronouns](#dont-use-gendered-pronouns) -- [Filename must resemble the title](#filename-must-resemble-the-title) - - [Example](#example-1) -- [Use correct heading hierarchy](#use-correct-heading-hierarchy) - - [Example](#example-2) -- [Use semantically correct markup](#use-semantically-correct-markup) -- [Use correct spelling](#use-correct-spelling) - - [Example](#example-3) -- [Use images not wider than 50% width](#use-images-not-wider-than-50-width) -- [Use descriptive links](#use-descriptive-links) - - [Example](#example-4) -- [Explain arguments](#explain-arguments) - - [Example](#example-5) -- [Explicitly define language for code examples](#explicitly-define-language-for-code-examples) - - [Example](#example-6) - - [CSS code example](#css-code-example) - - [JS code example](#js-code-example) -- [Use table of contents for top-level readme](#use-table-of-contents-for-top-level-readme) -- [Use internal links](#use-internal-links) -- [Sort releases descending](#sort-releases-descending) - - [Example](#example-7) -- [Structure β€œHow to” instructions](#structure-how-to-instructions) -- [Link references](#link-references) +- [Use active instead of passive voice](#use-active-instead-of-passive-voice) + - [Example](#example) +- [Use the personal pronoun β€œyou”](#use-the-personal-pronoun-you) +- [Don’t use gendered pronouns](#dont-use-gendered-pronouns) +- [Filename must resemble the title](#filename-must-resemble-the-title) + - [Example](#example-1) +- [Use correct heading hierarchy](#use-correct-heading-hierarchy) + - [Example](#example-2) +- [Use semantically correct markup](#use-semantically-correct-markup) +- [Use correct spelling](#use-correct-spelling) + - [Example](#example-3) +- [Use images not wider than 50% width](#use-images-not-wider-than-50-width) +- [Use descriptive links](#use-descriptive-links) + - [Example](#example-4) +- [Explain arguments](#explain-arguments) + - [Example](#example-5) +- [Explicitly define language for code examples](#explicitly-define-language-for-code-examples) + - [Example](#example-6) + - [CSS code example](#css-code-example) + - [JS code example](#js-code-example) +- [Use table of contents for top-level readme](#use-table-of-contents-for-top-level-readme) +- [Use internal links](#use-internal-links) +- [Sort releases descending](#sort-releases-descending) + - [Example](#example-7) +- [Structure β€œHow to” instructions](#structure-how-to-instructions) +- [Link references](#link-references) ## Use active instead of passive voice @@ -165,7 +165,6 @@ When referencing other documentations, the corresponding document should be link [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/documentation-guidelines.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/e2e-guidelines.md b/plugins/woocommerce-blocks/docs/contributors/e2e-guidelines.md similarity index 76% rename from plugins/woocommerce-blocks/docs/contributors/contributing/e2e-guidelines.md rename to plugins/woocommerce-blocks/docs/contributors/e2e-guidelines.md index 5db4ea854a4..d392205dc72 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/e2e-guidelines.md +++ b/plugins/woocommerce-blocks/docs/contributors/e2e-guidelines.md @@ -6,7 +6,7 @@ - [Playwright](#playwright) - [Structure](#structure-1) -This living document serves to prescribe coding guidelines specific to the WooCommerce Blocks project E2E tests. For more information on how to run Playwright end-to-end (E2E) tests, please refer to the [dedicated resource](../../../tests/e2e-pw/README.md). +This living document serves to prescribe coding guidelines specific to the WooCommerce Blocks project E2E tests. For more information on how to run Playwright end-to-end (E2E) tests, please refer to the [dedicated resource](../../tests/e2e-pw/README.md). ## Structure @@ -20,12 +20,12 @@ The first folder is named "e2e" and it contains all the E2E tests that were crea There are two Playwright projects configuration: -- blockTheme -- classicTheme +- blockTheme +- classicTheme -The blockTheme project runs the tests with the suffix *block_theme*. In this case, the theme is a block theme. The block theme is the default WordPress theme. Currently, it is Twenty-Twenty Three. You should use this configuration if you want test the block with the Site Editor. +The blockTheme project runs the tests with the suffix _block_theme_. In this case, the theme is a block theme. The block theme is the default WordPress theme. Currently, it is Twenty-Twenty Three. You should use this configuration if you want test the block with the Site Editor. -The classicTheme project runs the tests with the suffix *classic_theme*. In this case, the theme is a Twenty Twenty-One. You should use this configuration if you want test the block with a classic theme. +The classicTheme project runs the tests with the suffix _classic_theme_. In this case, the theme is a Twenty Twenty-One. You should use this configuration if you want test the block with a classic theme. Each block should have a dedicated folder with a scoped util file if you want share some logic related to the block. @@ -47,9 +47,18 @@ In order to write end to end tests we need to first find elements on the webpage In order to make the codebase cleaner, you should import the function from the packages: -- "@woocommerce/e2e-utils": Contains generic utils for interactive with the page. -- "@woocommerce/e2e-types": Contains generic types. -- "@woocommerce/e2e-playwright-utils": Contains utils for playwright for example custom hooks. +- "@woocommerce/e2e-utils": Contains generic utils for interactive with the page. +- "@woocommerce/e2e-types": Contains generic types. +- "@woocommerce/e2e-playwright-utils": Contains utils for playwright for example custom hooks. By using these packages, you can make your code more modular and easier to maintain. + + +--- + +[We're hiring!](https://woocommerce.com/careers/) Come work with us! + +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md) + + diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/folder-structure.md b/plugins/woocommerce-blocks/docs/contributors/folder-structure.md similarity index 99% rename from plugins/woocommerce-blocks/docs/contributors/contributing/folder-structure.md rename to plugins/woocommerce-blocks/docs/contributors/folder-structure.md index 0e025b4b811..9ead474b67e 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/folder-structure.md +++ b/plugins/woocommerce-blocks/docs/contributors/folder-structure.md @@ -194,7 +194,6 @@ This file is inspired by the great work of @JustinyAhin and @gziolo in - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/getting-started.md b/plugins/woocommerce-blocks/docs/contributors/getting-started.md similarity index 80% rename from plugins/woocommerce-blocks/docs/contributors/contributing/getting-started.md rename to plugins/woocommerce-blocks/docs/contributors/getting-started.md index 19e0fc81f78..32b009f5b8b 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/getting-started.md +++ b/plugins/woocommerce-blocks/docs/contributors/getting-started.md @@ -2,18 +2,18 @@ ## Table of contents -- [Cloning the Git Repository](#cloning-the-git-repository) -- [Configuring your WordPress site](#configuring-your-wordpress-site) -- [Installing dependencies](#installing-dependencies) -- [Building the plugin files](#building-the-plugin-files) -- [Create a plugin package in ZIP format](#create-a-plugin-package-in-zip-format) -- [Linting](#linting) -- [Running the Blocks plugin](#running-the-blocks-plugin) -- [Developer Tools (Visual Studio Code)](#developer-tools-visual-studio-code) - - [EditorConfig](#editorconfig) - - [ESLint](#eslint) - - [Prettier](#prettier) -- [Testing](#testing) +- [Cloning the Git Repository](#cloning-the-git-repository) +- [Configuring your WordPress site](#configuring-your-wordpress-site) +- [Installing dependencies](#installing-dependencies) +- [Building the plugin files](#building-the-plugin-files) +- [Create a plugin package in ZIP format](#create-a-plugin-package-in-zip-format) +- [Linting](#linting) +- [Running the Blocks plugin](#running-the-blocks-plugin) +- [Developer Tools (Visual Studio Code)](#developer-tools-visual-studio-code) + - [EditorConfig](#editorconfig) + - [ESLint](#eslint) + - [Prettier](#prettier) +- [Testing](#testing) Before you can begin contributing to the Blocks plugin there are several steps and tools required to setup your local development environment. @@ -48,12 +48,14 @@ define( 'SCRIPT_DEBUG', true ); To install dependencies, you will need the following tools installed on your machine: -- `node` and `npm` via [NVM](https://github.com/nvm-sh/nvm#installing-and-updating): While you can always install Node or NPM through other means, we recommend using NVM to ensure you're aligned with the version used by our development teams. Our repository contains [an `.nvmrc` file](../../../.nvmrc) which helps ensure you are using the correct version of Node. -- [PHP](https://www.php.net/manual/en/install.php): WooCommerce Blocks requires PHP. It is also needed to run Composer and various project build scripts. -- [Composer](https://getcomposer.org/doc/00-intro.md): We use Composer to manage all of the dependencies for PHP packages and plugins. +- `node` and `npm` via [NVM](https://github.com/nvm-sh/nvm#installing-and-updating): While you can always install Node or NPM through other means, we recommend using NVM to ensure you're aligned with the version used by our development teams. Our repository contains [an `.nvmrc` file](../../.nvmrc) which helps ensure you are using the correct version of Node. +- [PHP](https://www.php.net/manual/en/install.php): WooCommerce Blocks requires PHP. It is also needed to run Composer and various project build scripts. +- [Composer](https://getcomposer.org/doc/00-intro.md): We use Composer to manage all of the dependencies for PHP packages and plugins. + +See [`package.json` `engines`](../../package.json) and [`readme.txt`](../../readme.txt#L6) for details on required versions. -See [`package.json` `engines`](../../../package.json) and [`readme.txt`](../../../readme.txt#L6) for details on required versions. + Once you the above setup, install the dependencies from the command line: - Change directory to your repo folder, e.g. `$ cd woocommerce-blocks`. @@ -86,9 +88,9 @@ Run `$ npm run lint` to check code against our linting rules. This script runs 3 sub-commands: `lint:php`, `lint:css`, `lint:js`. Use these to run linters across the codebase (linters check for valid syntax). -- `lint:php` runs phpcs via composer, which uses the [phpcs.xml](../../../phpcs.xml) rule set. -- `lint:css` runs stylelint over all the scss code in `assets/css`, using the rules in [.stylelintrc.json.](../../../.stylelintrc.json) -- `lint:js` runs eslint over all the JavaScript, using the rules in [.eslintrc.js.](../../../.eslintrc.js) +- `lint:php` runs phpcs via composer, which uses the [phpcs.xml](../../phpcs.xml) rule set. +- `lint:css` runs stylelint over all the scss code in `assets/css`, using the rules in [.stylelintrc.json.](../../.stylelintrc.json) +- `lint:js` runs eslint over all the JavaScript, using the rules in [.eslintrc.js.](../../.eslintrc.js) Note; linters are also ran before commits via Git. If there are any violations, you will not be able to commit your changes until they are fixed, unless you add the `--no-verify` flag to your commit command. @@ -138,7 +140,7 @@ You’ll find a handful of scripts in `package.json` that performs the automated - JS tests: `npm run test` - Run `npm run wp-env` command to setup the development environment in Docker. -To find out more about how to run automated JavaScript tests, check out the documentation on [JavaScript Testing](../../contributors/contributing/javascript-testing.md). +To find out more about how to run automated JavaScript tests, check out the documentation on [JavaScript Testing](javascript-testing.md). @@ -146,7 +148,6 @@ To find out more about how to run automated JavaScript tests, check out the docu [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/getting-started.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/getting-started.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md b/plugins/woocommerce-blocks/docs/contributors/javascript-build-system.md similarity index 94% rename from plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md rename to plugins/woocommerce-blocks/docs/contributors/javascript-build-system.md index 193113a6be7..53ca09223f5 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md +++ b/plugins/woocommerce-blocks/docs/contributors/javascript-build-system.md @@ -38,8 +38,8 @@ Several scripts are loaded as externals. That means that they can be imported in In practice, that means the dependency version is: -- deterministic when running WooCommerce Blocks in isolation (e.g. unit tests). In this case, the dependency will have a version as stated in `package.json`, -- non-deterministic when run in the WordPress ecosystem. Depending on the WordPress or Gutenberg version the user has installed, the version of external dependencies may also vary. +- deterministic when running WooCommerce Blocks in isolation (e.g. unit tests). In this case, the dependency will have a version as stated in `package.json`, +- non-deterministic when run in the WordPress ecosystem. Depending on the WordPress or Gutenberg version the user has installed, the version of external dependencies may also vary. [`@wordpress/dependency-extraction-webpack-plugin`](https://developer.wordpress.org/block-editor/packages/packages-dependency-extraction-webpack-plugin/) script is applied to each of the build processes: Core, Main, Frontend, Payments, Extensions. @@ -81,7 +81,6 @@ Webpack config is split between several files: [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/javascript-build-system.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/javascript-build-system.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-testing.md b/plugins/woocommerce-blocks/docs/contributors/javascript-testing.md similarity index 89% rename from plugins/woocommerce-blocks/docs/contributors/contributing/javascript-testing.md rename to plugins/woocommerce-blocks/docs/contributors/javascript-testing.md index 368fc663f1f..6493357eeb2 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-testing.md +++ b/plugins/woocommerce-blocks/docs/contributors/javascript-testing.md @@ -2,11 +2,12 @@ ## Table of contents -- [How to run JavaScript unit tests](#how-to-run-javascript-unit-tests) -- [How to run end-to-end tests](#how-to-run-end-to-end-tests) - - [Debugging e2e tests using generated reports](#debugging-e2e-tests-using-generated-reports) - - [Modify the local environment used by end-to-end tests](#modify-the-local-environment-used-by-end-to-end-tests) - - [WordPress versions and end-to-end tests suites](#wordpress-versions-and-end-to-end-tests-suites) +- [How to run JavaScript unit tests](#how-to-run-javascript-unit-tests) +- [How to run end-to-end tests with deprecated infrastructure](#how-to-run-end-to-end-tests-with-deprecated-infrastructure) +- [How to run end-to-end tests](#how-to-run-end-to-end-tests) + - [Debugging e2e tests using generated reports](#debugging-e2e-tests-using-generated-reports) + - [Modify the local environment used by end-to-end tests](#modify-the-local-environment-used-by-end-to-end-tests) + - [WordPress versions and end-to-end tests suites](#wordpress-versions-and-end-to-end-tests-suites) Tests for JavaScript in the Blocks plugin are powered by [Jest](https://jestjs.io/). The Blocks plugin follows the same patterns as Gutenberg, therefore for instructions on writing tests you can [refer to this page in the Gutenberg Handbook](https://developer.wordpress.org/block-editor/contributors/develop/testing-overview/). @@ -62,7 +63,7 @@ When you're done, you may want to shut down the test environment: ## How to run end-to-end tests -Visit the [dedicated documentation](../../../tests/e2e-pw/README.md). +Visit the [dedicated documentation](../../tests/e2e-pw/README.md). ### Debugging e2e tests using generated reports @@ -114,7 +115,6 @@ When preparing for a new version of WordPress, it's a good practice to search fo [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/javascript-testing.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/javascript-testing.md) - diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/storybook-and-components.md b/plugins/woocommerce-blocks/docs/contributors/storybook-and-components.md similarity index 91% rename from plugins/woocommerce-blocks/docs/contributors/contributing/storybook-and-components.md rename to plugins/woocommerce-blocks/docs/contributors/storybook-and-components.md index 6bb83184ca0..ad7fe3f78a2 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/storybook-and-components.md +++ b/plugins/woocommerce-blocks/docs/contributors/storybook-and-components.md @@ -12,9 +12,9 @@ This repo includes [Storybook](https://storybook.js.org) tooling so we can test We have components in a few folders, for different contexts. -- [`assets/js/base/components`](../../../assets/js/base/components) -- [`assets/js/editor-components`](../../../assets/js/editor-components) -- [`assets/js/icons`](../../../assets/js/icons) +- [`assets/js/base/components`](../../assets/js/base/components) +- [`assets/js/editor-components`](../../assets/js/editor-components) +- [`assets/js/icons`](../../assets/js/icons) **`assets/js/base/components`** are used in front-end code, as well as editor & admin. These components help us build consistent interfaces across the front end (shopper) experience and elsewhere. @@ -50,7 +50,6 @@ If you're stuck, copy source of an existing story to get started. [We're hiring!](https://woocommerce.com/careers/) Come work with us! -🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/contributing/storybook-and-components.md) +🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/storybook-and-components.md) - diff --git a/plugins/woocommerce-blocks/docs/designers/theming/README.md b/plugins/woocommerce-blocks/docs/designers/theming/README.md index 4b353416bdb..9ce791b5a18 100644 --- a/plugins/woocommerce-blocks/docs/designers/theming/README.md +++ b/plugins/woocommerce-blocks/docs/designers/theming/README.md @@ -6,7 +6,7 @@ This page includes all documentation regarding WooCommerce Blocks and themes. ### Block and component class names -WooCommerce Blocks follows BEM for class names, as [stated in our coding guidelines](../../contributors/contributing/coding-guidelines.md). All classes start with one of these two prefixes: +WooCommerce Blocks follows BEM for class names, as [stated in our coding guidelines](../../contributors/coding-guidelines.md). All classes start with one of these two prefixes: - `.wc-block-`: class names specific to a single block. - `.wc-block-components-`: class names specific to a component. The component might be reused by different blocks. @@ -89,4 +89,3 @@ WooCommerce Blocks avoids using legacy unprefixed classes as much as possible. H 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/designers/theming/README.md) -