Re-organise docs and add WP update instructions (https://github.com/woocommerce/woocommerce-blocks/pull/1691)

* Move coding guideline and release docs to subdirectories

* Strip down contributing md to link to new docs

* Create main readme file to act as TOC

* Getting started and testing docs from contributing.md

* WP update testing checklist and docs for woocommerce/woocommerce-blocks#1285

* Update docs/contributors/smoke-testing.md

Co-Authored-By: Albert Juhé Lluveras <aljullu@gmail.com>

* link to svn doc

* Link to docs from readme

* Resolve feedback

* More consistent $ usage

Co-authored-by: Albert Juhé Lluveras <aljullu@gmail.com>

plugins/woocommerce-blocks/.github/CONTRIBUTING.md

@@ -1,89 +1,15 @@
 # Contributing
 
-Thanks for your interest in contributing to WooCommerce Blocks! Below are some developer docs for working with the project.
+Thanks for your interest in contributing to WooCommerce Blocks!
 
-## Get started
+If you wish to contribute code, to get started we recommend first reading our [Getting Started Guide](./docs/contributors/getting-started.md).
 
-### Required developer tools
+All other documentation for contributors can be found [in the docs directory](./docs/readme.md).
 
--   [`git`](https://git-scm.com)
+## Guidelines
--   [`npm` and `node.js`](https://nodejs.org)
--   [`composer`](https://getcomposer.org)
--   A WordPress development environment - e.g. [`VVV`](https://varyingvagrantvagrants.org) or [`docker`](https://www.docker.com).
 
-See [`package.json` `engines`](package.json) for details of required versions.
+Like the WooCommerce project, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](./.github/CODE_OF_CONDUCT.md).
 
-### Clone repo & install code dependencies
+## Reporting Security Issues
 
--   Clone this repository locally - `git clone https://github.com/woocommerce/woocommerce-gutenberg-products-block.git`.
+Please see [SECURITY.md](./.github/SECURITY.md).
--   Change directory to your repo folder, e.g. `cd woocommerce-gutenberg-products-block`.
--   Install javascript and php dependencies - `npm install && composer install`.
-
-### Run the plugin
-
--   Ensure the repo folder is in the `wp-content/plugins` folder of your WordPress environment.
--   Activate the `WooCommerce Blocks` plugin (should be dev version, e.g. `2.6.0-dev`).
--   Edit a page or post in block editor - you should see WooCommerce blocks in the block inserter!
-
-## NPM commands
-
-We have a set of scripts in npm to automate important developer tasks.
-
-### Build
-
--   Run `$ npm run build` to build all assets for production.
--   Run `$ npm start` to run the development build and watch for changes.
-
-These scripts compile the code using `webpack`.
-
-You can also run `$ npx webpack` to run the development build and not keep watching.
-
-### Lint
-
-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](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/phpcs.xml) rule set.
--   `lint:css` runs stylelint over all the scss code in `assets/css`, using the rules in [.stylelintrc.json.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/.stylelintrc.json)
--   `lint:js` runs eslint over all the JavaScript, using the rules in [.eslintrc.js.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/.eslintrc.js)
-
-### Test
-
-Run `$ npm run test` to run unit tests on the JavaScript.
-
-The test scripts use [wp-scripts](https://github.com/WordPress/gutenberg/tree/master/packages/scripts) to run jest for component and unit testing.
-
--   `test:update` updates the snapshot tests for components, used if you change a component that has tests attached.
--   Use `test:watch` to keep watch of files and automatically re-run tests.
-
-### Create a plugin package in ZIP format
-
-Run `$ npm run package-plugin` to trigger install and build, and then create a zip file which you can use to install WooCommerce Blocks in WordPress admin.
-
-## Releases
-
-See [RELEASE.md](RELEASE.md).
-
-## Publishing `@woocommerce/block-library`
-
-In the past, we published the blocks to NPM at [@woocommerce/block-library](https://www.npmjs.com/package/@woocommerce/block-library).
-
-**Note: since version 2.3.0 `@woocommerce/block-library` has been deprecated, you shouldn't publish a new version without first discussing it with the team**
-
-To release a new version, perform the following steps:
-
--   Run `npm pack` to prep a `.tgz` file.
--   Optionally test the package by uploading this onto a test site.
--   Run `npm publish --access public`, which will push the version up to npm.
-
-## Legacy builds
-
-This plugin supports two type of builds:
-
--   legacy builds (assets have `-legacy` suffix on their file names)
--   main builds (without the `-legacy` prefix)
-
-The legacy builds are loaded in a site environment where the WordPress version doesn't meet minimum requirements for a components used in a set build.
-
-You can read more about legacy builds in the [this doc](./assets/js/legacy/README.md).

plugins/woocommerce-blocks/README.md

@@ -8,15 +8,15 @@ If you want to see what we're working on for future versions, or want to help ou
 
 ## Table of Contents
 
-- [Installing the stable version](#installing-the-stable-version)
+-   [Installing the stable version](#installing-the-stable-version)
-- [Installing the development version](#installing-the-development-version)
+-   [Installing the development version](#installing-the-development-version)
-- [Getting started with block development](#getting-started-with-block-development)
+-   [Getting started with block development](#getting-started-with-block-development)
-- [Contributing](CONTRIBUTING.md)
+-   [Contributing](CONTRIBUTING.md)
-  - [About the npm scripts](CONTRIBUTING.md#npm-scripts)
+    -   [About the npm scripts](CONTRIBUTING.md#npm-scripts)
-  - [Publishing a release](CONTRIBUTING.md#publishing-woocommerceblock-library)
+    -   [Publishing a release](CONTRIBUTING.md#publishing-woocommerceblock-library)
-- Code Documentation
+-   Code Documentation
-  - [Blocks](assets/js/blocks)
+    -   [Blocks](assets/js/blocks)
-  - [Components](assets/js/components)
+    -   [Components](assets/js/components)
 
 ## Installing the stable version
 
@@ -43,11 +43,13 @@ Run through the ["Writing Your First Block Type" tutorial](https://wordpress.org
 
 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/getting-started.md) and [developer handbook](./docs/readme.md).
+
 Other useful docs to explore:
 
-- [`InnerBlocks `](https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/inner-blocks/README.md)
+-   [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/inner-blocks/README.md)
-- [`apiFetch`](https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-api-fetch/)
+-   [`apiFetch`](https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-api-fetch/)
-- [`@wordpress/editor`](https://github.com/WordPress/gutenberg/blob/master/packages/editor/README.md)
+-   [`@wordpress/editor`](https://github.com/WordPress/gutenberg/blob/master/packages/editor/README.md)
 
 ## Vision for the Feature
 

plugins/woocommerce-blocks/docs/contributors/getting-started.md

@@ -0,0 +1,104 @@
+# Getting Started
+
+Before you can begin contributing to the Blocks plugin there are several steps and tools required to setup your local development environment.
+
+## Cloning the Git Repository
+
+Before you can start modifying files you'll want to clone this repository locally, either via the command line, or using a Git client such as [GitHub Desktop](https://desktop.github.com/).
+
+To do so from the command line, ensure you have [`git`](https://git-scm.com) installed on your machine, and run the clone command:
+
+```
+$ git clone https://github.com/woocommerce/woocommerce-gutenberg-products-block.git
+```
+
+## Installing dependencies
+
+To install dependencies, you will need the following tools installed on your machine:
+
+-   [`npm` and `node.js`](https://nodejs.org)
+-   [`composer`](https://getcomposer.org)
+
+See [`package.json` `engines`](package.json) for details of required versions.
+
+Once you have `node` and `composer` setup, install the dependencies from the command line:
+
+-   Change directory to your repo folder, e.g. `$ cd woocommerce-gutenberg-products-block`.
+-   Install javascript and php dependencies - `$ npm install && composer install`.
+
+## Building the plugin files
+
+NPM is used to trigger builds. Building is required for the plugin to functional.
+
+-   Run `$ npm run build` to build all assets for production.
+-   Run `$ npm start` to run the development build and watch for changes.
+
+These scripts compile the code using `webpack` which is one of the installed dependencies from earlier.
+
+You can also run `$ npx webpack` to run the development build and not keep watching for changes.
+
+### Legacy builds
+
+This plugin supports two type of builds:
+
+-   legacy builds (assets have `-legacy` suffix on their file names)
+-   main builds (without the `-legacy` prefix)
+
+The legacy builds are loaded in a site environment where the WordPress version doesn't meet minimum requirements for a component used in a set build.
+
+You can read more about legacy builds in the [this doc](./assets/js/legacy/README.md).
+
+## Create a plugin package in ZIP format
+
+Run `$ npm run package-plugin` to trigger install and build, and then create a zip file which you can use to install WooCommerce Blocks in WordPress admin.
+
+## Linting
+
+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](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/phpcs.xml) rule set.
+-   `lint:css` runs stylelint over all the scss code in `assets/css`, using the rules in [.stylelintrc.json.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/.stylelintrc.json)
+-   `lint:js` runs eslint over all the JavaScript, using the rules in [.eslintrc.js.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/.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.
+
+## Running the Blocks plugin
+
+To run the Blocks plugin you'll need a WordPress development environment - e.g. [`VVV`](https://varyingvagrantvagrants.org) or [`docker`](https://www.docker.com).
+
+-   Ensure the repo folder is in the `wp-content/plugins` folder of your WordPress environment.
+-   Activate the `WooCommerce Blocks` plugin (should be dev version, e.g. `2.6.0-dev`).
+-   Edit a page or post in block editor - you should see WooCommerce blocks in the block inserter!
+
+## Developer Tools (Visual Studio Code)
+
+We recommend configuring your editor to automatically check for syntax and lint errors. This will help you save time as you develop by automatically fixing minor formatting issues.
+
+Here are some directions for setting up Visual Studio Code (most tools are also available for other editors).
+
+### EditorConfig
+
+[EditorConfig](https://editorconfig.org/) defines a standard configuration for setting up your editor, for example using tabs instead of spaces. You should install the [EditorConfig for VS Code extension](https://marketplace.visualstudio.com/items?itemName=editorconfig.editorconfig) and it will automatically configure your editor to match the rules defined in the Blocks plugin repository `.editorconfig` file.
+
+### ESLint
+
+[ESLint](https://eslint.org/) statically analyzes the code to find problems. The lint rules are integrated in the continuous integration process and must pass to be able to commit. You should install the [ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for Visual Studio Code (see [eslint docs](https://eslint.org/docs/user-guide/integrations) for more editor integrations).
+
+With the extension installed, ESLint will use the `.eslintrc.js` file in the root of the Blocks plugin repository for formatting rules. It will highlight issues as you code.
+
+### Prettier
+
+[Prettier](https://prettier.io/) is a tool that allows you to define an opinionated format, and automate fixing the code to match that format. Prettier and ESlint are similar, Prettier is more about formatting and style, while ESlint is for detecting coding errors.
+
+To use Prettier, you should install the [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extension in Visual Studio Code. You can then configure it to be the default formatter and to automatically fix issues on save, by adding the following to your settings.
+
+```
+"[javascript]": {
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true
+},
+```
+
+This will use the `.prettierrc.js` file in the root folder of the Blocks plugin repository and the version of Prettier that is installed in the root `node_modules` folder.

plugins/woocommerce-blocks/docs/contributors/javascript-testing.md

@@ -0,0 +1,20 @@
+# JavaScript Testing
+
+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/).
+
+## Running Tests
+
+Assuming you've already followed the [Getting Started Guide](getting-started.md) on setting up node and other dependencies, tests are ran from the command line using the following command:
+
+```
+$ npm run test
+```
+
+The test scripts use [wp-scripts](https://github.com/WordPress/gutenberg/tree/master/packages/scripts) to run jest for component and unit testing.
+
+Additionally,
+
+-   `test:update` updates the snapshot tests for components, used if you change a component that has tests attached.
+-   `test:watch` keeps watch of files and automatically re-runs tests when things change.

plugins/woocommerce-blocks/docs/contributors/smoke-testing.md

@@ -0,0 +1,32 @@
+# Smoke Testing
+
+When testing builds the following things should be tested to ensure critical parts
+of the Blocks plugin are still functional.
+
+## Prerequisites
+
+To make future testing more efficient, we recommend setting up some Blocks in advance so you can repeat tests on them whenever smoke testing.
+
+1. Have a page with all regular and SSR blocks (such as the product grids) setup and configured.
+2. Have a page with the All Products Block, and some Filter Blocks, setup to test that functionality in isolation. Using the columns block here too is a good idea to keep things organized.
+
+## Editor Tests
+
+1. Ensure all WooCommerce Blocks are shown in the Block Inserter.
+2. Check existing Blocks;
+    - Do they look correct?
+    - Can you change options/attributes in the Block inspector?
+    - Are changes persisted on save?
+    - Is the Browser error console free from errors/notices/warnings?
+3. Test inserting various blocks into the editor;
+    - All Products Blocks (this is powered by the Store API)
+    - Featured Product (this is powered by the REST API)
+    - On Sale Products (this is SSR)
+    - Is the Browser error console free from errors/notices/warnings after inserting them?
+    - Do they persist and continue to display correctly after save/refresh?
+
+## Frontend Tests
+
+1. Do the blocks on your pre-made pages render correctly?
+2. Test interaction with blocks, such as the All Products Block and filters.
+3. Is the Browser error console free from errors/notices/warnings?

plugins/woocommerce-blocks/docs/readme.md

@@ -0,0 +1,17 @@
+# WooCommerce Blocks Handbook
+
+The WooCommerce Blocks Handbook provides documentation for designers and developers on how to extend or contribute to blocks, and how internal developers should handle new releases.
+
+## Table of Contents
+
+**Contributing**
+
+-   [Getting Started](contributors/getting-started.md)
+-   [Coding Guidelines](contributors/coding-guidelines.md)
+-   [Smoke Testing](contributors/smoke-testing.md)
+-   [JavaScript Testing](contributors/javascript-testing.md)
+
+**Releases**
+
+-   [Releasing New Versions](releases/readme.md)
+-   [WordPress Update Testing Checklist](releases/wordpress-update-testing-checklist.md)

plugins/woocommerce-blocks/docs/releases/readme.md

@@ -1,10 +1,10 @@
-# Releasing New Versions
+# Releases
 
 This document outlines the process of releasing new versions of the blocks plugin.
 
 ## Prerequisites - what you need to release WooCommerce Blocks
 
--   You should be set up for development - for more info see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+-   You should be set up for development - for more info see [this doc](../contributors/getting-started.md).
 -   Install & set up [GitHub hub](https://hub.github.com) tools.
 -   Configure a GitHub token for release scripts to use.
     -   https://github.com/settings/tokens
@@ -60,9 +60,9 @@ _Outcome_: **Release branch has all relevant changes merged & pushed.**
 
 #### Ensure release branch readme is up to date
 
--   Run changelog script `npm run changelog` to get changelog txt for readme. Changelog content will be output to screen by script.
+-   Run changelog script `$ npm run changelog` to get changelog txt for readme. Changelog content will be output to screen by script.
     -   The above script will automatically generate changelog entries from a milestone (you will be asked about the milestone name in the script).
-    -   If you want to pull changelog entries from a Zenhub release instead, use `npm run changelog:zenhub` and follow instructions.
+    -   If you want to pull changelog entries from a Zenhub release instead, use `$ npm run changelog:zenhub` and follow instructions.
 -   Add changelog section for release, e.g. [`= 2.5.11 - 2020-01-20 =`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/commit/74a41881bfa456a2167a52aaeb4871352255e328).
 -   Copy-paste the changelog content into `readme.txt`.
 -   Make any other changes to readme as needed - e.g. support versions changing, new blocks.
@@ -74,9 +74,9 @@ _Outcome_: **Release branch has `readme.txt` is updated with release details.**
 #### Build zip & smoke test
 
 -   Ensure you are on the tip of the release branch, e.g. `git pull origin release/2.5`
--   Update dependencies – `npm ci`.
+-   Update dependencies – `$ npm ci`.
--   Run a production build - `npm run build`.
+-   Run a production build - `$ npm run build`.
--   Run package script to get a zip to test `npm run package-plugin`.
+-   Run package script to get a zip to test `$ npm run package-plugin`.
 -   Smoke test built release zip:
     -   At least one other person should test the built zip - ask a teammate to help out.
     -   Test in a clean environment, e.g. Jurassic.Ninja site.
@@ -92,7 +92,7 @@ _Outcome_: **Confident that source code is ready for release: intended fixes are
 
 #### Tag release on GitHub
 
--   Prepare tagged release on github `npm run deploy`.
+-   Prepare tagged release on github `$ npm run deploy`.
     -   Note: the script automatically updates version numbers (commits on your behalf).
 -   Edit release, add changelog info to Github release notes.
 -   Check release repo tag is correct - checkout, smoke test/confidence check.
@@ -101,7 +101,7 @@ _Outcomes_: **Version numbers updated in source code & developers can test tagge
 
 #### Release to WPORG
 
--   Run `npm run release`. This script clones a copy of the source code to your home folder, and outputs an `svn` command to push release up to WPORG.
+-   Run `$ npm run release`. This script clones a copy of the source code to your home folder, and outputs an `svn` command to push release up to WPORG.
 -   Push release to WPORG using `svn`.
     -   Run generated svn command to commit to WPORG svn repo.
         -   The command should look like this: `cd /Users/{YOU}/blocks-deployment/woo-gutenberg-products-block-svn && svn ci -m "Release 2.5.11, see readme.txt for changelog."`
@@ -150,8 +150,8 @@ Sometimes, we need to update a single file in WordPress.org without wanting to d
 1. Checkout the plugin repo:
 
 ```
-svn co "http://plugins.svn.wordpress.org/woo-gutenberg-products-block/"
+$ svn co "http://plugins.svn.wordpress.org/woo-gutenberg-products-block/"
-cd woo-gutenberg-products-block
+$ cd woo-gutenberg-products-block
 ```
 
 2. Modify the files you want to change in `trunk` or `tags/x.y.z`.
@@ -159,12 +159,12 @@ cd woo-gutenberg-products-block
 3. Check your changes with:
 
 ```
-svn stat
+$ svn stat
-svn diff
+$ svn diff
 ```
 
 4. Commit the changes to the server:
 
 ```
-svn ci -m "Updated readme.txt description"
+$ svn ci -m "Updated readme.txt description"
 ```

plugins/woocommerce-blocks/docs/releases/wordpress-update-testing-checklist.md

@@ -0,0 +1,24 @@
+# WordPress Update Testing Checklist
+
+Wherever a new version of WordPress is released, or is due for release, there are
+a number of steps that developers should perform in order to ensure compatibility
+exists between WordPress, Gutenberg, and the Blocks plugin.
+
+**Important:** Before testing, ensure you **disable** the **Gutenberg Feature Plugin** to ensure you're using the correct version of the Editor that is shipping with the new version of WordPress.
+
+Additionally, ensure your test environment includes a mixture of existing blocks to ensure any existing blocks work after the update.
+
+## Testing Checklist
+
+1. Run through the [smoke testing checklist](../contributors/smoke-testing.md) to ensure critical features are still functional.
+2. Verify the appearance of blocks on the frontend using the latest official theme. This includes new Twenty-X themes introduced every year.
+
+## Updating `readme.txt`
+
+Once testing is complete and any discovered issues are patched, update the `Tested up to: 5.3` version in readme.txt to match the minor version of WordPress. For example, `5.6`.
+
+If a new fix release is needed to deal with any compatibility problems, any patches, and the readme.txt update, should be cherry picked into the release branch and deployed. See [Releasing Updates](readme.md).
+
+If no changes are needed, and no fix releases are scheduled, you can use an SVN client to update the Stable Tag of the Blocks plugin in trunk (https://plugins.svn.wordpress.org/woo-gutenberg-products-block/trunk/). This will prevent the page on WordPress.org from warning users about incompatibilities.
+
+Instructions for updating specific files on SVN can be [found in this doc](readme.md#appendix-updating-a-specific-file-on-wporg).