Adjust contributor docs (https://github.com/woocommerce/woocommerce-blocks/pull/9622)
* Adjust contributor docs * Adjust contributor docs
This commit is contained in:
Niels Lange
GitHub
parent
134b12bef7
commit
8a9bcd4d13
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<!-- FEEDBACK -->
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
|
|||
|
|
@ -2,14 +2,14 @@
|
|||
|
||||
## Table of contents <!-- omit in toc -->
|
||||
|
||||
- [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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
|
|||
|
|
@ -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. |
|
||||
|
||||
|
||||
<!-- FEEDBACK -->
|
||||
|
||||
---
|
||||
|
||||
[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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -2,32 +2,32 @@
|
|||
|
||||
## Table of contents <!-- omit in toc -->
|
||||
|
||||
- [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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
<!-- FEEDBACK -->
|
||||
|
||||
---
|
||||
|
||||
[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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
|
@ -194,7 +194,6 @@ This file is inspired by the great work of @JustinyAhin and @gziolo in <https://
|
|||
|
||||
[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/folder-structure.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/folder-structure.md)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -2,18 +2,18 @@
|
|||
|
||||
## Table of contents <!-- omit in toc -->
|
||||
|
||||
- [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).
|
||||
|
||||
<!-- FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -2,11 +2,12 @@
|
|||
|
||||
## Table of contents <!-- omit in toc -->
|
||||
|
||||
- [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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue